You are on page 1of 138

OPC HDA Interface

Version 1.4.1.x 1.4.2.x

OSIsoft, LLC 777 Davis St., Suite 250 San Leandro, CA 94577 USA Tel: (01 510!297!5"00 #a$: (01 510!%57!"1%& 'e(: )tt*:++,,,.osiso-t..o/ 0S1so-t Australia 2 3ert), Australia 0S1so-t 4uro*e 5/(6 2 #ran7-urt, 5er/an8 0S1so-t Asia 3te Ltd. 2 Sin9a*ore 0S1so-t Canada ULC 2 :ontreal ; Cal9ar8, Canada 0S1so-t, LLC <e*resentative 0--i.e 2 S)an9)ai, 3eo*le=s <e*u(li. o- C)ina 0S1so-t >a*an ?? 2 To78o, >a*an 0S1so-t :e$i.o S. De <.L. De C.@. 2 :e$i.o Cit8, :e$i.o 0S1so-t do Arasil Siste/as Ltda. 2 Sao 3aulo, AraBil

03C 6DA 1nter-a.e Co*8ri9)t: C 2005!2014 0S1so-t, LLC. All ri9)ts reserved. Do *art o- t)is *u(li.ation /a8 (e re*rodu.ed, stored in a retrieval s8ste/, or trans/itted, in an8 -or/ or (8 an8 /eans, /e.)ani.al, *)oto.o*8in9, re.ordin9, or ot)er,ise, ,it)out t)e *rior ,ritten *er/ission o- 0S1so-t, LLC. 0S1so-t, t)e 0S1so-t lo9o and lo9ot8*e, 31 Anal8ti.s, 31 3ro.essAoo7, 31 DataLin7, 3ro.ess3oint, Si9/a-ine, Anal8sis #ra/e,or7, 1T :onitor, :CD 6ealt) :onitor, 31 S8ste/, 31 A.tive@ie,, 31 AC4, 31 Alar/@ie,, 31 Aat.)@ie,, 31 Data Servi.es, 31 :anual Lo99er, 31 3ro-ile@ie,, 31 'e(3arts, 3roT<AE, <L1D?, <tAnal8ti.s, <tAaseline, <t3ortal, <t3:, <t<e*orts and <t'e(3arts are all trade/ar7s o0S1so-t, LLC. All ot)er trade/ar7s or trade na/es used )erein are t)e *ro*ert8 o- t)eir res*e.tive o,ners. U.S. 50@4<D:4DT <156TS Use, du*li.ation or dis.losure (8 t)e U.S. 5overn/ent is su(Fe.t to restri.tions set -ort) in t)e 0S1so-t, LLC li.ense a9ree/ent and as *rovided in D#A<S 227.7202, D#A<S 252.227!701%, #A< 12.212, #A< 52.227, as a**li.a(le. 0S1so-t, LLC. 3u(lis)ed: 0"+2011

Table of Contents
Terminology................................................................................................................. vii Chapter 1. Introduction..................................................................................................1
<e-eren.e :anuals............................................................................................ 1 Su**orted #eatures........................................................................................... 2 Dia9ra/ o- 6ard,are Conne.tion......................................................................&

Chapter 2. rinciples of Operation................................................................................!


Trans-or/ations and S.alin9...........................................................................10

Chapter ". Installation Chec#list.................................................................................1$


Data Colle.tion Ste*s.......................................................................................15 1nter-a.e Dia9nosti.s........................................................................................1& Advan.ed 1nter-a.e #eatures...........................................................................17

Chapter %. Interface Installation .................................................................................1!


Da/in9 Conventions and <eGuire/ents..........................................................19 1nter-a.e Dire.tories.........................................................................................20 3160:4 Dire.tor8 Tree...............................................................................20 1nter-a.e 1nstallation Dire.tor8......................................................................20 1nter-a.e 1nstallation 3ro.edure.......................................................................20 1nstallin9 1nter-a.e as a 'indo,s Servi.e........................................................20 1nstallin9 1nter-a.e Servi.e ,it) 31 1nter-a.e Con-i9uration Utilit8....................21 Servi.e Con-i9uration...................................................................................21 1nstallin9 1nter-a.e Servi.e :anuall8............................................................2%

Chapter $. &CO' Configuration.................................................................................2$


03C4nu/ Tool................................................................................................ 25 5eneral Ste*s -or DC0: Con-i9uration...........................................................25 03C 6DA Server <e9istration.....................................................................2&

Chapter (. I)*&+Tool................................................................................................2, Chapter ,. &igital States..............................................................................................2! Chapter -. ointSource ..............................................................................................."1 Chapter !. I oint Configuration...............................................................................""
3oint Attri(utes................................................................................................. %% Ta9............................................................................................................... %% 3ointSour.e.................................................................................................. %4

O C *&+ Interface

iii

3ointT8*e..................................................................................................... %4 Lo.ation1...................................................................................................... %4 Lo.ation2...................................................................................................... %4 Lo.ation%...................................................................................................... %4 Lo.ation4...................................................................................................... %5 Lo.ation5...................................................................................................... %5 1nstru/entTa9..............................................................................................%5 4$Des.......................................................................................................... %& S.an ............................................................................................................ %9 S)utdo,n..................................................................................................... %9 0ut*ut 3oints .................................................................................................. 40 Tri99er :et)od 1 (<e.o//ended ..............................................................40 Tri99er :et)od 2..........................................................................................41 0ut*ut Ti/esta/*s......................................................................................41 31 3oint Con-i9uration Tool..............................................................................41 Con-i9uration Tool Co//and!line 3ara/eters............................................41

Chapter 1.. Startup Command /ile.............................................................................%"


Con-i9urin9 t)e 1nter-a.e ,it) 31 1CU...............................................................4% 03C6DA1nt 1nter-a.e *a9e..........................................................................45 Co//and!line 3ara/eters..............................................................................5% Sa/*le 3103C6DA1nt.(at #ile........................................................................&0

Chapter 11. 0niInt /ailover Configuration..................................................................(1


1ntrodu.tion...................................................................................................... &1 S8n.)roniBation t)rou9) a S)ared #ile (3)ase 2 ............................................&% Con-i9urin9 S8n.)roniBation t)rou9) a S)ared #ile (3)ase 2 ........................&4 Con-i9urin9 Uni1nt #ailover t)rou9) a S)ared #ile (3)ase 2 ...........................&7 Start!U* 3ara/eters....................................................................................&7 #ailover Control 3oints.................................................................................&9 31 Ta9s......................................................................................................... 70 Detailed 4$*lanation o- S8n.)roniBation t)rou9) a S)ared #ile (3)ase 2 ......74 Stead8 State 0*eration................................................................................75 #ailover Con-i9uration Usin9 31 1CU................................................................77 Create t)e 1nter-a.e 1nstan.e ,it) 31 1CU........................................................77 Con-i9urin9 t)e Uni1nt #ailover Startu* 3ara/eters ,it) 31 1CU......................7" Creatin9 t)e #ailover State Di9ital State Set ...................................................7" Usin9 t)e 31 1CU Utilit8 to .reate Di9ital State Set.......................................79 Usin9 t)e 31 S:T % Utilit8 to .reate Di9ital State Set...................................79 Creatin9 t)e Uni1nt #ailover Control and #ailover State Ta9s (3)ase 2 .........."2

Chapter 12. Interface 1ode Cloc#...............................................................................-" Chapter 1". Security.....................................................................................................-$


'indo,s ......................................................................................................... "5

Chapter 1%. Starting 2 Stopping the Interface ............................................................-,


Startin9 1nter-a.e as a Servi.e........................................................................."7 Sto**in9 1nter-a.e <unnin9 as a Servi.e........................................................."7

Chapter 1$. 3uffering...................................................................................................-!

O C *&+ Interface

iv

')i.) Au--erin9 A**li.ation to Use.................................................................."9 6o, Au--erin9 'or7s.......................................................................................90 Au--erin9 and 31 Server Se.urit8......................................................................90 4na(lin9 Au--erin9 on an 1nter-a.e Dode ,it) t)e 1CU.....................................91 C)oose Au--er T8*e.....................................................................................91 Au--erin9 Settin9s......................................................................................... 92 Au--ered Servers.......................................................................................... 94 1nstallin9 Au--erin9 as a Servi.e...................................................................97

Chapter 1(. Interface &iagnostics Configuration....................................................1.1


S.an Class 3er-or/an.e 3oints....................................................................101 3er-or/an.e Counters 3oints........................................................................104 3er-or/an.e Counters...............................................................................105 3er-or/an.e Counters -or (ot) (HTotal and (S.an Class $ ......................105 3er-or/an.e Counters -or (HTotal onl8.....................................................107 3er-or/an.e Counters -or (S.an Class $ onl8..........................................109 1nter-a.e 6ealt) :onitorin9 3oints.................................................................111 1+0 <ate 3oint................................................................................................ 11& 1nter-a.e Status 3oint.....................................................................................11"

4rror and Informational 'essages...........................................................................121


:essa9e Lo9s................................................................................................ 121 :essa9es....................................................................................................... 121 S8ste/ 4rrors and 31 4rrors..........................................................................125 Uni1nt #ailover S*e.i-i. 4rror :essa9es........................................................12& 1n-or/ational.............................................................................................. 12& 4rrors (3)ase 1 ; 2 ...................................................................................127 4rrors (3)ase 2 .........................................................................................12"

I S&5 Options.......................................................................................................... 12! O C *&+ Server Issues............................................................................................1"1


Aro,sin9 ....................................................................................................... 1%1 Dis.onne.tin9................................................................................................ 1%1

&ebugging................................................................................................................. 1"" Technical Support and 6esources...........................................................................1"$


Ae-ore Iou Call or 'rite -or 6el*...............................................................1%5 6el* Des7 and Tele*)one Su**ort............................................................1%5 Sear.) Su**ort..........................................................................................1%& 4/ail!(ased Te.)ni.al Su**ort.................................................................1%& 0nline Te.)ni.al Su**ort...........................................................................1%& <e/ote A..ess ......................................................................................... 1%7 0n!site Servi.e .......................................................................................... 1%7 ?no,led9e Center......................................................................................1%7 U*9rades.................................................................................................... 1%7

6evision *istory........................................................................................................1"!

O C *&+ Interface

Terminology
To understand this interface manual, you should be familiar with the terminology used in this document. Buffering Buffering refers to an Interface Nodes ability to store temporarily the data that interfaces collect and to forward these data to the appropriate PI Servers. N-Way Buffering If you have PI Servers that are part of a PI ollective, PIBufss supports n!way buffering. N! way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI ollective. "Bufserv also supports n!way buffering to multiple PI Server however it does not guarantee identical archive records since point compressions specs could be different between PI Servers. #ith this in mind, $SIsoft recommends that you run PIBufss instead.% ICU I & refers to the PI Interface onfiguration &tility. The I & is the primary application that you use to configure PI interface programs. 'ou must install the I & on the same computer on which an interface runs. ( single copy of the I & manages all of the interfaces on a particular computer. 'ou can configure an interface by editing a startup command file. )owever, $SIsoft discourages this approach. Instead, $SIsoft strongly recommends that you use the I & for interface management tas*s. ICU Control (n I & ontrol is a plug!in to the I &. #hereas the I & handles functionality common to all interfaces, an I & ontrol implements interface!specific behavior. +ost PI interfaces have an associated I & ontrol. Interface Node (n Interface Node is a computer on which the PI (PI and,or PI S-. are installed, and PI Server programs are not installed. PI API The PI (PI is a library of functions that allow applications to communicate and e/change data with the PI Server. (ll PI interfaces use the PI (PI. PI Collective ( PI ollective is two or more replicated PI Servers that collect data concurrently. ollectives are part of the )igh (vailability environment. #hen the primary PI Server in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your PI clients.

O C *&+ Interface

vii

PIHOME
PIHOME refers to the directory that is the common location for PI 01!bit client applications.

( typical PIHOME on a 01!bit operating system is C:\Program Files\PIPC. ( typical PIHOME on a 23!bit operating system is C:\Program Files (x86)\PIPC. PI 01!bit interfaces reside in a subdirectory of the Interfaces directory under PIHOME. 4or e/ample, files for the 01!bit +odbus 5thernet Interface are in 6PI)$+57\PIPC\Interfaces\Mod !sE. This document uses "PIHOME# as an abbreviation for the complete PIHOME or PIHOME6$ directory path. 4or e/ample, I & files in "PIHOME#\IC%. PIHOME6
PIHOME6$ is found only on a 23!bit operating system and refers to the directory that is the

common location for PI 23!bit client applications. ( typical PIHOME6$ is C:\Program Files\PIPC. PI 23!bit interfaces reside in a subdirectory of the Interfaces directory under PIHOME6$. 4or e/ample, files for a 23!bit +odbus 5thernet Interface would be found in
C:\Program Files\PIPC\Interfaces\Mod !sE.

This document uses "PIHOME# as an abbreviation for the complete PIHOME or PIHOME6$ directory path. 4or e/ample, I & files in "PIHOME#\IC%. PI Me!!age "og The PI message 8og is the file to which $SIsoft interfaces based on &niInt 3.9.:./ and later writes informational, debug and error message. #hen a PI interface runs, it writes to the local PI message log. This message file can only be viewed using the PI;et+sg utility. See the UniInt Interface Message Logging.docx file for more information on how to access these messages. PI #D$ The PI S-. is a library of functions that allow applications to communicate and e/change data with the PI Server. Some PI interfaces, in addition to using the PI (PI, re<uire the use of the PI S-.. PI #erver Node ( PI Server Node is a computer on which PI Server programs are installed. The PI Server runs on the PI Server Node. PI #M% PI S+T refers to PI System +anagement Tools. PI S+T is the program that you use for configuring PI Servers. ( single copy of PI S+T manages multiple PI Servers. PI S+T runs on either a PI Server Node or a PI Interface Node.

O C *&+ Interface

viii

Pi&c'log The &i&c.log file is the file to which $SIsoft applications write informational and error messages. #hen a PI interface runs, it writes to the &i&c.log file. The I & allows easy access to the &i&c.log. Point The PI point is the basic building bloc* for controlling data flow to and from the PI Server. 4or a given timestamp, a PI point holds a single value. ( PI point does not necessarily correspond to a =point> on the foreign device. 4or e/ample, a single =point> on the foreign device can consist of a set point, a process value, an alarm limit, and a discrete value. These four pieces of information re<uire four separate PI points. #ervice ( Service is a #indows program that runs without user interaction. ( Service continues to run after you have logged off from #indows. It has the ability to start up when the computer itself starts up. The I & allows you to configure a PI interface to run as a Service. %ag (In&ut %ag and Out&ut %ag) The tag attribute of a PI point is the name of the PI point. There is a one!to!one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms =tag> and =point> interchangeably. Interfaces read values from a device and write these values to an Input Tag. Interfaces use an $utput Tag to write a value to the device.

O C *&+ Interface

i7

Chapter 1.

Introduction

The PI $P )-( Interface is an $P )-( $+ interface for bi!directional data transfer between an $P )-( Server and an $SIsoft PI System. The interface accesses data from the $P )-( Server. The design of the interface allows running multiple instances of the interface simultaneously. 5ach interface is able to connect with only one $P )-( Server, which may be on the same or a different machine. +ore than one interface may be configured to connect to the same $P )-( Server. The interface may reside on a PI home node or a PI Interface node. This interface is designed only for an Intel platform. It re<uires both the PI (PI and the PI S-..
1ote8 T)e value o- J3160:4K varia(le -or t)e %2!(it inter-a.e ,ill de*end on ,)et)er t)e inter-a.e is (ein9 installed on a %2!(it o*eratin9 s8ste/ ( C:\Program Files\PIPC or a &4!(it o*eratin9 s8ste/ (C:\Program Files (x86)\PIPC . T)e value o- J3160:4&4K varia(le -or a &4!(it inter-a.e ,ill (e C:L3ro9ra/ #ilesL313C on t)e &4!(it 0*eratin9 s8ste/. 1n t)is do.u/entation J3160:4K ,ill (e used to re*resent t)e value -or eit)er J3160:4K or J3160:4&4K. T)e value o- J3160:4K is t)e dire.tor8 ,)i.) is t)e .o//on lo.ation -or 31 .lient a**li.ations.

1ote8 T)rou9)out t)is /anual t)ere are re-eren.es to ,)ere /essa9es are ,ritten (8 t)e inter-a.e ,)i.) is t)e 313C.lo9. T)is inter-a.e )as (een (uilt a9ainst a oUni1nt version (4.5.0.59 and later ,)i.) no, ,rites all its /essa9es to t)e lo.al 31 :essa9e lo9. 3lease note t)at an8 *la.e in t)is /anual ,)ere it re-eren.es 313C.lo9 s)ould no, re-er to t)e lo.al 31 /essa9e lo9. 3lease see t)e do.u/ent UniInt Interface Message Logging.docx in t)e M3160:4ML1nter-a.esLUni1nt dire.tor8 -or /ore details on )o, to a..ess t)ese /essa9es.

6eference 'anuals
O#I!oft PI Server manuals PI API Installation manual UniInt Interface User Manual

O C *&+ Interface

*endor The $P standards are available from the $P 4oundation at http?,,www.opcfoundation.org. This interface uses the $P )istorical -ata (ccess Specification @ersion A.1:

Supported /eatures
/eature 3art Du/(er N 3lat-or/s 'indo,s O3 %2!(it 0S &4!(it 0S 'indo,s 200% Server %2!(it 0S &4!(it 0S 'indo,s @ista %2!(it 0S &4!(it 0S 'indo,s 200" %2!(it 0S 'indo,s 200" <2 &4!(it 0S 'indo,s 7 %2!(it 0S &4!(it 0S Auto Creates 31 3oints 3oint Auilder Utilit8 1CU Control 31 3oint T8*es Su(!se.ond Ti/esta/*s Su(!se.ond S.an Classes Auto/ati.all8 1n.or*orates 31 3oint Attri(ute C)an9es 4$.e*tion <e*ortin9 N0ut*uts -ro/ 31 1n*uts to 31: S.an!(ased + Unsoli.ited + 4vent Ta9s Su**orts Euestiona(le Ait Su**orts :ulti!.)ara.ter 3ointSour.e :a$i/u/ 3oint Count N Uses 31 SD? Ies Ies (4/ulation :ode A3S Conne.tor Ies Ies #loat1& + #loat%2 + #loat&4 + 1nt1& + 1nt%2 + Di9ital + Strin9 Ies Ies Ies Done (8 inter-a.e Ies S.an!(ased + Unsoli.ited + 4vent Ta9s Ies Ies Unli/ited Ies Do Do Ies (4/ulation :ode Do Ies Do Ies Ies (4/ulation :ode Do Do Ies Ies (4/ulation :ode Do Do Ies Ies (4/ulation :ode Do Do Support 31!1D!0S!03C6DA!DT %2!(it 1nter-a.e &4!(it 1nter-a.e

O C *&+ Interface

/eature 31Det Strin9 Su**ort N Sour.e o- Ti/esta/*s N 6istor8 <e.over8 N Uni1nt!(ased Dis.onne.ted Startu* N SetDevi.eStatus #ailover N @endor So-t,are <eGuired on 31 1nter-a.e Dode + 31Det Dode @endor So-t,are <eGuired on #orei9n Devi.e @endor 6ard,are <eGuired Additional 31 So-t,are 1n.luded ,it) 1nter-a.e Devi.e 3oint T8*es Serial!Aased 1nter-a.e

Support Do 03C 6DA Server Ies Ies Do Ies Uni1nt #ailover (3)ase 2 'ar/ , Cold P Server! level -ailover Do Ies Do Ies See (elo, Do

* See available paragraphs below for further explanation. Platfor+! The Interface is designed to run on the above mentioned +icrosoft #indows operating systems. Out&ut! fro+ PI The $P )-( Server must have the method? Sync&pdate??InsertBeplace implemented for outputs from PI to wor*. Not all $P )-( Servers implement this optional method. )oneywell 5/perion $P )-( Server does not implement this method. U!e! PI #D$ The PI S-. and the PI (PI are bundled together and must be installed on each PI Interface node. This Interface does not specifically ma*e PI S-. calls. #ource of %i+e!ta+&! The interface uses the timestamps from the $P )-( Server. The timestamps will be adCusted to the time difference from the $P )-( Server and the PI Server. It is possible to use the ,TS& command!line parameter to adCust this behavior of the interface. ,TS& is an option that must be selected with caution. #ith this option, the timestamps received from the $P )-( Server will be sent to the PI Server directly without any adCustments. If the $P Server time is ahead of the PI Server time, this option will result in the PI Server receiving timestamps that are in the future. onse<uently, the data will not be written to the PI Server. The user should select this option only if the cloc* settings on both servers are appropriate "i.e. either the same or the PI Server cloc* is ahead% and the cloc*s are either automatically synchroniDed or cloc* chec*s are made fre<uently. If the user is getting error !AA:3E in the pipc.log file, the cloc*s on the PI Server and on the interface node must

O C *&+ Interface

"

Introduction be chec*ed. This error will occur when the interface has sent a timestamp that is outside of the range for the PI archives. Hi!tory ,ecovery )istory recovery is performed at interface startup and when the connection to the $P )-( Server has been re!established after a loss of connection. $n a per!point basis "for both scanned and event tags%, the interface will use the timestamp of the last good PI (rchive value or the ,hiF/ command!line parameter, whichever is closer to the current time, to determine how far bac* in time to retrieve data. In this conte/t a =good> PI (rchive value means one that is not a system digital state. System digital state values within the history recovery time period are deleted from PI. UniInt--a!ed &niInt stands for &niversal Interface. &niInt is not a separate product or fileG it is an $SIsoft!developed template used by developers, and is integrated into many interfaces, including this interface. The purpose of &niInt is to *eep a consistent feature set and behavior across as many of $SIsofts interfaces as possible. It also allows for the very rapid development of new interfaces. In any &niInt!based interface, the interface uses some of the &niInt!supplied configuration parameters and some interface!specific parameters. &niInt is constantly being upgraded with new options and features. The UniInt Interface User Manual is a supplement to this manual. #etDevice#tatu! The Interface is built with a version of &NIINT that is higher than 3.0.:./ and that supports interface health points. The health point with the point attribute 5/desc F 6&IH-5@ST(T7, is used to represent the status of the source devices. The following events can be written to the point? =;ood> The interface is properly communicating and reading data from the devices. If no data collection points have been defined, this indicates the interface has successfully started. =0 I A devices"s% in error = The interface has determined that the listed device"s% are offline. ( device is considered offline when the connection to the )-( Server has failed. Please refer to the UniInt Interface User Manual for more information on how to configure interface health points. .ailover Server!8evel 4ailover This interface supports server!level failover which allows the interface to continue to collect data from the currently active $P )-( server when two servers are running in unison and the primary server shutdown or an une/pected communication failure occurs. &niInt 4ailover Support

&niInt Phase 1 4ailover provides support for cold, warm, or hot failover configurations. The Phase 1 hot failover results in a no data loss solution for bi! directional data transfer between the PI Server and the -ata Source given a single point of failure in the system architecture similar to Phase A. )owever, in warm and cold failover configurations, you can e/pect a small period of data loss during a single point of failure transition. This failover solution re<uires that two copies of the interface be installed on different interface nodes collecting data simultaneously from a single data source. Phase 1 4ailover re<uires each interface have access to a shared data file. 4ailover operation is automatic and operates with no user interaction. 5ach interface participating in failover has the ability to monitor and determine liveliness and failover status. To assist in administering system operations, the ability to manually trigger failover to a desired interface is also supported by the failover scheme. The failover scheme is described in detail in the UniInt Interface User Manual, which is a supplement to this manual. -etails for configuring this Interface to use failover are described in the &niInt 4ailover onfiguration section of this manual. *endor #oft/are ,e0uired The $P )-( Server may run on the same system as the interface, or it may run on another system. Additional PI #oft/are The PI )-( Tool is an $SIsoft product that ships with the interface to assist in configuring and troubleshooting of the interface. Device Point %y&e! By default, the interface will re<uest the following data types?
I ointType Di9ital 1nt1& 1nt%2 #loat%2 #loat&4 Strin9 O C *&+ Server &ata Type 2!(8te 1nte9er (@TH12 2!(8te 1nte9er (@TH12 4!(8te 1nte9er (@TH14 4!(8te #loat (@TH<4 "!(8te #loat (@TH<" Strin9 (@THAST<

O C *&+ Interface

Introduction

&iagram of *ard9are Connection


Configuration 12 Preferred Configuration This configuration is the simplest and allows data buffering on the interface node.

Configuration 32 Co++on Configuration This configuration allows data buffering on the interface node and it is recommended to have all machines in the same domain.

O C *&+ Interface

Introduction Configuration 42 Alternate Configuration This configuration is possible, but not the preferred configuration. )aving the interface and the PI server compete for resources can impair efficiency.

1ote8 All .on-i9urations reGuire DC0: settin9s, and it is re.o//ended usin9 (u--erin9 even ,)en t)e inter-a.e runs on t)e 31 Server node.

Chapter 2.

rinciples of Operation

The PI $P )-( Interface is an $P )-( client that allows the PI System and other software applications to e/change data across a networ*. -uring installation of the interface, entries are put into the #indows Begistry, which then allows the #indows system to locate the $P )-( Server whenever the client wants to connect to it. If the PI $P )-( Interface and an $P )-( Server are running on different machines, the $P 5num tool can be used to locate those registry entries on the other machine. (t interface startup the PI $P )-( Interface attempts connection to both the $P )-( Server and the PI Server. If $P )-( server is unavailable, the interface will attempt to connect every 9 seconds until successful. If the PI Server is unavailable, the interface will attempt to connect every 2: seconds. (fter connection to both servers is successfully established, the interface periodically chec*s its node cloc* against that of the $P )-( Server and against that of the PI Server, to eliminate any differences due to cloc* drift. The interface goes on to identify the PI tags associated with the instance of the interface, based on the PointSource and 8ocationA point attributes. The interface will ma*e sure that each of these PI tags is properly configured so that it *nows what data to collect from the $P )-( Server. (n incorrectly configured tag is reCected and a message is sent to the log file. $nce the properly configured PI tags are identified, the interface will perform history recovery before entering the data collection mode. The interface will use the timestamp of the last good PI (rchive value or the ,hiF/ command! line parameter, whichever is closer to the current time, to determine how far bac* in time to retrieve data. The interface supports the SyncBead??BeadBaw and SyncBead??BeadProcessed method. This re<uires setting up scan classes to control how fre<uently to collect data from the $P )-( server. 4or 5vent reads, the PI Server informs the interface when the trigger point has a new event "not necessarily a change in value%, and the interface sends a synchronous Bead for the tags attached to that trigger. (ll data since the last read will be processed using the SyncBead??BeadBaw method. If communication between the interface and the $P )-( Server is lost, the interface will periodically try to reestablish the connection. (ll the historical data for when the connection was down will be recovered after communication is re!established and then data collection will resume. If communication between the interface and the PI Server is lost, the interface will still collect data and the interface will periodically attempt to re!establish communication. If PI (PI Buffering is enabled, no data is lost. If buffering is not enabled data is lost. -uring data collection all data stored in the history database since the last scan will be read during the current scan. 4or e/ample, if a tag is in a scan class of A minute, and data goes

O C *&+ Interface

into the history database on the $P )-( Server every A: seconds, 2 values will be read and processed for each scan. Sync&pdate??InsertBeplace method is used for outputs from PI to the )-( Server. This function inserts or replaces values and <ualities in the )-( for the timestamp of the sourcetag. If the item has a value at the specified timestamp, the new value and <uality will replace the old one. If there is no value at that timestamp, the function will insert the new data. If the soucetags value is a system digital state "e.g., io timeout, shutdown,J%, the output will not be done. The <uality of the data sent to the )-( will be set to =;ood>. PI tag configurations can be updated K added, edited, or deleted K while the interface is running and these changes will be pic*ed up by the interface automatically. In general, the interface will chec* for tag updates every 1 minutes. )owever, if it finds that at least 19 tags have been updated, it will chec* again in 0: secondsG otherwise it will wait another 1 minutes before chec*ing again. #ith some $P )-( servers, this operation can re<uire more time and more system resources. Therefore, it is more efficient to stop and restart the interface if a large number of tags are edited. The PI $P )-( Interface is designed to send messages about its operation to the pipc.log file. This file will contain the following information about the interface? Informational messages on interface startup and shutdown The scan rates for each scan class ( count of the Input points in each scan class and the number of $utput points 5rror messages for reCected PI tags or error messages from the $P )-( Server Notification for all connections and disconnections from the $P )-( server
1ote: T)e 31 03C 6DA 1nter-a.e .an (e .on-i9ured to run on t)e sa/e s8ste/ as t)e 03C 6DA Server, 31 Server or on anot)er node. T)e .on-i9uration a--e.ts t)e s*e.i-i. s8ste/ settin9s needed -or t)e inter-a.e to (e installed and *er-or/ .orre.tl8. T)ere-ore, it is .ru.ial to 7no, t)e o*erational details o- t)e inter-a.e *resented in t)is se.tion (e-ore installin9 and runnin9 it.

Transformations and Scaling


#hile $P Servers can perform their own transformations and scaling, some users have found that the desired functions are not filled by their server. In this case, configure the PI points so that the interface will perform transformations and scaling. Note that transformation and scaling happens before the value is compared to the e/ception parameters for the tag, so the e/ception parameters are applied to the value that would be sent to PI, rather than to the raw value. The Transformation and Scaling calculations are the same as the PI$P interface. #caling Scaling is fairly comple/ and is controlled by the 'otalCode and ()!are*oot properties of the tag. Since were limited in what information we can get about the tag, the Con+ers attribute is used to carry the Span of the device, and the Ex,esc does further duty to carry the device Lero "-Dero%. The interface can then translate a value from the scale of what the device can send to the scale of the actual tag.

O C *&+ Interface

1.

If 'otalCode is Dero, the only scaling performed is based on the value of ()!are*oot. If S<uare Boot is a A, the value read will be s<uared before sending it to PI, and for an output value the s<uare root will be ta*en before writing to the device. If ()!are*oot is a 1, the opposite happens? for values read from the device, the s<uare root of the value read will be sent to PI, while output values will be s<uared before sending them to the device. If 'otalCode is non!Dero, some other scaling may be performed, either to transform the value read into another scale of measurement or to apply an offset or conversion factor. Must as the value stored in the tag ranges from "Lero% to "Lero N Span%, so too the values read from or written to the device can range from "-Dero% to "-Dero N onvers%. This allows the value stored in PI to be a simple transformation from one scale to another. The ()!are*oot attribute can be used to specify that the s<uare or s<uare root of the value should be used rather than the value itself. In other cases, the Con+ers value may be added to or subtracted from the value, or may be used as a multiplier, or applied as a bit mas*. (gain, the ()!are*oot attribute may specify using the s<uare or s<uare root of the value, rather than the raw value, as the input to the formula. Scaling is only supported for numeric tags. ( tag may be defined in PI as a number, yet the $P Server reads and writes the Item as a string, and those tags would support scaling. But if the PI tag is defined as a string, any scaling will be ignored. The table below covers all the scaling formulas currently used. (gain, if ()!are*oot is a A or a 1, the s<uare root or s<uare of the value will be calculated first, and then the formula will be applied.
Convers TotalCode S:uare6oot &;ero Operation

0 0

0 0

0 1

Dont care Dont care

Value = value Input tags: Value = (Value)2 Output tags: Value = (Value)0.5 Input tags: Value = (Value)0.5 Output tags: Value = (Value)2 Input tags: Value = ! (Value " D#ero) $ %onvers & ' (pan ) *ero Output tags: Value = ! (Value " *ero) $ (pan& ' %onvers ) D#ero Input tags: Value = ! ((Value)2 " D#ero) $ %onvers & ' (pan ) *ero Output tags: Value = ! ((Value)0.5 " *ero) $ (pan& ' %onvers ) D#ero

Dont care

Not 0

Define

Not 0

Define

O C *&+ Interface

11

rinciples of Operation
Convers TotalCode S:uare6oot &;ero Operation

Not 0

Define

Input tags: Value = ! ((Value)0.5 " D#ero) $ %onvers & ' (pan ) *ero Output tags: Value = ! ((Value)2 " *ero) $ (pan& ' %onvers ) D#ero Input tags: Value = Value ' %onvers Output tags: Value = Value $ %onvers Input tags: Value = (Value)2 ' %onvers Output tags: Value = (Value)0.5 $ %onvers Input tags: Value = (Value)0.5 ' %onvers Output tags: Value = (Value)2 $ %onvers Input tags: Value = (Value $ %onvers) " D#ero Output tags: Value = (Value ) D#ero) ' %onvers Input tags: Value = ((Value)2 $ %onvers) " D#ero Output tags: Value = ((Value)0.5 ) D#ero) ' %onvers Input tags: Value = ((Value)0.5 $ %onvers) " D#ero Output tags: Value = ((Value)2 ) D#ero) ' %onvers Input tags: Value = (Value " D#ero)$ %onvers Output tags: Value = (Value ' %onvers) ) D#ero

Not 0

Dont care

Not 0

Dont care

Not 0

Dont care

Not 0

Define

Not 0

Define

Not 0

Define

Not 0

Define

12

Convers

TotalCode

S:uare6oot

&;ero

Operation

Not 0

Define

Input tags: Value = ((Value)2 " D#ero)$ %onvers Output tags: Value = ((Value)0.5 ' %onvers) ) D#ero Input tags: Value = ((Value)0.5 " D#ero)$ %onvers Output tags: Value = ((Value)2 ' %onvers) ) D#ero Input tags: Value = Value ) %onvers Output tags: Value = Value " %onvers Input tags: Value = (Value)2 ) %onvers Output tags: Value = (Value)0.5 " %onvers Input tags: Value = (Value)0.5 ) %onvers Output tags: Value = (Value)2 " %onvers Input tags: Value = Value .ND %onvers Output tags: Value = Value .ND %onvers Input tags: Value = Value O0 %onvers Output tags: Value = Value O0 %onvers Input tags: Value = Value 2O0 %onvers Output tags: Value = Value 2O0 %onvers

Not 0

Define

Not 0

Dont care

Not 0

Dont care

Not 0

Dont care

Not 0

Dont care

Dont care

Not 0

Dont care

Dont care

Not 0

Dont care

Dont care

UniInt .ailover This interface supports &niInt failover. Befer to the &niInt 4ailover onfiguration section of this document for configuring the interface for failover.

O C *&+ Interface

1"

Chapter ".

Installation Chec#list

If you are familiar with running PI data collection interface programs, this chec*list helps you get the Interface running. If you are not familiar with PI interfaces, return to this section after reading the rest of the manual in detail. This chec*list summariDes the steps for installing this Interface. 'ou need not perform a given tas* if you have already done so as part of the installation of another interface. 4or e/ample, you only have to configure one instance of Buffering for every Interface Node regardless of how many interfaces run on that node. The -ata ollection Steps below are re<uired. Interface -iagnostics and (dvanced Interface 4eatures are optional.

&ata Collection Steps


A. onfirm that you can use PI S+T to configure the PI Server. 'ou need not run PI S+T on the same computer on which you run this Interface.

1. If you are running the Interface on an Interface Node, edit the PI Servers Trust Table to allow the Interface to write data. 0. Bun the installation *it for the PI Interface onfiguration &tility "I &% on the interface node. This *it runs the PI S-. installation *it, which installs both the PI (PI and the PI S-.. 3. Bun the installation *it for this Interface. . 9. If you are running the Interface on an Interface Node, chec* the computers time Done properties. (n improper time Done configuration can cause the PI Server to reCect the data that this Interface writes. 2. Bun the I & and configure a new instance of this Interface. 5ssential startup parameters for this Interface are Point Source (/PS=x) Interface ID (/ID=#) PI Server (/Host=host:port) Scan Class (/F=##:##:##,offset) O. &se the onnection Tool to confirm connection between the Interface Node and the device. P. If you will use digital points, define the appropriate digital state sets. E. Build input tags and, if desired, output tags for this Interface. Important point attributes and their use are?

O C *&+ Interface

1$

-ocation. specifies the Interface instance I-ocation/ specifies whether to store the <uality or value. If location1FA, interface

stores point <uality rather than point value.


-ocation0 specifies tag type "either scanned or output%. If location0F:, the point is

an input tagG if location0F1, the point is an output tag.


-ocation$ specifies the scan class. -ocation1 specifies treatment of data with uncertain <uality?

o o o

If location9F:, interface flags data with uncertain <uality as <uestionable when sending to PI. If locatation9FA, interface sets the digital state of data with uncertain <uality to =Bad Quality.>

If location9F1, interface treats data with uncertain <uality as good <uality and does not flag the data. Ex,esc specifies long ItemI-. Instr!ment'ag specifies ItemI- for the tag "unless specified in Ex,esc%. A:. Start the Interface interactively and confirm its successful connection to the PI Server without buffering. AA. onfirm that the Interface collects data successfully. A1. Stop the Interface and configure a buffering application "either Bufserv or PIBufss%. #hen configuring buffering use the I & menu item Tools BufferingJ Buffering Settings to ma*e a change to the default value "012OP% for the Primary and Secondary +emory Buffer SiDe "Bytes% to 1::::::. This will optimiDe the throughput for buffering and is recommended by $SIsoft. A0. Start the buffering application and the Interface. onfirm that the Interface wor*s together with the buffering application by either physically removing the connection between the Interface Node and the PI Server Node or by stopping the PI Server. A3. onfigure the Interface to run as a Service. onfirm that the Interface runs properly as a Service.

A9. Bestart the Interface Node and confirm that the Interface and the buffering application restart.

Interface &iagnostics
A. onfigure Scan lass Performance points. 1. Install the PI Performance +onitor Interface "4ull @ersion only% on the Interface Node. 0. 3. 9. O. onfigure Performance ounter points. onfigure &niInt )ealth +onitoring points onfigure the I,$ Bate point. onfigure the Interface Status point.

2. Install and configure the Interface Status &tility on the PI Server Node.

O C *&+ Interface

1(

+dvanced Interface /eatures


A. onfigure &niInt 4ailoverG see that section in this document for details related to configuring the interface for failover.

O C *&+ Interface

1,

Chapter %.

Interface Installation

$SIsoft recommends that interfaces be installed on a PI Interface Nodes instead of directly on the PI Server node. ( PI Interface Node is any node other than the PI Server node where the PI (pplication Programming Interface "PI (PI% has been installed "see the PI (PI manual%. #ith this approach, the PI Server need not compete with interfaces for the machines resources. The primary function of the PI Server is to archive data and to service clients that re<uest data. (fter the interface has been installed and tested, Buffering should be enabled on the PI Interface Node. Buffering refers to either PI (PI Buffer Server "Bufserv% or the PI Buffer Subsystem "PIBufss%. 4or more information about Buffering see the Buffering section of this manual. In most cases, interfaces on PI Interface Nodes should be installed as automatic services. Services *eep running after the user logs off. (utomatic 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 &pdate +anager and PI Networ* +anager services. This typical scenario assumes that Buffering 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 conCunction with PI, but it is not standard practice to enable buffering on the PI Server node. The PI Buffer Subsystem can also be installed on the PI Server. See the UniInt Interface User Manual for special procedural information.

1aming Conventions and 6e:uirements


In the installation procedure below, it is assumed that the name of the interface e/ecutable is PIOPCH,2Int.exe and that the startup command file is called PIOPCH,2Int. at. W5en Configuring t5e Interface Manually It is customary for the user to rename the e/ecutable and the startup command file when multiple copies of the interface are run. 4or e/ample, PIOPCH,2Int..exe and PIOPCH,2Int.. at would typically be used for interface number A, PIOPCH,2Int/.exe and PIOPCH,2Int/. at for interface number 1, and so on. #hen an interface is run as a service, the e/ecutable and the command file must have the same root name because the service loo*s for its command!line parameters in a file that has the same root name.

O C *&+ Interface

1!

Interface &irectories
I*O'4 &irectory Tree
"2<bit Interfaces The 6PIHOME7 directory tree is defined by the PIHOME entry in the &i&c.ini configuration file. This &i&c.ini file is an (S II te/t file, which is located in the 34indir3 directory. 4or 01!bit operating systems a typical &i&c.ini file contains the following lines?
"PIPC# PIHOME5C:\Program Files\PIPC

4or 23!bit operating systems a typical &i&c.ini file contains the following lines?
"PIPC# PIHOME5C:\Program Files (686)\PIPC

The above lines define the root of the PIHOME directory on the ? drive. The PIHOME directory does not need to be on the ? drive. $SIsoft recommends using the paths shown above as the root PIHOME directory name.

Interface Installation &irectory


The interface install *it will automatically install the interface to?
PIHOME\Interfaces\OPCH,2Int PIHOME is defined in the &i&c.ini file.

( new interface installation will create two subdirectories? PI!$P Tools and PIH)-(Tool. Installed in the PI)$+5 directory, the PIH)-(Tool directory is a subdirectory of the PI! $P Tools directory?
PIHOME\PI7OPC 'ools\PI8H,2'ool

Interface Installation rocedure


The PI $P )-( Interface setup program uses the services of the +icrosoft #indows Installer. #indows Installer is a standard part of #indows 1::: and greater operating systems. To install, run the appropriate installation *it.

Installing Interface as a =indo9s Service


The PI $P )-( Interface service can be created, preferably, with the PI Interface onfiguration &tility, or can be created manually.

O C *&+ Interface

2.

Installing Interface Service 9ith I Interface Configuration 0tility


The PI Interface onfiguration &tility provides a user interface for creating, editing, and deleting the interface service?

Service Configuration
Service name The Service name bo/ shows the name of the current interface service. This service name is obtained from the interface e/ecutable. I& This is the service id used to distinguish multiple instances of the same interface using the same e/ecutable. &isplay name The ispla! "ame te/t bo/ shows the current -isplay Name of the interface service. If there is currently no service for the selected interface, the default -isplay Name is the service name with a =PI!> prefi/. &sers may specify a different -isplay Name. $SIsoft suggests that the prefi/ =PI!> be appended to the beginning of the interface to indicate that the service is part of the $SIsoft suite of products.

O C *&+ Interface

21

Interface Installation Log on as The Log on as te/t bo/ shows the current =8og on as> #indows &ser (ccount of the interface service. If the service is configured to use the 8ocal System account, the Log on as te/t bo/ will show =8ocalSystem.> &sers may specify a different #indows &ser account for the service to use. ass9ord If a #indows &ser account is entered in the Log on as te/t bo/, then a password must be provided in the Password te/t bo/, unless the account re<uires no password. Confirm pass9ord If a password is entered in the Password te/t bo/, then it must be confirmed in the #onfirm Password te/t bo/. &ependencies The 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 ependencies list using the button. 4or e/ample, if (PI 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 ependencies list. button, and the service name will be removed from the

#hen the 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 interface service will not run.
1ote8 3lease see t)e 31 Lo9 and 'indo,s 4vent Lo99er -or /essa9es t)at /a8 indi.ate t)e .ause -or an8 servi.e not runnin9 as e$*e.ted.

< Add 3utton To add a dependency from the list of Installed services, select the dependency name, and clic* the Add button.

< ,e+ove 3utton To remove a selected dependency, highlight the service name in the ependencies list, and clic* the $emove button. The full name of the service selected in the Installed services list is displayed below the Installed services list bo/. Startup Type The Startup %!pe indicates whether the interface service will start automatically or needs to be started manually on reboot.

22

If the (uto option is selected, the service will be installed to start automatically when the machine reboots. If the +anual option is selected, the interface service will not start on reboot, but will re<uire someone to manually start the service. If the -isabled option is selected, the service will not start at all. ;enerally, interface services are set to start automatically. Create The #reate button adds the displayed service with the specified specified Startup %!pe. 6emove The $emove 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 Service The toolbar contains a Start button and a Stop button . 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 I & dialog. ependencies and with the

Status of the I &

Status of the Interface Service

Service installed or uninstalled

Installing Interface Service 'anually


)elp for installing the interface as a service is available at any time with the command?
PIOPCH,2Int.exe 9:el&

$pen a #indows command prompt window and change to the directory where the PIOPCH,2Int..exe e/ecutable is located. Then, consult the following table to determine the appropriate service installation command.
=indo9s Service Installation Commands on a I Interface 1ode or a I Server 1ode 9ith 3ufserv implemented :anual servi.e Auto/ati. servi.e NAuto/ati. servi.e ,it) servi.e id

PIOPCH,2Int.e$e !install !de*end Qt.*i* (u-servQ PIOPCH,2Inte$e !install !auto !de*end Qt.*i* (u-servQ PIOPCH,2Int.e$e !servi.eid O !install !auto !de*end Qt.*i*
(u-servQ

O C *&+ Interface

2"

Interface Installation
=indo9s Service Installation Commands on a I Interface 1ode or a I Server 1ode 9ithout 3ufserv implemented :anual servi.e Auto/ati. servi.e NAuto/ati. servi.e ,it) servi.e id

PIOPCH,2Inte$e !install !de*end t.*i* PIOPCH,2Int.e$e !install !auto !de*end t.*i* PIOPCH,2Int.e$e !servi.eid O !install !auto !de*end t.*i*

R#hen 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. hec* the +icrosoft #indows 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.

2%

Chapter $.

&CO' Configuration

(ll $P )-( servers and clients are based on +icrosofts - $+ technology. - $+ is the networ* connection protocol that allows communication between machines through the networ*. This type of communication re<uires proper - $+ configuration for all - $+ applications. )ence both $P )-( client and server machines must have proper - $+ settings permitting them to securely access one another remotely There are two maCor steps that must be ta*en to properly configure - $+ permissions? A. - $+ configuration for $P )-( Server application on an $P )-( Server nodeG 1. - $+ configuration for default permissions on a PI $P )-( Interface node. The general steps for - $+ configuration are similar. )owever depending on whether the machines are within the same domain or different domains, or even no domain, the se<uence of steps will be different.

O C4num Tool
The $P 4oundation has provided a tool to allow $P )-( clients to locate servers on remote nodes, without having information about those servers in the local registry. This tool is called $P 5num and is freely distributed by the $P 4oundation. The PI $P )-( interface installation installs $P 5num as well. The primary function of $P 5num is to inform or re<uest information from other instances of $P 5num about e/isting $P )-( Servers on the local system. #hen $P 5num is installed, it grants -a!nc: and 2ccess - $+ permission to E+er;one and sets the (uthentication level to <O<E. This allows access to any user who can log on to the system. The permissions can be changed using dcomcnfg.exe. #hile the interface, - $+, and the PIH)-(Tool only re<uire NT 3.: with Service Pac* 0, $P 5num re<uires at least SP3 and Internet 5/plorer 3 or higher be installed. See the PIH)-(Tool documentation for more information about $P 5num and how to use it.

>eneral Steps for &CO' Configuration


- $+ configuration can be done with the - $+ onfiguration utility " dcomcnfg.exe% that comes with the #indows $S. In order to be able to use this utility, the user must be logged in with administrators privileges. This utility allows for the configuration of special security rules for all - $+ obCects on the local node. The - $+ onfiguration utility may loo* slightly different and setting options may differ, depending on the version of the #indows $S.

O C *&+ Interface

2$

4or detail information on how to configure - $+, please refer to the #&M #onfiguration 'uide.pdf found in the 6PI)$+57SPI!$P ToolsS- $+ ;uideS directory.

O C *&+ Server 6egistration


If the PIH)-(Tool does not list the $P )-( server when running the tool on the same machine as the $P )-( Server, register it using the command?
ser+ername.exe 7regser+er (to !nregister !se 9!nregser+er)

This command should wor* for most servers. -o a search on all hard drives for o&c&rox;.dll "this comes with the $P )-( server%. +a*e sure there is only one version on the machine. +ore than one copy of the file should not be a problem if they are all same version. If there are multiple versions, rename all but the latest one and *eep it in the \4innt\s;stem0/ directory. Then register the following -88s. +a*e sure o&c&rox;.dll and o&ccomn8&s.dll e/ist in the \4innt\s;stem0/ directory. Bun
C:=regs+r0/ o&c&rox;.dll

The following dialog bo/ should open?

Then run?
C:=regs+r0/ o&ccomn8&s.dll

The following dialog bo/ should open?

lic* &( to complete this procedure.

O C *&+ Interface

2(

Chapter (.

I)*&+Tool

The $P )-( Interface includes the PIH)-(Tool to help you install and troubleshoot the PI $P )-( Interface and $P )-( Server"s%. The tool consists of an e/ecutable file, PI8H,2'ool.exe, which you can run by double!clic*ing the file name in #indows 5/plorer or +y omputer. The interface installs the tool into the PIHOME\PI OPC 'ools\PI8H,2'ool directory. 'ou can find a manual describing the tool in the same directory. The general purpose of PIH)-(Tool is to verify that a connection from the Interface node can be made to the $P )-( Server and data read and optionally written. If the $P )-( Server is on a different node than the Interface and PIH)-(Tool, $P 5num must be installed on both machines. If a connection cannot be established using the PIH)-(Tool, then the PI $P )-( Interface will also fail to connect to that $P )-( Server. PIH)-(Tool can also be used to read from and write data to the $P )-( Server. If successful in reading data from the $P )-( Server by using the S!nchronous )$ead$aw button in the PIH)-(Tool, the PI $P )-( Interface should also be able to read and write data.
1ote8 1- a(le to .onne.t and read+,rite *oints -ro/+to an 03C 6DA Server ,it) t)e 31H6DATool, (ut not ,it) t)e 1nter-a.e, t)en .)e.7 t)e DC0: settin9s and t)e Userid under ,)i.) t)e inter-a.e is runnin9.

O C *&+ Interface

2,

Chapter ,.

&igital States

This interface does not re<uire any specific digital states. )owever, you must create digital states before creating digital points. 4or more information regarding digital states, refer to the PI Server documentation. Digital #tate #et! PI digital states are discrete values represented by strings. These strings are organiDed in PI as digital state sets. 5ach digital state set is a user!defined list of strings, enumerated from : to n to represent different values of discrete data. 4or more information about PI digital tags and editing digital state sets, see the PI Server manuals. (n interface point that contains discrete data can be stored in PI as a digital tag. ( -igital tag associates discrete data with a digital state set, as specified by the user. #y!te+ Digital #tate #et Similar 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. 4or e/ample, if the interface receives bad data from an interface point, it writes the system digital state ad in&!t to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients. -igital States AE0!01: are reserved for $SIsoft applications.

O C *&+ Interface

2!

Chapter -.

ointSource

The PointSource is a uni<ue, single or multi!character string that is used to identify the PI point as a point that belongs to a particular interface. 4or e/ample, the string *oiler+ may be used to identify points that belong to the M!Int Interface. To implement this, the PointSource attribute would be set to >oiler. for every PI Point that is configured for the M!Int Interface. Then, if /ps=Boiler1 is used on the startup command!line of the M!Int Interface, the Interface will search the PI Point -atabase upon startup for every PI point that is configured with a PointSource of >oiler.. Before an interface loads a point, the interface usually performs further chec*s by e/amining additional PI point attributes to determine whether a particular point is valid for the interface. 4or additional information, see the ?&s parameter. If the PI (PI version being used is prior to A.2./ or the PI Server version is prior to 0.3.0O:./, the PointSource is limited to a single character unless the S-. is being used. Ca!e-!en!itivity for Point#ource Attri-ute The PointSource character that is supplied with the /ps command!line parameter is not case sensitive. That is, /ps=P and /ps=p are e<uivalent. ,e!erved Point #ource! Several subsystems and applications that ship with PI are associated with default PointSource characters. The TotaliDer Subsystem uses the PointSource character ', the (larm Subsystem uses @ and A, Bandom uses *, BampSoa* uses B, and the Performance 5<uations Subsystem uses C. -o not use these PointSource characters or change the default point source characters for these applications. (lso, if a PointSource character is not e/plicitly defined when creating a PI pointG the point is assigned a default PointSource character of -a "PI 0%. Therefore, it would be confusing to use -a as the PointSource character for an interface.
1ote8 Do not use a *oint sour.e .)ara.ter t)at is alread8 asso.iated ,it) anot)er inter-a.e *ro9ra/. 6o,ever it is a..e*ta(le to use t)e sa/e *oint sour.e -or /ulti*le instan.es o- an inter-a.e.

O C *&+ Interface

"1

Chapter !.

I oint Configuration

The PI point is the basic building bloc* for controlling data flow to and from the PI Server. ( single point is configured for each measurement value that needs to be archived.

oint +ttributes
&se the point attributes below to define the PI point configuration for the Interface, including specifically what data to transfer.

Tag
The 'ag attribute "or tagname% is the name for a point. There is a one!to!one correspondence between the name of a point and the point itself. Because of this relationship, PI documentation uses the terms =tag> and =point> interchangeably. 4ollow these rules for naming PI points? The name must be uni<ue on the PI Server. The first character must be alphanumeric, the underscore "H%, or the percent sign "T%. ontrol characters such as linefeeds or tabs are illegal. The following characters also are illegal? R U G V W 6 7 I S X Y C "engt5 -epending on the version of the PI (PI and the PI Server, this Interface supports tags whose length is at most 199 or A:10 characters. The following table indicates the ma/imum length of this attribute for all the different combinations of PI (PI and PI Server versions.
I+ I 1.&.0.2 or )i9)er 1.&.0.2 or )i9)er Aelo, 1.&.0.2 Aelo, 1.&.0.2 I Server %.4.%70.$ or )i9)er Aelo, %.4.%70.$ %.4.%70.$ or )i9)er Aelo, %.4.%70.$ 'a7imum Length 102% 255 255 255

If the PI Server version is earlier than 0.3.0O:./ or the PI (PI version is earlier than A.2.:.1, and you want to use a ma/imum tag length of A:10, you need to enable the PI S-.. See (ppendi/HB for information.

O C *&+ Interface

""

ointSource
The PointSource is a uni<ue, single or multi!character string that is used to identify the PI point as a point that belongs to a particular interface. 4or additional information, see the /ps command!line parameter and the =PointSource> section.

ointType
Typically, device point types do not need to correspond to PI point types. 4or e/ample, 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. The interface supports the 4loatA2, float01, float 23, intA2, int01, digital, and string point types. 4or more information on the individual PointTypes, see PI Server manuals. Note that not all $P )-( Servers will support all these PI point types. Befer to the vendor! supplied documentation for your specific $P )-( Server to determine what point types that server supports. If the point type defined in PI does not match the canonical data type defined in the $P )-( Server, the interface will attempt to translate the data. Try using the PIH)-(Tool to read the point directly from the $P )-( Server, this can help determine whether the PI PointType can be used for the data to be read..

Location1
8ocationA indicates to which copy of the Interface the point belongs. The value of this attribute must match the /id startup parameter.

Location2
4or Input tags? 8ocation1 indicates whether the tag stores the data value or the <uality of the data? : Z Store the data value A Z Store the <uality of the data 4or Output tags? 8ocation 1 indicates whether the tag sends the digital string for digital tags or the ordinal number ":,A,1,J%? : Z Send the ordinal number A Z Send the digital string

Location"
8ocation0 indicates whether this tag is an Input or $utput tag? : or A Z Input 1 Z $utput

O C *&+ Interface

"%

Location%
#can--a!ed In&ut! 4or scan!based data collection, 8ocation3 defines the scan class for the PI point. The scan class determines the fre<uency at which input points are scanned for new values. 4or more information, see the description of the /f parameter in the Startup ommand 4ile section. %rigger--a!ed In&ut!6 Un!olicited In&ut!6 and Out&ut Point! 8ocation 3 should be set to Dero for these points.

Location$
8ocation9 indicates how the point handles data that has the <uality of =&ncertain>? : Z Send =&ncertain> data to PI Server with the <uestionable bit set. A Z Store the digital state =Bad Quality> if the <uality is =&ncertain.> 1 Z Treat =&ncertain> data as good!<uality data. Note that data can have a <uality of ;ood, &ncertain, or Bad. If the <uality is =Bad,> then the digital state =Bad Input> will be sent to PI Server. 7uality Infor+ation The data values from the )-( have a <uality value of either =;ood,> =&ncertain,> or =Bad.> Because the PI archive stores either the <uality or the value, the interface will translate the <ualities that are =&ncertain> to ;$$-ST(T, and set the =<uestionable value> parameter for the data value. This behavior can be changed on a point!by!point basis with the 8ocation9 PI point attribute. Setting 8ocation9FA will cause the interface to store the digital state =Bad Quality> if the <uality is =&ncertain.> If 8ocation9F1, the interface will ignore the =&ncertain> <uality, and treat the value as if it had good <uality. Note? if 8ocation 9 is set to anything other than :, A or 1, the interface will write an error message for that tag and use the location 9 F : setting.
?uality 500D Euestiona(le AAD Location$ @ . value value, *ara/eter di9ital state Location$ @ 1 value di9ital state di9ital state Location$ @ 2 value value di9ital state

'ou can also store the <uality in a separate PI tag, so both the values reported and also the <ualities that came with those values are stored in PI, with no loss of granularity. Setting 8ocation1FA for a tag tells the interface to store the <uality for the associated $P )-( Item, rather than the value. Since $P )-( <ualities are unsigned, 01!bit integers, an Int01 PI tag must receive them. The values are stored in PI without any change, and their status is always ;$$-. To understand what those <uality values represent, please go to http?,,www.$P foundation.org and download the $P )-( -ata (ccess specifications, which contain a brief discussion of <uality data.

InstrumentTag
InstrumentTag contains the ItemI- for the tag. The format of this field depends on your specific $P )-( Server. Befer to the documentation for the specific server to determine

O C *&+ Interface

"$

I oint Configuration the proper format. %his field must exactl! match the point defined on the &P# , A Server . That means punctuation, spaces, uppercase vs. lowercase, and so on. "engt5 -epending on the version of the PI (PI and the PI Server, this Interface supports an Instr!ment'ag attribute whose length is at most 01 or A:10 characters. The following table indicates the ma/imum length of this attribute for all the different combinations of PI (PI and PI Server versions.
I+ I 1.&.0.2 or )i9)er 1.&.0.2 or )i9)er Aelo, 1.&.0.2 Aelo, 1.&.0.2 I Server %.4.%70.$ or )i9)er Aelo, %.4.%70.$ %.4.%70.$ or )i9)er Aelo, %.4.%70.$ 'a7imum Length 102% %2 %2 %2

If the PI Server version is earlier than 0.3.0O:./ or the PI (PI version is earlier than A.2.:.1, and you want to use a ma/imum Instr!ment'ag length of A:10, you need to enable the PI S-.. See (ppendi/ B for information. To verify an ItemI-, use the PIH)-(Tool. If the server supports browsing, use List Servers Tags to see a list of defined ItemI-s. -ouble!clic*ing an ItemI- in the tree will result in the full ItemI- being displayed in the Item field. This is the ItemI- to use in InstrumentTag. If the instrument tag for a point is longer than 01 characters and PI (PI A.2 or better and PI 0.3.0O:/ PI server are not installed, put the InstrumentTag in the 5/ended -escriptor attribute, using the form =instr F whatever.the!$P )-(,serverRneeds>. Note that the InstrumentTag must e/actly match the ItemI- defined on the $P )-( Server. If the InstrumentTag contains a comma, enclose the tagname with double <uote characters "=%, such as?
Instr5D4:ate+er.;o!E or someoneFneedsFD

47&esc
'ou can use the e/tended descriptor attribute for several purposes, such as indicating a point is a performance point, associating a trigger point with an input point, and specifying different ItemI-s for the timestamp and the point value. #hen using the field for multiple purposes, insert a comma between each definition. "engt5 -epending on the version of the PI (PI and the PI Server, this Interface supports an Extended ,escri&tor attribute whose length is at most P: or A:10 characters. The following table indicates the ma/imum length of this attribute for all the different combinations of PI (PI and PI Server versions.
I+ I 1.&.0.2 or )i9)er 1.&.0.2 or )i9)er Aelo, 1.&.0.2 Aelo, 1.&.0.2 I Server %.4.%70.$ or )i9)er Aelo, %.4.%70.$ %.4.%70.$ or )i9)er Aelo, %.4.%70.$ 'a7imum Length 102% "0 "0 "0

"(

If the PI Server version is earlier than 0.3.0O:./ or the PI (PI version is earlier than A.2.:.1, and you want to use a ma/imum Ex,esc length of A:10, you need to enable the PI S-.. See (ppendi/ B for information. Perfor+ance Point! 4or &niInt!based interfaces, the e/tended descriptor is chec*ed for the string =P5B4$B+(N 5HP$INT>. If this character string is found, &niInt treats this point as a performance point. See the section called Scan lass Performance Points. %rigger--a!ed In&ut! 4or trigger!based input points, a separate trigger point must be configured. (n input point is associated with a trigger point by entering a case!insensitive string in the e/tended descriptor "5/-esc% PI point attribute of the input point of the form?
Ge;4ord5trigger8tag8name

where Ge;4ord is replaced by =event> or =trig> and trigger8tag8name is replaced by the name of the trigger point. There should be no spaces in the string. &niInt automatically assumes that an input point is trigger!based instead of scan!based when the Ge;4ord5trigger8tag8name string is found in the e/tended descriptor attribute. (n input is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous Snapshot value to trigger an input, but the timestamp of the new value must be greater than "more recent than% or e<ual to the timestamp of the previous value. This is different than the trigger mechanism for output points. 4or output points, the timestamp of the trigger value must be greater than "not greater than or e<ual to% the timestamp of the previous value. onditions can be placed on trigger events. 5vent conditions are specified in the e/tended descriptor as follows?
E+ent5Htrigger8tag8nameI e+ent8condition

The trigger tag name must be in single <uotes. 4or e/ample,


E+ent5H(in!soidI 2n;c:ange

will trigger on any event to the PI Tag sinusoid as long as the ne/t event is different than the last event. The initial event is read from the snapshot. The *eywords in the following table can be used to specify trigger conditions.
4vent Condition An8.)an9e &escription Tri99er on an8 .)an9e as lon9 as t)e value o- t)e .urrent event is di--erent t)an t)e value o- t)e *revious event. S8ste/ di9ital states also tri99er events. #or e$a/*le, an event ,ill (e tri99ered on a value .)an9e -ro/ 0 to RAad 1n*ut,S and an event ,ill (e tri99ered on a value .)an9e -ro/ RAad 1n*utS to 0. Tri99er on an8 in.rease in value. S8ste/ di9ital states do not tri99er events. #or e$a/*le, an event ,ill (e tri99ered on a value .)an9e -ro/ 0 to 1, (ut an event ,ill not (e tri99ered on a value .)an9e -ro/ R3t CreatedS to 0. Li7e,ise, an event ,ill not (e tri99ered on a value .)an9e -ro/ 0 to RAad 1n*ut.S Tri99er on an8 de.rease in value. S8ste/ di9ital states do not tri99er events. #or e$a/*le, an event ,ill (e tri99ered on a value .)an9e -ro/ 1 to 0, (ut an event ,ill not (e tri99ered on a value .)an9e -ro/ R3t CreatedS to 0. Li7e,ise, an event ,ill not (e tri99ered on a value .)an9e -ro/ 0 to RAad 1n*ut.S Tri99er on an8 non!Bero value. 4vents are not tri99ered ,)en a s8ste/ di9ital state is ,ritten to t)e tri99er ta9. #or e$a/*le, an event is tri99ered on a value

1n.re/ent

De.re/ent

DonBero

O C *&+ Interface

",

I oint Configuration
4vent Condition &escription .)an9e -ro/ R3t CreatedS to 1, (ut an event is not tri99ered on a value .)an9e -ro/ 1 to RAad 1n*ut.S

#ending %i+e!ta+& and Out&ut *alue to Different Ite+ID! Specify the timestamp ItemI- in 5/-esc when you want to write the output value to one ItemI- and the corresponding timestamp to a different ItemI-. In this case, the ItemIspecified in the InstrumentTag field or in the E Desc field as instr5ItemId will contain the value, and the ItemI- specified in the E Desc field will contain the timestamp that goes with that value. (gain, the ItemI- string must match e/actly the ItemI- on the $P Server. There are two formats, depending on the data type of the ItemI- that receives the timestamp.
/ormat Ti/T1te/1D &escription 1nter-a.e ,rites t)e ti/esta/* as a strin9 (@THAST< -or/atted a..ordin9 to t)e +T# settin9 in t)e startu* -ile. 1n t)is -or/at, t)e ti/esta/* /at.)es t)e 31 Server ti/esta/*, and is not adFusted -or di--eren.es in ti/e Bone or da8li9)t savin9 ti/e settin9s. 1nter-a.e ,rites t)e ti/esta/* as a @THDAT4. 1n t)is -or/at, t)e ti/esta/* is in universal (UTC -or/at, and )as no de*enden.8 on t)e ti/e Bone or da8li9)t savin9 ti/e settin9.

DatT1te/1D

The timestamp written to the $P Server is the same timestamp seen on the PI machine when loo*ing at the archive timestamp. %i+e!ta+& #tring! 'ou can only specify one format string for an instance of the interface. If you must process more than one format of timestamp, then you must use more than one copy of the interface. The interface will ma*e a copy of the format string, and will then replace the to*ens with the actual values, to create a string. To read a string, it will loo* for numbers that are in the same position as the to*ens, and use those numbers as values. The to*ens that the interface recogniDes in the ?'F parameter are?
To#en .. 88 /n /on &escription 2!di9it .entur8 2!di9it 8ear 2!di9it /ont) /ont) as a %!.)ara.ter a((reviation, one o- t)e -ollo,in9: >an #e( :ar A*r :a8 >un >ul Au9 Se* 0.t Dov De. 2!di9it da8 2!di9it )our -ro/ 0 to 2% 2!di9it )our -ro/ 0 to 12 2!di9it /inute 2!di9it se.ond %!di9it /illise.onds eit)er A: or 3:

dd )) )r // ss 0 O:

"-

'ou can put the to*ens together in any combination, with anything or nothing between them. #hat matters to the interface is where in the string the to*ens are found. It reads from left to right, loo*ing for a recogniDable to*en. The following table shows some common format strings and e/ample timestamps.
/ormat String ..88+/n+dd ))://:ss.000 dd /on, ..88 )r://:ss O: /n!dd!..88 ))://:ss ))://:ss.000 47ample Timestamp 199"+11+29 15:%2:19.%91 29 Dov, 199" 0%:%2:19 3: 11!29!199" 15:%2:19 15:%2:19.4"2

D8ero for !caled tag! #hen the device returns values that must be scaled to fit the range of values the tag stores "such as scaling from device voltage to temperature in degrees elsius%, store the device Lero in 5/-esc. "The onvers attribute is used to specify the device Span.% The format is for the device Lero is? -DeroFnnnnn.nnn

Scan
By default, the Scan attribute has a value of A, which means that scanning is turned on for the point. Setting the scan attribute to : turns scanning off. If the scan attribute is : when the Interface starts, a message is written to the &i&c.log and the tag is not loaded by the Interface. There is one e/ception to the previous statement. If any PI point is removed from the Interface while the Interface is running "including setting the scan attribute to :%, S (N $44 will be written to the PI point regardless of the value of the Scan attribute. Two e/amples of actions that would remove a PI point from an interface are to change the point source or set the scan attribute to :. If an interface specific attribute is changed that causes the tag to be reCected by the Interface, S (N $44 will be written to the PI point.

Shutdo9n
The Shutdown attribute is A "true% by default. The default behavior of the PI Shutdown subsystem is to write the (H%',OJ< digital state to all PI points when PI is started. The timestamp that is used for the (H%',OJ< events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every A9 minutes, which means that the timestamp for the (H%',OJ< events will be accurate to within A9 minutes in the event of a power failure. 4or additional information on shutdown events, refer to PI Server manuals.
1ote8 T)e (H%',OJ< events t)at are ,ritten (8 t)e 31 S)utdo,n su(s8ste/ are inde*endent o- t)e (H%',OJ< events t)at are ,ritten (8 t)e 1nter-a.e ,)en t)e /stopst t=Shutdo!n .o//and!line *ara/eter is s*e.i-ied. (H%',OJ< events can be disabled from being written to PI when PI is restarted by setting the

Shutdown attribute to : for each point. (lternatively, the default behavior of the PI Shutdown Subsystem can be changed to write (H%',OJ< events only for PI points that have their

O C *&+ Interface

"!

I oint Configuration Shutdown attribute set to :. To change the default behavior, edit the \PI\dat\(:!tdo4n.dat file, as discussed in PI Server manuals. Buf!erv and PIBuf!! It is undesirable to write shutdown events when buffering is being used. Bufserv and PIBufss are utility programs that provide the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, bac*ups, and une/pected failures. That is, when PI is shutdown, Bufserv or PIBufss will continue to collect data for the Interface, ma*ing it undesirable to write (H%',OJ< events to the PI points for this Interface. -isabling Shutdown is recommended when sending data to a PI collective to support high availability. Befer to the Bufserv or PIBufss manuals for additional information.

Output oints
$utput points control the flow of data from the PI Server to any destination that is e/ternal to the PI Server, such as a P8 or a third!party database. 4or e/ample, to write a value to a register in a P8 , use an output point. 5ach interface has its own rules for determining whether a given point is an input point or an output point. There is no de facto PI point attribute that distinguishes a point as an input point or an output point. $utputs are triggered for &niInt!based interfaces. That is, outputs are not scheduled to occur on a periodic basis. There are two mechanisms for triggering an output. (s of &niInt 0.0.3, event conditions can be placed on triggered outputs. The conditions are specified using the same event condition *eywords in the e/tended descriptor as described under =Trigger!based Inputs.> The only difference is that the trigger tag is specified with the SourceTag attribute instead of with the =event> or =trig> *eywords. $therwise, the behavior of event conditions described under YTrigger!Based Inputs> is identical for output points. 4or output points, event conditions are specified in the e/tended descriptor as follows?
e+ent8condition

Trigger 'ethod 1 A6ecommendedB


4or trigger method A, a separate trigger point must be configured. The output point must have the same point source as the interface. The trigger point can be associated with any point source, including the point source of the interface. (lso, the point type of the trigger point does not need to be the same as the point type of the output point. The output point is associated with the trigger point by setting the SourceTag attribute of the output point e<ual to the tag name of the trigger point. (n output is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous value that was sent to the Snapshot to trigger an output, but the timestamp of the new value must be more recent than the previous value. If no error is indicated, then the value that was sent to the trigger point is also written to the output point. If the output is unsuccessful, then an appropriate digital state that is indicative of the failure is usually written to the output point. If an error is not indicated, the output still may not have succeeded because the interface may not be able to tell with certainty that an output has failed.

%.

Trigger 'ethod 2
4or trigger method 1, a separate trigger point is not configured. To trigger an output, write a new value to the Snapshot of the output point itself. The new value does not need to be different than the previous value to trigger an output, but the timestamp of the new value must be more recent than the previous value. Trigger method 1 may be easier to configure than trigger method A, but trigger method 1 has a significant disadvantage. If the output is unsuccessful, there is no tag to receive a digital state that is indicative of the failure, which is very important for troubleshooting.

Output Timestamps
If you need to write the timestamp of an output value to one ItemI- and the output value itself to another, you can get the timestamp by specifying the ItemI- in the E Desc field. In this case, you must specify whether the ItemI- is to be written as a @TH-(T5 or as a @THBSTB "string value%. To write as a string value, define the ?'F parameter in the startup file, so the interface *nows what format to use to create the string. See the sections on 5/-esc and ommand!line Parameters for more details on settings.

I oint Configuration Tool


The $P )-( Tag Builder Tool is a command!line utility that helps you create PI points from the $P )-( Server. #hen e/ecuted, the tool browses the $P )-( Server and gets the attributes needed to configure a PI tag. To get the information re<uired to build PI tags, e/ecute the tool with the following command?
PIHOME\interfaces\OPCH,2Int\H,2'ag>!ilder.exe ?node5t!r o err; ?ser+er5O(I.H,2.. ?&s5:ad

The following section lists optional and re<uired arguments.

Configuration Tool Command<line arameters


arameter +d( (0*tional +) or +)el* (0*tional +lo.1TU (0*tional &escription Lo99in9 -or internal data translation and is )el*-ul -or 31 Te.) Su**ort. Dis*la8s in-or/ation a(out t)e use o- .o//and!line *ara/eters. S*e.i-ies t)e .o*8 o- t)e inter-a.e to ,)i.) t)e *oint (elon9s. T)e value o- t)is attri(ute /ust /at.) t)e +id inter-a.e startu* *ara/eter. #or in*ut ta9s, t)is value s*e.i-ies ,)et)er to store t)e data value(0 or Gualit8 o- t)e data(1 . #or out*ut ta9s, t)is value is used to indi.ate ,)et)er t)is ta9 is to send t)e di9ital strin9(0 or t)e ordinal nu/(er(1 (0, 1, 2, V -or di9ital ta9s. S*e.i-ies ,)et)er t)e ta9 is an 1n*ut(0 or 0ut*ut(2 ta9.

+lo.2TU (0*tional

+lo.%TU (0*tional

O C *&+ Interface

%1

I oint Configuration
arameter +lo.4TU (0*tional &escription #or inter-a.es t)at su**ort s.an!(ased .olle.tion odata, t)is value de-ines t)e s.an .lass nu/(er -or t)e 31 3oint. #or Tri99er!(ased 1n*uts and 0ut*ut 3oints, set t)is value to Bero. S*e.i-ies )o, t)e *oint is to use data t)at )as t)e Gualit8 o- RUn.ertainS: 0 W RUn.ertainS data ,ill (e sent to 31 ,it) t)e Guestiona(le (it set. 1 W store t)e di9ital state RAad Eualit8S i- t)e Gualit8 is RUn.ertainS. 2 W RUn.ertainS Gualit8 ,ill (e treated as 9ood Gualit8 S*e.i-ies t)e node ,)ere t)e 03C 6DA server is runnin9 (o*tional . T)is ar9u/ent is needed onl8 ,)en e$e.utin9 t)e .on-i9uration tool on a se*arate node -ro/ t)e 03C 6DA server. T)e 3ointSour.e used (8 t)e 31 3oints. S*e.i-ies t)e na/e o- t)e server (i.e. 0S1.6DA.1

+lo.5TU (0*tional

+nodeTnodena/e (<eGuired i- inter-a.e not loaded on 03C 6DA server node, ot)er,ise o*tional +*sT3oint Sour.e (<eGuired +serverTserverna/e (<eGuired

4or more information on the Point (ttributes listed above, please see the =Point (ttributes> section of this manual. To build PI $P )-( Interface tags, use the output file, =hdatagbuilder.csv,> from the configuration tool within PI S+T to e/port the tags to PI.

%2

Chapter 1..

Startup Command /ile

ommand!line parameters can begin with a ? or with a 7. 4or e/ample, the /ps=" and #ps=" command!line parameters are e<uivalent. 4or #indows, command file names have a .bat e/tension. The #indows continuation character "K% allows for the use of multiple lines for the startup command. The ma/imum length of each line is A:13 characters "A *ilobyte%. The number of parameters is unlimited, and the ma/imum length of each parameter is A:13 characters. The PI Interface onfiguration &tility "PI I &% provides a tool for configuring the Interface startup command file.

Configuring the Interface 9ith I IC0


1ote: 31 1CU reGuires 31 %.% or 9reater.

The PI Interface onfiguration &tility provides a graphical user interface for configuring PI interfaces. If the Interface is configured by the PI I &, the batch file of the Interface "PIOPCH,2Int. at% will be maintained by the PI I & and all configuration changes will be *ept in that file and the module database. The procedure below describes the necessary steps for using PI I & to configure the PI $P )-( Interface. 4rom the PI I & menu, select Interface, then "ew-indows Interface Instance from ./...., and then *rowse to the PIOPCH,2Int.exe e/ecutable file. Then, enter values for Point Source and Interface I 0. ( window such as the following results?

O C *&+ Interface

%"

=Interface name as displayed in the I & "optional%> will have PI! pre!pended to this name and it will be the display name in the services menu. lic* on Add. The following display should appear?

Note that in this e/ample the )ost PI System is +.588'8(PT$P. To configure the interface to communicate with a remote PI Server, select Y Interface 12 #onnections3 item from PI I & menu and select the default server. If the remote node is not present in the list of servers, it can be added. $nce the interface is added to PI I &, near the top of the main PI I & screen, the Interface %!pe should be o&c:daint. If not, use the drop!down bo/ to change the Interface %!pe to be o&c:daint. lic* on Appl! to enable the PI I & to manage this copy of the PI $P )-( Interface.

The ne/t step is to ma*e selections in the interface!specific tab "i.e., = o&c:daint>% that allow the user to enter values for the startup parameters that are particular to the PI $P )-( Interface.

O C *&+ Interface

%%

Since the PI $P )-( Interface is a &niInt!based interface, in some cases the user will need to ma*e appropriate selections in the !niInt page. This page allows the user to access &niInt features through the PI I & and to ma*e changes to the behavior of the interface. To set up the interface as a #indows Service, use the Service page. This page 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 I &. To do that go to menu, select the Interface item and then Start Interactive. 4or more detailed information on how to use the above!mentioned and other PI I & pages and selections, please refer to the PI Interface onfiguration &tility &ser +anual. The ne/t section describes the selections that are available from the opchdaint page. $nce selections have been made on the PI I & ;&I, press the Appl! button in order for PI I & to ma*e these changes to the interfaces startup file.

O C*&+Int Interface page


Since the startup file of the PI $P )-( Interface is maintained automatically by the PI I &, use the opchdaint page to configure the startup parameters and do not ma*e changes in the file manually. The following is the description of interface configuration parameters used in the PI I & ontrol and corresponding manual parameters.

O C *&+ Interface

%$

Startup Command /ile O C*&+Int

The $P )-(Iint I & ontrol for PI I & has four tabs. ( yellow te/t bo/ indicates that an invalid value has been entered, or that a re<uired value has not been entered. >eneral arameters OPCHDA #erver Node Na+e )ost name of the node where the $P )-( Server is located. If the interface is running on the computer where the $P )-( Server is located then the NodeName?? must be omitted in the command line parameter argument . If the server name has embedded spaces, enclose the name in double <uotes. This is a re<uired field and must be filled in. "/Ser$er=NodeName::OPCHDAServerName% "oad Availa-le OPCHDA #erver Na+e! lic* this button to get a list of available $P )-( Server names from the $P )-( Server Node entered above. It will populate the OPC"D# Server $ame drop down bo/. OPCHDA #erver Na+e 8ists the $P )-( Servers available at the node specified in OPC"D# Server $ode $ame . Select the server that the interface will access. "/Ser$er=NodeName::OPCHDAServerName% Current Active #erver %ag The string tag into which should be written the name of the currently active $P )-( Server "/%S=tag%.

%(

Optional parameters

Hi!tory ,ecovery Only 9 Hi!tory ti+e range Specifies a range of history to recover before e/iting. Specify the times using PI time string formats with a colon separating the date and the time. 4or e/ample, if you enter .L7dec7 L$:.L:LL:LLE.L7dec7L$:./:LL:LL, the interface will recover two hours of data from the $P )-( Server, send the data to the PI System for all points, and then e/it. " /H&'()*5 dd-mmm-yy:hh:mm:ss,dd-mmm-yy:hh:mm:ss% U!e %i+e!ta+& #tring .or+at Sets the format for timestamp strings written to the $P )-( Server. " /+FFformat% U!e ,eadProce!!ed Call Tells the interface to use the $P )-( BeadProcessed call instead of the BeadBaw call. The BeadProcessed call will return values at an interval based on the scan time of the points scan class. ",BPFflag where ,fl g=- Z The BeadProcessed call will be made with the $P )-(HINT5BP$8(TI@5 flag. This will cause the $P )-( server to return interpolated values at the scan interval. 4lagFA Z The BeadProcessed will be made with the $P )-(HST(BT flag. This will cause the $P )-( server to return the value and timestamp at the start time of the interval. 4lagF1 Z The BeadProcessed will be made with the $P )-(H5N- flag. This will cause the $P )-( server to return the value and timestamp at the end time of interval%

O C *&+ Interface

%,

Startup Command /ile Hi!tory ,ecovery Ma:i+u+ %i+e Specifies the ma/imum amount of time to go bac* in history at startup. To use, select the chec* bo/, enter a value, and choose a unit of measure. " /HIF#c, where # is a number and c is a unit, li*e =-> for days, =)> for hours, =+> for minutes, or =S> for seconds.% Ad;u!t %i+e!ta+& /it5 Off!et (pplies an adCustment to the timestamp, to deal with bro*en servers and bro*en installations, where the cloc* for the $P )-( Server is set incorrectly "for e/ample, the server re<uires the cloc* to match the wall cloc*, but the time Done must be ;+T, regardless of where the server is actually located%. To use, select the chec* bo/, enter a value "which maybe either positive or negative%, and choose a unit of measurement. The interface converts the value stored in the batch file to the number of seconds corresponding to the chosen unit of measurement. "/+'=#, where # is either a positive or negative value depending on whether the time must be adCusted forward or bac*ward.% Ma:i+u+ %i+e Period Per Call Specifies the ma/imum amount of time to re<uest data from the $P )-( per call. Instead of as*ing for data from last value to current time, interface calls data in chun*s of time using the passed in ma/ time period. To use, select the chec* bo/, enter a value, and choose a unit of measure. "/"P=#c, where # is a number, and x is a unit li*e =-> for days, =)> for hours, =+> for minutes, and =S> for seconds. %i+e delay -efore reading OPC %ag! Specifies the number of seconds to wait after connecting to the $P )-( Server before scanning data. This delay provides time for loading points on the $P )-( Server before scanning. "/SD=#, where # is a number in seconds.% M# to &au!e -et/een Hi!tory ,etrieval Specifies the number of milliseconds to pause between history recovery of a tag. "/H&P./S05millisecond% %i+e! Not Ad;u!ted to t5e PI #erver The $P )-( Server provides the timestamp, but the interface does not adCust for any offset between the $P Server and the PI Server. "/+S/%.
1ote: Use t)is o*tion ,it) .aution.

Di!card #u--#u-!econd Portion of %i+e!ta+& #hen selected, the interface discards the subsecond portion of the timestamp passed to PI Server and only sends whole integer seconds. This parameter can improve performance? PI Server will re<uire less spaceZand possibly less P&Zto store the same amount of data. The interface truncates the fractional part of the timestamp. " /I+% <rou& #i8e (= of %ag!) Specifies ma/imum number of tags to include in a call to the $P )-( Server. #ithin each scan class, the interface calls the $P )-( server in groups of the specified siDe, up to the number of points in the scan class. The start time of each data re<uest matches the end time of the previous re<uest. If you do not specify this parameter, the interface calls the $P )-(
%-

Server one tag at a time with the start time set to the timestamp of the last value read from the $P )-( Server. "/1S5#% #tart %i+e Ad;u!t (!ec') &sed with %roup Si&e, sets the start time of the data call to the previous end time minus the specified seconds. #ith this parameter, you can provide some overlap in the data call to ensure that you do not miss data that enters the $P )-( Server after the interface made the read call. If the ?@( parameter is not passed in, the ?sa parameter has no effect. "/S.5#E where # is a number in seconds.% End %i+e Ad;u!t (!ec') &sed with %roup Si&e, sets the end time of the data call to the current time minus the specified seconds. #ith this parameter, you can provide some overlap in the data call to ensure that you do not miss data that enters the $P )-( Server after the interface made the read call. If the ?@( parameter is not passed in, the ?ea parameter has no effect. "/0.5#E where # is a number in seconds.% No %i+eout #hen selected, the interface never writes I,$ Timeout, including when the interface loses connection with the $P )-( Server. "/(+%. Ignore #erver #tatu! The $P Server should go to $P )-(H&P state when it is ready to send data. If it does not, set the interface to try to tal* to it anyway by clic*ing this chec*bo/. " /IS% Ena-le Ma!! %ag Adding Select this chec* bo/ to set the interface to verify many tags at one time. It is faster to verify many items at once, instead of one by one. "/".%

O C *&+ Interface

%!

Startup Command /ile

3ac#up arameters This tab contains parameters that set the server!level failover options of the interface. By design, the PI $P )-( interface provides redundancy for the $P )-( server. 4or server!level failover, you can configure the interface to change to another server when the current server no longer serves data or when the server changes state. To implement, you must specify the primary and secondary "that is, bac*up% $P )-( servers.

OPCHDA Bac>u& #erver Node Na+e and #erver Na+e The name of the node and server of the $P )-( server that you are designating as the bac*up server. "/2 c3upS0&40&5>2CM%P <ode::>2CM%P (E*NE*<2ME%. #/itc5 to Bac>u& Delay (!ec) The number of attempts to connect, before switching to the bac*up $P )-( Server "/F+5#%. Wait for ,UNNIN< #tate (!ec) The number of seconds to wait for &P status, before switching to the bac*up $P )-( Server "/S55#%.

$.

&ebug arameters

&se the parameters on this tab to do minimal debugging when having difficulty determining what data you are receiving from the $P )(- Server. Internal %e!ting Only This is for internal testing onlyG do not use. "/DB5.% "og of #tartu& 5nable startup logging, including InstrumentTag and 5/-esc for each tag. " /DB5/% "og Write O&eration 5nable pipc.log file messages for write operations. "/DB5$% "og %i+e!ta+&! of ,efre!5 8og the time that a scan starts and that a scan ends. " /DB58% "og %i+e!ta+&! and Data (All %ag!) 8og the timestamp with the data, the adCusted timestamp, the PITime, and the scan class for each data value that the interface receives. " /DB50/%
1ote: T)is settin9 *rodu.es a lot o- data. D0 D0T L4A@4 T61S S4TT1D5 0D #0< :0<4 T6AD A #4' :1DUT4S.

O C *&+ Interface

$1

Startup Command /ile "og %i+e!ta+&! and Data for %ag 8og the same items as ?,>50/, but only for the tag specified as the debug tag "?,'5tagname%. If there is no tag specified, the first tag for which a value is received is set to the debug tag. "/DB56$% "og atte+&t! to connect to OPC HDA #erver and ti+e it too> to fini!5 reading a !can cla!! 8og when the interface tries to connect to the $P )-( Server. (lso log the start and end of each scan with the amount of time it too* to finish the scan and the number of values sent to PI. "/DB5./8% "og /5en a Digital tag i! reading a nu+eric value t5at i! Over ,ange 8og when a numeric value is read for a digital tag and the number is above the possible number of digital states. The $ver Bange system digital state is sent to PI in this case. "/DB5/16% #et De-ug "evel *ia a %ag &se to change the value of the debug parameter while the interface is running. onfigure an output tag for the interface, Int01, and set its value to :. ;ive the name of this tag with the ?,F parameter. #hen the value of this PI tag is changed, the interface will capture the new value and set its debug parameter to that value. Nothing will be written to the $P )-( Server. "/DF5tagname%
1ote: T)e UniInt Interface User Manual in.ludes details a(out ot)er .o//and line *ara/eters, ,)i.) /a8 (e use-ul.

+dditional arameters This section is provided for any additional parameters that the current I & ontrol does not support. Separate command!line parameters by a space, and enclose arguments that have embedded blan*s with double <uotes.

$2

Command<line arameters
arameter &escription De-ines t)e AAC?U3 03C 6DA Server to (e used. Use t)e -ollo,in9 -or/at:

/B.%6/PS0&40&=, 'P%,HD.,Ser$er,
0*tional De-ault: none

/B.%6/PS0&40&=FACT NOD!::"OD#$SOPC%HDA, ,)ere FACT NOD! is t)e na/e o- t)e .o/*uter ,)ere t)e 03C 6DA Server runs, and "OD#$SOPC%HDA is t)e na/e o- t)e 03C 6DA
Server as re9istered on t)at /a.)ine. 1- t)e (a.7u* server runs on t)e sa/e /a.)ine as t)e inter-a.e, o/it t)e node na/e:

/B.%6/PS0&40&="OD#$SOPC%HDA,
1- t)e server na/e )as e/(edded s*a.es, en.lose t)e na/e in dou(le Guotes:

/B.%6/PS0&40&=7Server&name&'ith&s(aces7 /%S=tagname
0*tional De-ault: none T)e strin9 ta9 ,)ere t)e inter-a.e s)ould ,rite t)e na/e o- t)e .urrentl8 a.tive 03C 6DA Server. 4na(les /ini/al de(u99in9. Use-ul ,)en 8ou .annot tell ,)at t)e server is returnin9. See R3ara/etersS on *a9e 51 -or /ore in-or/ation. C)an9es t)e value o- t)e de(u9 *ara/eter ,)ile t)e inter-a.e is runnin9. Con-i9ure an out*ut ta9 -or t)e inter-a.e, 1nt%2, and set its value to 0. 5ive t)e na/e o- t)is ta9 ,it) t)e /DF *ara/eter. #or e$a/*le:

/DB=x
0*tional De-ault: none

/DF=tagname
0*tional De-ault: none

/DF='P%HD..De2ug.,P r meter,
')en t)e value is .)an9ed in t)e 31 ta9, t)e inter-a.e ,ill .a*ture t)e ne, value and set its de(u9 *ara/eter to t)at value. Dot)in9 ,ill (e ,ritten to t)e 03C 6DA Server.

/0.=#
0*tional De-ault: none

AdFusts t)e end ti/e o- t)e data .all to t)e .urrent ti/e /inus # nu/(er o- se.onds. T)is is used ,it) t)e /1S (9rou* siBe *ara/eter. Use t)is *ara/eter to *rovide so/e overla* in t)e data .all to ensure no data is /issed i- data 9oes into t)e 03C6DA Server a-ter t)e inter-a.e /ade t)e read .all. 1- t)e /1S *ara/eter is not *assed in, t)e /0. *ara/eter ,ill )ave no e--e.t. T)e -irst instan.e o- t)e /ec *ara/eter on t)e .o//and!line is used to s*e.i-8 a .ounter nu/(er, O, -or an 1+0 <ate *oint. 1- t)e O is not s*e.i-ied, t)en t)e de-ault event .ounter is 1. Also, i- t)e /ec *ara/eter is not s*e.i-ied at all, t)ere is still a de-ault event .ounter o1 asso.iated ,it) t)e inter-a.e. 1- t)ere is an 1+0 <ate *oint t)at is asso.iated ,it) an event .ounter o- 1, ea.) .o*8 o- t)e inter-a.e t)at is runnin9 ,it)out /ec=#e$*li.itl8 de-ined ,ill ,rite to t)e sa/e 1+0 <ate *oint. T)is /eans eit)er e$*li.itl8 de-inin9 an event .ounter ot)er t)an 1 -or ea.) .o*8 o- t)e inter-a.e or not asso.iatin9 an8 1+0 <ate *oints ,it) event .ounter 1. Con-i9uration o- 1+0 <ate *oints is dis.ussed in t)e se.tion .alled 1+0 <ate 3oint. Su(seGuent instan.es o- t)e /ec *ara/eter /a8 (e used (8 s*e.i-i. inter-a.es to 7ee* tra.7 o- various in*ut or out*ut o*erations. Su(seGuent instan.es o- t)e /ec *ara/eter .an (e o- t)e -or/ /ec8, ,)ere F is an8 ASC11 .)ara.ter seGuen.e. #or e$a/*le, /ecinput=1-, /ecoutput=11, and /ec=19 are le9iti/ate .)oi.es -or t)e se.ond, t)ird, and -ourt) event .ounter strin9s. T)e /f,*ara/eter de-ines t)e ti/e *eriod (et,een s.ans in ter/s o)ours (HH , /inutes (MM , se.onds ((( and su(!se.onds (OO . T)e

/ec=#
0*tional

/f=SS.##
or

O C *&+ Interface

$"

Startup Command /ile


arameter &escription s.ans .an (e s.)eduled to o..ur at dis.rete /o/ents in ti/e ,it) an o*tional ti/e o--set s*e.i-ied in ter/s o- )ours (:: , /inutes (mm , se.onds (ss and su(!se.onds (OO . 1- HH and MM are o/itted, t)en t)e ti/e *eriod t)at is s*e.i-ied is assu/ed to (e in se.onds. 4a.) instan.e o- t)e /f *ara/eter on t)e .o//and!line de-ines a s.an .lass -or t)e inter-a.e. T)ere is no li/it to t)e nu/(er o- s.an .lasses t)at .an (e de-ined. T)e -irst o..urren.e o- t)e /f *ara/eter on t)e .o//and!line de-ines t)e -irst s.an .lass o- t)e inter-a.eP t)e se.ond o..urren.e de-ines t)e se.ond s.an .lass, and so on. 31 3oints are asso.iated ,it) a *arti.ular s.an .lass via t)e Lo.ation4 31 3oint attri(ute. #or e$a/*le, all 31 3oints t)at )ave Lo.ation4 set to 1 ,ill re.eive in*ut values at t)e -reGuen.8 de-ined (8 t)e -irst s.an .lass. Si/ilarl8, all *oints t)at )ave Lo.ation4 set to 2 ,ill re.eive in*ut values at t)e -reGuen.8 s*e.i-ied (8 t)e se.ond s.an .lass, and so on. T,o s.an .lasses are de-ined in t)e -ollo,in9 e$a/*le:

/f=SS.##,SS.##
or

/f=HH:"":SS.##
or

/f=HH:"":SS.##, hh:mm:ss.##
<eGuired -or readin9 s.an!(ased in*uts

/f=--:-1:--,--:--:-:,/f=--:--:-;
or, eGuivalentl8:

/f=<-,: /f=;
T)e -irst s.an .lass )as a s.annin9 -reGuen.8 o- 1 /inute ,it) an o--set o- 5 se.onds, and t)e se.ond s.an .lass )as a s.annin9 -reGuen.8 o7 se.onds. ')en an o--set is s*e.i-ied, t)e s.ans o..ur at dis.rete /o/ents in ti/e a..ordin9 to t)e -or/ula: s.an ti/es T (re-eren.e ti/e X n(-reGuen.8 X o--set ,)ere n is an inte9er and t)e re-eren.e ti/e is /idni9)t on t)e da8 t)at t)e inter-a.e ,as started. 1n t)e a(ove e$a/*le, -reGuen.8 is &0 se.onds and o--set is 5 se.onds -or t)e -irst s.an .lass. T)is /eans t)at i- t)e inter-a.e ,as started at 05:0&:0&, t)e -irst s.an ,ould (e at .$8.,8.$, t)e se.ond s.an ,ould (e at .$8.-8.$, and so on. Sin.e no o--set is s*e.i-ied -or t)e se.ond s.an .lass, t)e a(solute s.an ti/es are unde-ined. T)e de-inition o- a s.an .lass does not 9uarantee t)at t)e asso.iated *oints ,ill (e s.anned at t)e 9iven -reGuen.8. 1- t)e inter-a.e is under a lar9e load, t)en so/e s.ans /a8 o..ur late or (e s7i**ed entirel8. See t)e se.tion R3er-or/an.e Su//ariesS in t)e UniInt Interface User Manual.do. -or /ore in-or/ation on s7i**ed or /issed s.ans.

(! 7second (can Classes


Su(!se.ond s.an .lasses .an (e de-ined on t)e .o//and!line, su.) as

/f=-.: /f=--:--:--.1
,)ere t)e s.annin9 -reGuen.8 asso.iated ,it) t)e -irst s.an .lass is 0.5 se.onds and t)e s.annin9 -reGuen.8 asso.iated ,it) t)e se.ond s.an .lass is 0.1 o- a se.ond. Si/ilarl8, su(!se.ond s.an .lasses ,it) su(!se.ond o--sets .an (e de-ined, su.) as

/f=-.:,-.9 /f=1,Jall ClocG (c:ed!ling


S.an .lasses t)at stri.tl8 ad)ere to ,all .lo.7 s.)edulin9 are no, *ossi(le. T)is -eature is availa(le -or inter-a.es t)at run on 'indo,s and+or UD1O. 3reviousl8, ,all .lo.7 s.)edulin9 ,as *ossi(le, (ut not a.ross da8li9)t savin9 ti/e. #or e$a/*leE /f=9=:--:--,->:--:-- .orres*onds to 1 s.an a da8 startin9 at " A:. 6o,ever, a-ter a Da8li9)t Savin9 Ti/e .)an9e, t)e s.an ,ould o..ur eit)er at 7 A: or 9 A:, de*endin9 u*on t)e dire.tion o- t)e ti/e s)i-t. To s.)edule a s.an on.e a da8 at " A: (even a.ross da8li9)t savin9 ti/e , use /f=9=:--:--,--:->:--,). T)e E- at t)e end o- t)e s.an .lass tells Uni1nt to use t)e ne, ,all .lo.7 s.)edulin9 al9orit)/.

$%

arameter

&escription T)e nu/(er o- atte/*ts to .onne.t, (e-ore s,it.)in9 to t)e Aa.7u* 03C 6DA Server. T)e .all to t)e 03C6DA Server ,ill (e /ade in 9rou*s o- U nu/(er ota9s. 'it)in ea.) s.an .lass, t)e .all to t)e 03C6DA Server ,ill (e /ade in 9rou*s o- $ u* to t)e nu/(er o- *oints t)e s.an .lass. T)e start ti/e o- ea.) data reGuest ,ill (e done -ro/ t)e *revious end ti/e. 'it)out t)e /1S *ara/eter, t)e .alls to t)e 03C6DA server ,ill (e done one ta9 at a ti/e ,it) t)e start ti/e (ein9 t)e ti/e sta/* o- t)e last value read -ro/ t)e 03C6DA Server. T)e /a$i/u/ a/ount o- ti/e to 9o (a.7 in )istor8 at startu*. #or e$a/*le: .d -or one da8. De-ault is /d. T)e /host *ara/eter is used to s*e.i-8 t)e 31 6o/e node. Host is t)e 13 address o- t)e 31 Sever node or t)e do/ain na/e o- t)e 31 Server node. Port is t)e *ort nu/(er -or TC3+13 .o//uni.ation. T)e *ort is al,a8s 5450. 1t is re.o//ended to e$*li.itl8 de-ine t)e )ost and *ort on t)e .o//and!line ,it) t)e /host,*ara/eter. Devert)eless, i- eit)er t)e )ost or *ort is not s*e.i-ied, t)e inter-a.e ,ill atte/*t to use de-aults. 4$a/*les: T)e inter-a.e is runnin9 on a 31 1nter-a.e Dode, t)e do/ain na/e ot)e 31 )o/e node is :arvin, and t)e 13 address o- :arvin is 20&.79.19".%0. @alid /host *ara/eters ,ould (e:

/F+=#
0*tional De-ault: /F+=1-

1S=#
0*tional Da-ault: /1S=1

/HI=x
0*tional De-ault: 9d

/host=host:port
<eGuired

/host=m r$in /host=m r$in::=:/host=9-<.;?.1?>.@/host=9-<.;?.1?>.@-::=:/hronlA= start,end


0*tional

S*e.i-8 ti/e!ran9e!s*e.i-i. )istor8 re.over8. S*e.i-8 ti/es usin9 31 ti/e strin9 -or/ats ,it) a .olon se*aratin9 t)e date and t)e ti/e:

/hronlA=1-#dec#?>:1-:--,1-#dec#?>:19:--,
')en .on-i9ured -or ti/e!ran9e!s*e.i-i. )istor8 re.over8, t)e inter-a.e re.overs data t)en e$its. :illise.onds to *ause (et,een ta9s durin9 )istor8 re.over8. Used to t)rottle ar.)ive data retrieval durin9 )istor8 re.over8.

/hrp use=O
0*tional De-ault:

/hrp use=-, /id=x


6i9)l8 <e.o//ended T)e /id *ara/eter is used to s*e.i-8 t)e inter-a.e identi-ier. T)e inter-a.e identi-ier is a strin9 t)at is no lon9er t)an 9 .)ara.ters in len9t). Uni1nt .on.atenates t)is strin9 to t)e )eader t)at is used to identi-8 error /essa9es as (elon9in9 to a *arti.ular inter-a.e. See t)e A**endi$ A 4rror and 1n-or/ational :essa9es -or /ore in-or/ation. Uni1nt al,a8s uses t)e /id *ara/eter in t)e -as)ion des.ri(ed a(ove. T)is inter-a.e also uses t)e /id,*ara/eter to identi-8 a *arti.ular inter-a.e .o*8 nu/(er t)at .orres*onds to an inte9er value t)at is assi9ned to Lo.ation1. #or t)is inter-a.e, use onl8 nu/eri. .)ara.ters in t)e identi-ier. #or e$a/*le,

/id=1

O C *&+ Interface

$$

Startup Command /ile


arameter &escription Tells t)e inter-a.e to i9nore t)e server status returned (8 t)e 03C 6DA Server. All servers s)ould return

/IS
0*tional

OPCH,28%P
,)en t)e8 are read8 to read values. Use t)is *ara/eter i- 8our 03C6DA server does not do t)is.

/I+
0*tional

Tells t)e inter-a.e to dis.ard t)e su(se.ond *ortion o- t)e ti/esta/*s *assed to 31 Server and onl8 send ,)ole inte9er se.onds. Use -or *er-or/an.e reasons. 'it) t)is o*tion, 31 Server ,ill reGuire less s*a.e, and *ossi(l8 less C3U, to store t)e sa/e a/ount o- data. T)e inter-a.e si/*l8 trun.ates t)e -ra.tional *art o- t)e se.ond. Tells t)e inter-a.e to veri-8 u* to 500 ite/s at t)e sa/e ti/e. T)is .an s*eed u* t)e startu* ti/e. A8 de-ault, t)e inter-a.e ,ill veri-8 one ite/ at a ti/e. T)e /a$i/u/ a/ount o- ti/e to reGuest data -ro/ t)e 03C 6DA *er .all. 1nstead o- as7in9 -or data -ro/ last value to .urrent ti/e, .all data in .)un7s o- ti/e usin9 t)e *assed in /a$ ti/e *eriod. (/"P=#c, ,)ere # is a nu/(er and c is a unit li7e RD: -or da8s, R6S -or )ours, R:S -or /inutes, and RSS -or se.onds. Tells t)e inter-a.e to never ,rite 1+0 Ti/eout, in.ludin9 ,)en inter-a.e loses .onne.tion ,it) t)e 03C6DA Server. T)e /ps *ara/eter s*e.i-ies t)e *oint sour.e -or t)e inter-a.e. 6 is not .ase sensitive and .an (e an8 uniGue sin9le or /ulti*le .)ara.ter strin9. #or e$a/*le, /ps=P and /ps=p,are eGuivalent. T)e *oint sour.e t)at is assi9ned ,it) t)e /ps,*ara/eter .orres*onds to t)e 3ointSour.e attri(ute o- individual 31 3oints. T)e inter-a.e ,ill atte/*t to load onl8 t)ose 31 *oints ,it) t)e a**ro*riate *oint sour.e. 1- t)e 31 A31 version (ein9 used is *rior to 1.&.$ or t)e 31 Server version is *rior to %.4.%70.$, t)e Point(o!rce is li/ited to a sin9le .)ara.ter. Tells t)e inter-a.e to Gueue sna*s)ots and e$.e*tions (e-ore sendin9 to t)e 31 Server node. T)e /a$i/u/ Gueue siBe is .lose to 4000 (8tes. T)e Gueue is -lus)ed (et,een s.ans i- it is not -illed. Tells t)e inter-a.e to use t)e 03C 6DA <ead3ro.essed .all instead ot)e <ead<a, .all. T)e <ead3ro.essed .all ,ill return values at an interval (ased on t)e s.an ti/e o- t)e *oint=s s.an .lass. #or e$a/*le: 1- a *oint is in a s.an .lass ,it) a 10!se.ond s.an ti/e, t)e <ead3ro.essed .all ,ill return values at a 10!se.ond interval instead o- all t)e values in t)e 6DA server. T)is ,ill redu.e t)e tra--i. (et,een t)e 03C6DA Server and t)e inter-a.e. T)ere are t)ree ,a8s to .on-i9ure t)is *ara/eter: /rp=- Y T)e <ead3ro.essed .all ,ill (e /ade ,it) t)e 03C6DAH1DT4<30LAT1@4 -la9. T)is ,ill .ause t)e 03C 6DA server to return inter*olated values at t)e s.an interval. /rp=1 Y T)e <ead3ro.essed ,ill (e /ade ,it) t)e 03C6DAHSTA<T -la9. T)is ,ill .ause t)e 03C 6DA server to return t)e value and ti/esta/* at t)e start ti/e o- t)e interval /rp=9 Y T)e <ead3ro.essed ,ill (e /ade ,it) t)e 03C6DAH4DD -la9. T)is ,ill .ause t)e 03C 6DA server to return t)e value and ti/esta/* at t)e end ti/e o- interval.

/".
0*tional De-ault: none,

/"P=#c
0*tional De-ault: none

/(+
0*tional De-ault: none

/ps=x
<eGuired

/B
0*tional

/&P=#
0*tional

$(

arameter

&escription AdFusts t)e start ti/e o- t)e data .all to t)e *revious end ti/e /inus # nu/(er o- se.onds. T)is is used ,it) t)e /1S (9rou* siBe *ara/eter. Use t)is *ara/eter to *rovide so/e overla* in t)e data .all to ensure no data is /issed i- data 9oes into t)e 03C6DA Server a-ter t)e inter-a.e /ade t)e read .all. 1- t)e /1S *ara/eter is not *assed in, t)e /S. *ara/eter ,ill )ave no e--e.t. T)e nu/(er o- se.onds to ,ait a-ter a .onne.tion to t)e 03C 6DA Server and (e-ore s.annin9 data. T)is is to allo, ti/e -or t)e *oints on t)e 03C Server to load (e-ore s.annin9. De-ines t)e 03C 6DA Server to (e used. S*e.i-8 ,it) t)e -ollo,in9 -or/at:

/S.=#
0*tional De-ault: none

/sd=x
0*tional

/S0&40&= 'P%HD.Ser$er,
<eGuired

/S0&40&=FACT)NOD!::"OD#$SOPC%HDA ,)ere FACT)NOD! is t)e na/e o- t)e .o/*uter ,)ere t)e 03C 6DA Server runs, and "OD#$SOPC%HDA is t)e na/e o- t)e 03C 6DA
Server as re9istered on t)at /a.)ine. 1- t)e server runs on t)e sa/e /a.)ine as t)e inter-a.e, o/it t)e node na/e:

/S0&40&="OD#$SOPC%HDA
1- t)e server na/e )as e/(edded s*a.es, en.lose t)e na/e in dou(le Guotes:

/S0&40&=7Server&name&'ith&s(aces7, /sio
0*tional T)e /sio *ara/eter stands -or Rsu**ress initial out*uts.S T)e *ara/eter a**lies onl8 -or inter-a.es t)at su**ort out*uts. 1- t)e /sio, *ara/eter is not s*e.i-ied, t)e inter-a.e ,ill (e)ave in t)e -ollo,in9 /anner. ')en t)e inter-a.e is started, t)e inter-a.e deter/ines t)e .urrent Sna*s)ot value o- ea.) out*ut ta9. De$t, t)e inter-a.e ,rites t)is value to ea.) out*ut ta9. 1n addition, ,)enever an individual out*ut ta9 is edited ,)ile t)e inter-a.e is runnin9, t)e inter-a.e ,ill ,rite t)e .urrent Sna*s)ot value to t)e edited out*ut ta9. T)is (e)avior is su**ressed i- t)e /sio *ara/eter is s*e.i-ied on t)e .o//and!line. T)at is, out*uts ,ill not (e ,ritten ,)en t)e inter-a.e starts or ,)en an out*ut ta9 is edited. 1n ot)er ,ords, ,)en t)e /sio,*ara/eter is s*e.i-ied, out*uts ,ill onl8 (e ,ritten ,)en t)e8 are e$*li.itl8 tri99ered.

O C *&+ Interface

$,

Startup Command /ile


arameter &escription 1- t)e /stopst t *ara/eter is *resent on t)e startu* .o//and line, t)en t)e di9ital state Intf (:!t ,ill (e ,ritten to ea.) 31 3oint ,)en t)e inter-a.e is sto**ed. 1- /stopst t=digst te is *resent on t)e .o//and line, t)en t)e di9ital state, digstate, ,ill (e ,ritten to ea.) 31 3oint ,)en t)e inter-a.e is sto**ed. #or a 31 % Server, digstate /ust (e in t)e s8ste/ di9ital state ta(le. Uni1nt uses t)e -irst o..urren.e in t)e ta(le. 1- neit)er /stopst t nor /stopst t=digst te is s*e.i-ied on t)e .o//and line, t)en no di9ital states ,ill (e ,ritten ,)en t)e inter-a.e is s)ut do,n. 1ote8 T)e /stopst t *ara/eter is disa(led 1- t)e inter-a.e is runnin9 in a Uni1nt -ailover .on-i9uration as de-ined in t)e Uni1nt #ailover Con-i9uration se.tion o- t)is /anual. T)ere-ore, t)e di9ital state, digstate, ,ill not (e ,ritten to ea.) 31 3oint ,)en t)e inter-a.e is sto**ed. T)is *revents t)e di9ital state (ein9 ,ritten to 31 3oints ,)ile a redundant s8ste/ is also ,ritin9 data to t)e sa/e 31 3oints. T)e /stopst t *ara/eter is disa(led even i- t)ere is onl8 one inter-a.e a.tive in t)e -ailover .on-i9uration. 4$a/*les:

/stopst t
or

/stopst t= digst te
De-ault:

/stopst t= CIntf,Shut7
0*tional

/stopst t=shutdo!n /stopst t=7Intf,Shut7 T)e entire digstate value s)ould (e en.losed ,it)in dou(le Guotes ,)en t)ere is a s*a.e in digstate. /S5=#
0*tional De-ault: none T)e nu/(er o- se.onds to ,ait -or <UDD1D5 status, (e-ore s,it.)in9 to t)e Aa.7u* 03C 6DA Server. Sets t)e -or/at -or ti/esta/* strin9s ,ritten to t)e 03C6DA Server T)e inter-a.e ,rites out*ut ti/esta/*s usin9 T1:T in t)e 4$Des. -ield. See RSendin9 Ti/esta/* and 0ut*ut @alue to Di--erent 1te/1DsRon *a9e %" -or /ore in-or/ation. @alid to7ens are: .. 88 /n /on dd )) )r // ss 000 O: A**lies an adFust/ent to t)e ti/esta/*s (a ti/esta/* o--set , to deal ,it) (ro7en servers and (ro7en installations, ,)ere t)e .lo.7 -or t)e 03C 6DA Server is set in.orre.tl8 (-or e$a/*le, t)e server reGuires t)e .lo.7 to /at.) t)e ,all.lo.7, (ut t)e Ti/eBone /ust (e 5:T, re9ardless o- ,)ere t)e server is a.tuall8 lo.ated . Do not use i- t)e server is ,or7in9 *ro*erl8. S*e.i-8 t)e *ara/eter in se.ondsP 8ou /a8 *re.ede (8 a ne9ative si9n. #or e$a/*le: Ti/e adFusted a)ead (8 1 )our

/+F=*ormat
0*tional

/+'=xx
0*tional

/+'=@<--,
Ti/e adFusted (a.7 (8 1 )our

/+'=#@<--,
Ti/e adFusted a)ead (8 %0 /inutes

/+'=1>--, /+S/
0*tional 1- 8ou need to use t)e ti/esta/*s re.eived -ro/ t)e 03C6DA server ,it)out )avin9 t)e/ adFusted to t)e 31 Server .lo.7, use:

/+S/,
T)is settin9 .an .ause 8our data to (e lost, i- 8our .lo.7s are set in.orre.tl8. 3lease see t)e se.tion on Ti/esta/*s (e-ore usin9 t)is settin9.

$-

arameter

&escription T)e value o- t)is .o//and!line *ara/eter is used ,)en .reatin9 Uni1nt )ealt) *oints -or an inter-a.e t)at uses Don!Uni1nt inter-a.e -ailover. 1t is used -or t)e Lo.ation% *oint attri(ute -or Uni1nt )ealt) *oints.

/uhtDid=#
<eGuired i- an8 t8*e o-ailover ot)er t)an Un1nt 1nter-a.e Level #ailover 3)ase 1 or 2 is su**orted.

//F'DID=#
<eGuired -or Uni1nt 1nter-a.e Level #ailover 3)ase 1 or 2

#ailover 1D. T)is value /ust (e di--erent -ro/ t)e #ailover 1D o- t)e ot)er inter-a.e in t)e -ailover *air. 1t .an (e an8 *ositive, non!Bero inte9er.

//F'DInter$ l=#
0*tional De-ault: .LLL @alid values are 50!20000.

#ailover U*date 1nterval S*e.i-ies t)e )eart(eat U*date 1nterval in /illise.onds and /ust (e t)e sa/e on (ot) inter-a.e .o/*uters. T)is is t)e rate at ,)i.) Uni1nt u*dates t)e #ailover 6eart(eat ta9s as ,ell as )o, o-ten Uni1nt .)e.7s on t)e status o- t)e ot)er .o*8 o- t)e inter-a.e.

//F'D'therID=#
<eGuired -or Uni1nt 1nter-a.e Level #ailover 3)ase 1 or 2

0t)er #ailover 1D. T)is value /ust (e eGual to t)e #ailover 1D .on-i9ured -or t)e ot)er inter-a.e in t)e -ailover *air.

//F'DSAnc=p th/ Efilen meF


<eGuired -or Uni1nt 1nter-a.e Level #ailover 3)ase 2 s8n.)roniBation. An8 valid *at)na/e + an8 valid -ilena/e T)e de-ault -ilena/e is 9enerated as executablenameHpoint sourceHinterfaceID.dat

T)e #ailover #ile S8n.)roniBation #ile*at) and 0*tional #ilena/e s*e.i-8 t)e *at) to t)e s)ared -ile used -or -ailover s8n.)roniBation and an o*tional -ilena/e used to s*e.i-8 a user de-ined -ilena/e in lieu ot)e de-ault -ilena/e. T)e path to t)e s)ared -ile dire.tor8 .an (e a -ull8 Guali-ied /a.)ine na/e and dire.tor8, a /a**ed drive letter, or a lo.al *at) i- t)e s)ared -ile is on one o- t)e inter-a.e nodes. T)e path /ust (e ter/inated (8 a slas) ( ? or (a.7slas) ( \ .)ara.ter. 1- no d ter/inatin9 slas) is -ound, in t)e //F'DSAnc *ara/eter, t)e inter-a.e inter*rets t)e -inal .)ara.ter strin9 as an o*tional filename. T)e o*tional filename .an (e an8 valid -ilena/e. 1- t)e -ile does not e$ist, t)e -irst inter-a.e to start atte/*ts to .reate t)e -ile. 1ote8 1- usin9 t)e o*tional -ilena/e, do not su**l8 a ter/inatin9 slas) or (a.7slas) .)ara.ter. 1- t)ere are an8 s*a.es in t)e path or filename, t)e entire *at) and -ilena/e /ust (e en.losed in Guotes. 1ote8 1- 8ou use t)e (a.7slas) and *at) se*arators and en.lose t)e *at) in dou(le Guotes, t)e -inal (a.7slas) /ust (e a dou(le (a.7slas) (\\ . 0t)er,ise t)e .losin9 dou(le Guote (e.o/es *art o- t)e *ara/eter instead o- a *ara/eter se*arator. 4a.) node in t)e -ailover .on-i9uration /ust s*e.i-8 t)e sa/e *at) and -ilena/e and /ust )ave read, ,rite, and -ile .reation ri9)ts to t)e s)ared dire.tor8 s*e.i-ied (8 t)e path *ara/eter. T)e servi.e t)at t)e inter-a.e runs a9ainst /ust s*e.i-8 a valid lo9on user a..ount under t)e RLo9 0nS ta( -or t)e servi.e *ro*erties.

O C *&+ Interface

$!

Startup Command /ile


arameter &escription T)e #ailover T8*e indi.ates ,)i.) t8*e o- -ailover .on-i9uration t)e inter-a.e ,ill run. T)e valid t8*es -or -ailover are 60T, 'A<:, and C0LD .on-i9urations. 1- an inter-a.e does not su**orted t)e reGuested t8*e o- -ailover, t)e inter-a.e ,ill s)ut do,n and lo9 an error to t)e &i&c.log -ile statin9 t)e reGuested -ailover t8*e is not su**orted.

//F'D+Ape=tApe
<eGuired -or Uni1nt 1nter-a.e Level #ailover 3)ase 2.

Sample IO C*&+Int.bat /ile


The following is an e/ample file?
*EM 55555555555555555555555555555555555555555555555555555555555555555 *EM PIOPCH,2Int. at *EM *EM (am&le start!& file for t:e OPC H,2 Interface *EM 55555555555555555555555555555555555555555555555555555555555555555 *EM O(Isoft strongl; recommends !sing PI IC% to modif; start!& files. *EM 55555555555555555555555555555555555555555555555555555555555555555 *EM *EM ':e K marGs are contin!ation c:aractersE t:e; allo4 *EM a command to e s&lit et4een m!lti&le lines. *EM ':ere m!st not e 2<P'HI<@ after t:e K on eac: line.

*EM *EM (am&le command line *EM PIOPCH,2Int K ?&s5OPCH,2 K ?id5. K ?(E*NE*5O(I.H,2.. K ?:ost5666666:1$1L K ?f5LL:L.:LL K ?f5LL:LL:0L *EM *EM End of PIOPCH,2Int. at

(.

Chapter 11.

0niInt /ailover Configuration

Introduction
To minimiDe data loss during a single point of failure within a system, &niInt provides two failover schemas? "A% synchroniDation through the data source and "1% synchroniDation through a shared file. SynchroniDation through the data source is Phase +, and synchroniDation through a shared file is Phase 4. Phase A &niInt 4ailover uses the data source itself to synchroniDe failover operations and provides a hot failover, no data loss solution when a single point of failure occurs. 4or this option, the data source must be able to communicate with and provide data for two interfaces simultaneously. (dditionally, the failover configuration re<uires the interface to support outputs. Phase 1 &niInt 4ailover uses a shared file to synchroniDe failover operations and provides for hot, warm, or cold failover. The Phase 1 hot failover configuration provides a no data loss solution for a single point of failure similar to Phase A. )owever, in warm and cold failover configurations, you can e/pect a small period of data loss during a single point of failure transition.
1ote8 T)is inter-a.e su**orts onl8 3)ase 2 -ailover.

'ou can also configure the &niInt interface level failover to send data to a PI collective that supports PI Server high availability ")(%. The collective provides redundant PI Servers to allow for the uninterrupted collection and presentation of PI time series data. In an )( configuration, PI Servers can be ta*en down for maintenance or repair. See the ,igh Availabilit! Administrator 'uide for more information about PI collectives. #hen configured for &niInt failover, the interface routes all PI data through a state machine. The state machine determines whether to <ueue data or send it directly to PI depending on the current state of the interface. #hen the interface is in the active state, data sent through the interface gets routed directly to PI. In the bac*up state, data from the interface gets <ueued for a short period. Queued data in the bac*up interface ensures a no5data loss failover under normal circumstances for Phase A and for the hot failover configuration of Phase 1. The same algorithm of <ueuing events while in bac*up is used for output data.

O C *&+ Interface

(1

?uic# Overvie9
The Quic* $verview below may be used to configure this Interface for failover. The failover configuration re<uires the two copies of the interface participating in failover be installed on different nodes. &sers should verify non!failover interface operation as discussed in the Installation hec*list section of this manual prior to configuring the interface for failover operations. If you are not familiar with &niInt failover configuration, return to this section after reading the rest of the &niInt 4ailover onfiguration section in detail. If a failure occurs at any step below, correct the error and start again at the beginning of step 2 Test in the table below. 4or the discussion below, the first copy of the interface configured and tested will be considered the primary interface and the second copy of the interface configured will be the bac*up interface. Configuration $ne -ata Source Two Interfaces Prere0ui!ite! Interface A is the Primary interface for collection of PI data from the data source. Interface 1 is the Bac*up interface for collection of PI data from the data source. 'ou must setup a shared file. Phase 1? The shared file must store data for five failover tags? "A% (ctive I-, "1% )eartbeat A, "0% )eartbeat 1, "3% -evice Status A and "9% -evice Status 1. 5ach interface must be configured with two re<uired failover command line parameters? "A% its 4ailoverI- number "//F'DID%G "1% the 4ailoverI- number of its Bac*up interface "//F'D'therID%. 'ou must also specify the name of the PI Server host for e/ceptions and PI tag updates. (ll other configuration parameters for the two interfaces must be identical.

O C *&+ Interface

(2

Synchroni;ation through a Shared /ile A hase 2B

#i9ure 1: S8n.)roniBation t)rou9) a S)ared #ile (3)ase 2 #ailover Ar.)ite.ture

The Phase 1 failover architecture is shown in 4igure 1 which depicts a typical networ* setup including the path to the synchroniDation file located on a 4ile Server "4ileSvr%. $ther configurations may be supported and this figure is used only as an e/ample for the following discussion. 4or a more detailed e/planation of this synchroniDation method, see -etailed 5/planation of SynchroniDation through a Shared 4ile "Phase 1%

O C *&+ Interface

("

0niInt /ailover Configuration

Configuring Synchroni;ation through a Shared /ile A hase 2B


Step 1. 2. &escription @eri-8 non!-ailover inter-a.e o*eration as des.ri(ed in t)e 1nstallation C)e.7list se.tion ot)is /anual Configure the Shared /ile C)oose a lo.ation -or t)e s)ared -ile. T)e -ile .an reside on one o- t)e inter-a.e nodes (ut 0S1so-t stron9l8 re.o//ends t)at 8ou *ut t)e -ile on a dedi.ated -ile server t)at )as no ot)er role in data .olle.tion. Setu* a -ile s)are and /a7e sure to assi9n t)e *er/issions so t)at (ot) 3ri/ar8 and Aa.7u* inter-a.es )ave read+,rite a..ess to t)e -ile. Configure the interface parameters Use t)e #ailover se.tion o- t)e 1nter-a.e Con-i9uration Utilit8 (1CU to ena(le -ailover and .reate t,o *ara/eters -or ea.) inter-a.e: (1 a #ailover 1D nu/(er -or t)e inter-a.eP and (2 t)e #ailover 1D nu/(er -or its (a.7u* inter-a.e. T)e #ailover 1D -or ea.) inter-a.e /ust (e uniGue and ea.) inter-a.e /ust 7no, t)e #ailover 1D o- its (a.7u* inter-a.e. 1- t)e inter-a.e .an *er-or/ usin9 eit)er 3)ase 1 or 3)ase 2 *i.7 t)e 3)ase 2 radio (utton in t)e 1CU. Sele.t t)e s8n.)roniBation #ile 3at) and #ile to use -or #ailover. Sele.t t)e t8*e o- -ailover reGuired (Cold, 'ar/, 6ot . T)e .)oi.e de*ends on ,)at t8*es o- -ailover t)e inter-a.e su**orts. 4nsure t)at t)e user na/e assi9ned in t)e RLo9 on as:S *ara/eter in t)e Servi.e se.tion o- t)e 1CU is a user t)at )as read+,rite a..ess to t)e -older ,)ere t)e s)ared -ile ,ill reside. All ot)er .o//and line *ara/eters -or t)e *ri/ar8 and se.ondar8 inter-a.es /ust (e identi.al. 1- 8ou use a 31 Colle.tive, 8ou /ust *oint t)e *ri/ar8 and se.ondar8 inter-a.es to di--erent /e/(ers o- t)e .olle.tive (8 settin9 t)e SD? :e/(er under t)e 31 6ost 1n-or/ation se.tion o- t)e 1CU. J0*tionK Set t)e u*date rate -or t)e )eart(eat *oint i- 8ou need a value ot)er t)an t)e de-ault o- 5000 /illise.onds. Configure the I tags Con-i9ure -ive 31 ta9s -or t)e inter-a.e: t)e A.tive 1D, 6eart(eat 1, 6eart(eat2, Devi.e Status 1 and Devi.e Status 2. Iou .an also .on-i9ure t,o state ta9s -or /onitorin9 t)e status o- t)e inter-a.es. Do not .on-use t)e -ailover Devi.e status ta9s ,it) t)e Uni1nt 6ealt) Devi.e Status ta9s. T)e in-or/ation in t)e t,o ta9s is si/ilar, (ut t)e -ailover devi.e status ta9s are inte9er values and t)e )ealt) devi.e status ta9s are strin9 values. Tag +ctiveI& I/1)*eartbeat (1#!Dode1 I/2)*eartbeat (1#!Dode2 I/1)&eviceStatus (1#!Dode1 I/2)&eviceStatus (1#!Dode2 I/1)State (1#!Dode1 47&esc JU#02HACT1@41DK JU#02H64A<TA4AT:UK JU#02H64A<TA4AT:UK JU#02HD4@1C4STAT:UK JU#02HD4@1C4STAT:UK JU#02HSTAT4:UK 1#HState digitalset Uni1nt does not e$a/ine t)e re/ainin9 attri(utes, (ut t)e *ointsour.e and lo.ation1 /ust /at.)

%.

4.

(%

Step

&escription Tag I/2)State (1#!Dode2 47&esc JU#02HSTAT4:UK digitalset 1#HState Uni1nt does not e$a/ine t)e re/ainin9 attri(utes, (ut t)e *ointsour.e

5.

Test the configuration. A-ter .on-i9urin9 t)e s)ared -ile and t)e inter-a.e and 31 ta9s, t)e inter-a.e s)ould (e read8 to run. See Trou(les)ootin9 Uni1nt #ailover -or )el* resolvin9 #ailover issues.

Start t)e *ri/ar8 inter-a.e intera.tivel8 ,it)out (u--erin9. @eri-8 a su..ess-ul inter-a.e start (8 revie,in9 t)e *i*..lo9 -ile. T)e lo9 -ile ,ill .ontain /essa9es t)at indi.ate t)e -ailover state o- t)e inter-a.e. A su..ess-ul start ,it) onl8 a sin9le inter-a.e .o*8 runnin9 ,ill (e indi.ated (8 an in-or/ational /essa9e statin9 RUni1nt -ailover: 1nter-a.e in t)e R3ri/ar8S state and a.tivel8 sendin9 data to 31. Aa.7u* inter-a.e not availa(le.S 1- t)e inter-a.e )as -ailed to start, an error /essa9e ,ill a**ear in t)e lo9 -ile. #or details relatin9 to in-or/ational and error /essa9es, re-er to t)e :essa9es se.tion (elo,. @eri-8 data on t)e 31 Server usin9 availa(le 31 tools. T)e +ctive I& .ontrol ta9 on t)e 31 Server /ust (e set to t)e value ot)e runnin9 .o*8 o- t)e inter-a.e as de-ined (8 t)e //F'DID startu* .o//and!line *ara/eter. T)e *eartbeat .ontrol ta9 on t)e 31 Server /ust (e .)an9in9 values at a rate s*e.i-ied (8 t)e //F'DInter$ l startu* .o//and!line *ara/eter. Sto* t)e *ri/ar8 inter-a.e. Start t)e (a.7u* inter-a.e intera.tivel8 ,it)out (u--erin9. Doti.e t)at t)is .o*8 ,ill (e.o/e t)e *ri/ar8 (e.ause t)e ot)er .o*8 is sto**ed. <e*eat ste*s 2, %, and 4. Sto* t)e (a.7u* inter-a.e. Start (u--erin9. Start t)e *ri/ar8 inter-a.e intera.tivel8. 0n.e t)e *ri/ar8 inter-a.e )as su..ess-ull8 started and is .olle.tin9 data, start t)e (a.7u* inter-a.e intera.tivel8. @eri-8 t)at (ot) .o*ies o- t)e inter-a.e are runnin9 in a -ailover .on-i9uration. <evie, t)e &i&c.log -ile -or t)e .o*8 o- t)e inter-a.e t)at ,as started -irst. T)e lo9 -ile ,ill .ontain /essa9es t)at indi.ate t)e -ailover state ot)e inter-a.e. T)e state o- t)is inter-a.e /ust )ave .)an9ed as indi.ated ,it) an in-or/ational /essa9e statin9 R%niInt failo+er: Interface in t:e CPrimar;D state and acti+el; sending data to PI. >acG!& interface a+aila le.S 1- t)e inter-a.e )as not .)an9ed to t)is state, (ro,se t)e lo9 -ile -or error /essa9es. #or details relatin9 to in-or/ational and error /essa9es, re-er to t)e :essa9es se.tion (elo,. <evie, t)e &i&c.log -ile -or t)e .o*8 o- t)e inter-a.e t)at ,as started last. T)e lo9 -ile ,ill .ontain /essa9es t)at indi.ate t)e -ailover state ot)e inter-a.e. A su..ess-ul start o- t)e inter-a.e ,ill (e indi.ated (8 an in-or/ational /essa9e statin9 R%niInt failo+er: Interface in t:e C>acG!&D state.S 1- t)e inter-a.e )as -ailed to start, an error /essa9e ,ill a**ear in t)e lo9 -ile. #or details relatin9 to in-or/ational and error /essa9es, re-er to t)e :essa9es se.tion (elo,. @eri-8 data on t)e 31 Server usin9 availa(le 31 tools.

O C *&+ Interface

($

0niInt /ailover Configuration


Step &escription

T)e +ctive I& .ontrol ta9 on t)e 31 Server /ust (e set to t)e value ot)e runnin9 .o*8 o- t)e inter-a.e t)at ,as started -irst as de-ined (8 t)e //F'DID startu* .o//and!line *ara/eter. T)e *eartbeat .ontrol ta9s -or (ot) .o*ies o- t)e inter-a.e on t)e 31 Server /ust (e .)an9in9 values at a rate s*e.i-ied (8 t)e //F'DInter$ l startu* .o//and!line *ara/eter or t)e s.an .lass ,)i.) t)e *oints )ave (een (uilt a9ainst. Test #ailover (8 sto**in9 t)e *ri/ar8 inter-a.e. @eri-8 t)e (a.7u* inter-a.e )as assu/ed t)e role o- *ri/ar8 (8 sear.)in9 t)e &i&c.log -ile -or a /essa9e indi.atin9 t)e (a.7u* inter-a.e )as .)an9ed to t)e R%niInt failo+er: Interface in t:e CPrimar;D state and acti+el; sending data to PI. >acG!& interface not a+aila le.S T)e (a.7u* inter-a.e is no, .onsidered *ri/ar8 and t)e *revious *ri/ar8 inter-a.e is no, (a.7u*. @eri-8 no loss o- data in 31. T)ere /a8 (e an overla* o- data due to t)e Gueuin9 o- data. 6o,ever, t)ere /ust (e no data loss. Start t)e (a.7u* inter-a.e. 0n.e t)e *ri/ar8 inter-a.e dete.ts a (a.7u* inter-a.e, t)e *ri/ar8 inter-a.e ,ill no, .)an9e state indi.atin9 R %niInt failo+er: Interface in t:e CPrimar;D state and acti+el; sending data to PI. >acG!& interface a+aila le.S 1n t)e &i&c.log -ile. @eri-8 t)e (a.7u* inter-a.e starts and assu/es t)e role o- (a.7u*. A su..ess-ul start o- t)e (a.7u* inter-a.e ,ill (e indi.ated (8 an in-or/ational /essa9e statin9 R%niInt failo+er: Interface in C>acG!& state.D Sin.e t)is is t)e initial state o- t)e inter-a.e, t)e in-or/ational /essa9e ,ill (e near t)e (e9innin9 o- t)e start seGuen.e o- t)e &i&c.log -ile. Test -ailover ,it) di--erent -ailure s.enarios (e.9. loss o- 31 .onne.tion -or a sin9le inter-a.e .o*8 . Uni1nt -ailover 9uarantees no data loss ,it) a sin9le *oint o- -ailure. @eri-8 no data loss (8 .)e.7in9 t)e data in 31 and on t)e data sour.e. Sto* (ot) .o*ies o- t)e inter-a.e, start (u--erin9, start ea.) inter-a.e as a servi.e. @eri-8 data as stated a(ove. To desi9nate a s*e.i-i. inter-a.e as *ri/ar8. Set t)e +ctive I& *oint on t)e Data Sour.e Server o- t)e desired *ri/ar8 inter-a.e as de-ined (8 t)e //F'DID startu* .o//and!line *ara/eter.

((

Configuring 0niInt /ailover through a Shared /ile A hase 2B


Start<0p arameters
1ote8 T)e /stopst t *ara/eter is disa(led 1- t)e inter-a.e is runnin9 in a Uni1nt -ailover .on-i9uration. T)ere-ore, t)e di9ital state, digstate, ,ill not (e ,ritten to ea.) 31 3oint ,)en t)e inter-a.e is sto**ed. T)is *revents t)e di9ital state (ein9 ,ritten to 31 3oints ,)ile a redundant s8ste/ is also ,ritin9 data to t)e sa/e 31 3oints. T)e /stopst t *ara/eter is disa(led even i- t)ere is onl8 one inter-a.e a.tive in t)e -ailover .on-i9uration.

The following table lists the start!up parameters used by &niInt 4ailover Phase 1. (ll of the parameters are re<uired e/cept the //F'DInter$ l startup parameter. See the table below for further e/planation.
arameter 6e:uired2 Optional <eGuired &escription #ailover 1D -or 1#!Dode1 T)is value /ust (e di--erent -ro/ t)e -ailover 1D o- 1#!Dode2. #ailover 1D -or 1#!Dode2 T)is value /ust (e di--erent -ro/ t)e -ailover 1D o- 1#!Dode1. 0t)er #ailover 1D -or 1#!Dode1 T)e value /ust (e eGual to t)e #ailover 1D .on-i9ured -or t)e inter-a.e on 1#!Dode2. 0t)er #ailover 1D -or 1#!Dode2 T)e value /ust (e eGual to t)e #ailover 1D .on-i9ured -or t)e inter-a.e on 1#!Dode1. T)e #ailover #ile S8n.)roniBation #ile*at) and 0*tional #ilena/e s*e.i-8 t)e *at) to t)e s)ared -ile used -or -ailover s8n.)roniBation and an o*tional -ilena/e used to s*e.i-8 a user de-ined -ilena/e in lieu o- t)e de-ault -ilena/e. T)e path to t)e s)ared -ile dire.tor8 .an (e a -ull8 Guali-ied /a.)ine na/e and dire.tor8, a /a**ed drive letter, or a lo.al *at) i- t)e s)ared -ile is on one o- t)e inter-a.e nodes. T)e path /ust (e ter/inated (8 a slas) ( ? or (a.7slas) ( \ .)ara.ter. 1- no ter/inatin9 slas) is -ound, in t)e //F'DSAnc *ara/eter, t)e inter-a.e inter*rets t)e -inal .)ara.ter strin9 as an o*tional filename. T)e o*tional filename .an (e an8 valid -ilena/e. 1- t)e -ile does not Calue2&efault An8 *ositive, non! Bero inte9er + 1 An8 *ositive, non! Bero inte9er + 2 Sa/e value as #ailover 1D -or 1#!Dode2 + 2 Sa/e value as #ailover 1D -or 1#!Dode1 + 1 An8 valid *at)na/e + an8 valid -ilena/e T)e de-ault -ilena/e is 9enerated as executablenameH pointsourceH interfaceID.dat

//F'DID=#

<eGuired

//F'D'therID=#

<eGuired

<eGuired

//F'DSAnc= p th/Efilen meF

<eGuired -or 3)ase 2 s8n.)roniBation

O C *&+ Interface

(,

0niInt /ailover Configuration


arameter 6e:uired2 Optional &escription e$ist, t)e -irst inter-a.e to start atte/*ts to .reate t)e -ile. 1ote8 1- usin9 t)e o*tional -ilena/e, do not su**l8 a ter/inatin9 slas) or (a.7slas) .)ara.ter. 1- t)ere are an8 s*a.es in t)e path or filename, t)e entire *at) and -ilena/e /ust (e en.losed in Guotes. 1ote8 1- 8ou use t)e (a.7slas) and *at) se*arators and en.lose t)e *at) in dou(le Guotes, t)e -inal (a.7slas) /ust (e a dou(le (a.7slas) (\\ . 0t)er,ise t)e .losin9 dou(le Guote (e.o/es *art o- t)e *ara/eter instead o- a *ara/eter se*arator. 4a.) node in t)e -ailover .on-i9uration /ust s*e.i-8 t)e sa/e *at) and -ilena/e and /ust )ave read, ,rite, and -ile .reation ri9)ts to t)e s)ared dire.tor8 s*e.i-ied (8 t)e path *ara/eter. T)e servi.e t)at t)e inter-a.e runs a9ainst /ust s*e.i-8 a valid lo9on user a..ount under t)e RLo9 0nS ta( -or t)e servi.e *ro*erties. Calue2&efault

//F'D+Ape=tApe

<eGuired

T)e #ailover T8*e indi.ates ,)i.) t8*e o- -ailover .on-i9uration t)e inter-a.e ,ill run. T)e valid t8*es -or -ailover are 60T, 'A<:, and C0LD .on-i9urations. 1- an inter-a.e does not su**orted t)e reGuested t8*e o- -ailover, t)e inter-a.e ,ill s)utdo,n and lo9 an error to t)e &i&c.log -ile statin9 t)e reGuested -ailover t8*e is not su**orted. #ailover U*date 1nterval S*e.i-ies t)e )eart(eat U*date 1nterval in /illise.onds and /ust (e t)e sa/e on (ot) inter-a.e .o/*uters. T)is is t)e rate at ,)i.) Uni1nt u*dates t)e #ailover 6eart(eat ta9s as ,ell as )o, o-ten Uni1nt .)e.7s on t)e status o- t)e ot)er .o*8 o- t)e inter-a.e.

C0LDZ'A<:Z60T + COL&

//F'DInter$ l=#

0*tional

50 W 20000 + 1...

(-

arameter

/Host=ser$er

6e:uired2 Optional <eGuired

&escription 6ost 31 Server -or 4$.e*tions and 31 ta9 u*dates T)e value o- t)e /Host startu* *ara/eter de*ends on t)e 31 Server .on-i9uration. 1- t)e 31 Server is not *art o- a .olle.tive, t)e value o- /Host /ust (e identi.al on (ot) inter-a.e .o/*uters. 1- t)e redundant inter-a.es are (ein9 .on-i9ured to send data to a 31 Server .olle.tive, t)e value ot)e /Host *ara/eters on t)e di--erent inter-a.e nodes s)ould eGual to di--erent /e/(ers o- t)e .olle.tive. T)is *ara/eter ensures t)at out*uts .ontinue to (e sent to t)e Data Sour.e i- one o- t)e 31 Servers (e.o/es unavaila(le -or an8 reason.

Calue2&efault #or 1#!Dode1 3ri/ar831 + 1one #or 1#!Dode2 Se.ondar831 + 1one

/ailover Control oints


The following table describes the points that are re<uired to manage failover. In Phase 1 4ailover, these points are located in a data file shared by the Primary and Bac*up interfaces. $SIsoft recommends that you locate the shared file on a dedicated server that has no other role in data collection. This avoids potential resource contention and processing degradation if your system monitors a large number of data points at a high fre<uency.
oint +ctiveI& &escription :onitored (8 t)e inter-a.es to deter/ine ,)i.) inter-a.e is .urrentl8 sendin9 data to 31. +ctiveI& /ust (e initialiBed so t)at ,)en t)e inter-a.es read it -or t)e -irst ti/e, it is not an error. +ctiveI& .an also (e used to -or.e -ailover. #or e$a/*le, i- t)e .urrent 3ri/ar8 is 1#!Dode 1 and +ctiveI& is 1, 8ou .an /anuall8 .)an9e +ctiveI& to 2. T)is .auses t)e inter-a.e at 1#! Dode2 to transition to t)e *ri/ar8 role and t)e inter-a.e at 1#!Dode1 to transition to t)e (a.7u* role. U*dated *eriodi.all8 (8 t)e inter-a.e on 1#!Dode1. T)e inter-a.e on 1#!Dode2 /onitors t)is value to deter/ine i- t)e inter-a.e on 1#!Dode1 )as (e.o/e unres*onsive. U*dated *eriodi.all8 (8 t)e inter-a.e on 1#! Dode2. T)e inter-a.e on 1#!Dode1 /onitors t)is value to deter/ine i- t)e inter-a.e on 1#!Dode2 )as (e.o/e unres*onsive. Calue 2 &efault #ro/ 0 to t)e )i9)est 1nter-a.e #ailover 1D nu/(er + 1one U*dated (8 t)e redundant 1nter-a.es Can (e .)an9ed /anuall8 to initiate a /anual -ailover

*eartbeat 1

@alues ran9e (et,een 0 and %1 + 1one U*dated (8 t)e 1nter-a.e on 1#!Dode1 @alues ran9e (et,een 0 and %1 + 1one U*dated (8 t)e 1nter-a.e on 1#!Dode2

*eartbeat 2

O C *&+ Interface

(!

0niInt /ailover Configuration

I Tags
The following tables list the re<uired &niInt 4ailover ontrol PI tags, the values they will receive, and descriptions. Active?ID %ag Configuration
+ttributes Ta9 4$Des. Lo.ation1 Lo.ation5 3oint Sour.e 3oint T8*e S)utdo,n Ste* +ctiveI& DIntfE)+ctiveI& JU#02HA.tive1DK :at.) U in /id=# 0*tional, Ti/e in /in to ,ait -or (a.7u* to .olle.t data (e-ore -ailin9 over. :at.) $ in /ps=x 1nt%2 0 1

Heart-eat and Device #tatu! %ag Configuration


+ttribute Ta9 4$Des. Lo.ation1 Lo.ation5 *eartbeat 1 [6A1\
JU#02H6eart(eat:UK :at.) U in //F'DID=#

*eartbeat 2 [6A2\
JU#02H6eart(eat:UK :at.) U in //F'D'therID=#

&eviceStatus 1 [DS1\
JU#02HDevi.eStat:UK :at.) U in //F'DID=#

&eviceStatus 2 [DS2\
JU#02HDevi.eStat:UK :at.) U in

//F'D'therID= #
:at.) U in /id=# 0*tional, Ti/e in /in to ,ait -or (a.7u* to .olle.t data (e-ore -ailin9 over. :at.) $ in /ps=x int%2 0 1

:at.) U in /id=# 0*tional, Ti/e in /in to ,ait -or (a.7u* to .olle.t data (e-ore -ailin9 over. :at.) $ in /ps=x int%2 0 1

:at.) U in /id=# 0*tional, Ti/e in /in to ,ait -or (a.7u* to .olle.t data (e-ore -ailin9 over. :at.) $ in /ps=x int%2 0 1

:at.) U in /id=# 0*tional, Ti/e in /in to ,ait -or (a.7u* to .olle.t data (e-ore -ailin9 over. :at.) $ in /ps=x int%2 0 1

3oint Sour.e 3oint T8*e S)utdo,n Ste*

Interface #tate %ag Configuration


+ttribute Ta9 Di9italSet 4$Des. Lo.ation1 3ointSour.e 3ointT8*e S)utdo,n rimary [Ta9na/e1\ U#0HState JU#02HState:UK (:at.),//F'DID=# on *ri/ar8 node :at.) U in /id=# :at.) $ in /ps=x di9ital 0 3ac#up [Ta9na/e2\ U#0HState JU#02HState:UK (:at.) //F'DID=# on (a.7u* node Sa/e as -or 3ri/ar8 node Sa/e as -or 3ri/ar8 node di9ital 0

,.

+ttribute Ste* 1

rimary

3ac#up 1

The following table describes the e/tended descriptor for the above PI tags in more detail.
I Tag 47&esc JU#02HACT1@41DK 6e:uired 2 Optional <eGuired &escription A.tive 1D ta9 T)e 4$Des. /ust start ,it) t)e .ase sensitive strin9: JU#02HACT1@41DK. T)e *ointsour.e /ust /at.) t)e inter-a.es= *oint sour.e. Lo.ation1 /ust /at.) t)e 1D -or t)e inter-a.es. Lo.ation5 is t)e C0LD -ailover retr8 interval in /inutes. T)is .an (e used to s*e.i-8 )o, lon9 (e-ore an inter-a.e retries to .onne.t to t)e devi.e in a C0LD -ailover .on-i9uration. (See t)e des.ri*tion o- C0LD -ailover retr8 interval -or a detailed e$*lanation. 6eart(eat 1 Ta9 T)e 4$Des. /ust start ,it) t)e .ase sensitive strin9: JU#02H64A<TA4AT:UK T)e nu/(er -ollo,in9 t)e .olon ( /ust (e t)e #ailover 1D -or t)e inter-a.e runnin9 on 1#!Dode1. T)e *ointsour.e /ust /at.) t)e inter-a.es= *oint sour.e. Lo.ation1 /ust /at.) t)e 1D -or t)e inter-a.es. 6eart(eat 2 Ta9 T)e 4$Des. /ust start ,it) t)e .ase sensitive strin9: JU#02H64A<TA4AT:UK T)e nu/(er -ollo,in9 t)e .olon ( /ust (e t)e #ailover 1D -or t)e inter-a.e runnin9 on 1#!Dode2. T)e *ointsour.e /ust /at.) t)e inter-a.es= *oint sour.e. Lo.ation1 /ust /at.) t)e id -or t)e inter-a.es. Calue 0 W )i9)est 1nter-a.e #ailover 1D U*dated (8 t)e redundant 1nter-a.es

JU#02H64A<TA4AT:UK (1#!Dode1

<eGuired

0 W %1 + 1one U*dated (8 t)e 1nter-a.e on 1#!Dode1

JU#02H64A<TA4AT:UK (1#!Dode2

<eGuired

0 W %1 + 1one U*dated (8 t)e 1nter-a.e on 1#!Dode2

O C *&+ Interface

,1

0niInt /ailover Configuration


I Tag 47&esc JU#02HD4@1C4STAT :UK (1#!Dode1 6e:uired 2 Optional <eGuired &escription Devi.e Status 1 Ta9 T)e 4$Des. /ust start ,it) t)e .ase sensitive strin9: JU#02H64A<TA4AT:UK T)e value -ollo,in9 t)e .olon ( /ust (e t)e #ailover 1D -or t)e inter-a.e runnin9 on 1#!Dode1 T)e *ointsour.e /ust /at.) t)e inter-a.es= *oint sour.e. Lo.ation1 /ust /at.) t)e id -or t)e inter-a.es. A lo,er value is a (etter status and t)e inter-a.e ,it) t)e lo,er status ,ill atte/*t to (e.o/e t)e *ri/ar8 inter-a.e. T)e -ailover 1 devi.e status ta9 is ver8 si/ilar to t)e Uni1nt 6ealt) Devi.e Status ta9 e$.e*t t)e data ,ritten to t)is ta9 are inte9er values. A value o- 0 is 9ood and a value o- 99 is 0##. An8 value (et,een t)ese t,o e$tre/es /a8 result in a -ailover. T)e inter-a.e .lient .ode u*dates t)ese values ,)en t)e )ealt) devi.e status ta9 is u*dated. Devi.e Status 2 Ta9 T)e 4$Des. /ust start ,it) t)e .ase sensitive strin9: JU#02H64A<TA4AT:UK T)e nu/(er -ollo,in9 t)e .olon ( /ust (e t)e #ailover 1D -or t)e inter-a.e runnin9 on 1#!Dode2 T)e *ointsour.e /ust /at.) t)e inter-a.es= *oint sour.e. Lo.ation1 /ust /at.) t)e 1D -or t)e inter-a.es. A lo,er value is a (etter status and t)e inter-a.e ,it) t)e lo,er status ,ill atte/*t to (e.o/e t)e *ri/ar8 inter-a.e. State 1 Ta9 T)e 4$Des. /ust start ,it) t)e .ase sensitive strin9: JU#02HSTAT4:UK T)e nu/(er -ollo,in9 t)e .olon ( /ust (e t)e #ailover 1D -or t)e inter-a.e runnin9 on 1#!Dode1 T)e -ailover state ta9 is re.o//ended. T)e -ailover state ta9s are di9ital ta9s assi9ned to a di9ital state set ,it) t)e -ollo,in9 values. 0 T 0--: T)e inter-a.e )as (een s)ut do,n. 1 T Aa.7u* Do Data Sour.e: T)e Calue 0 W 99 + 1one U*dated (8 t)e 1nter-a.e on 1#!Dode1

JU#02HD4@1C4STAT :UK (1#!Dode2

<eGuired

0 W 99 + 1one U*dated (8 t)e 1nter-a.e on 1#!Dode2

JU#02HSTAT4:UK (1#!Dode1

0*tional

0 W 5 + 1one Dor/all8 u*dated (8 t)e 1nter-a.e .urrentl8 in t)e *ri/ar8 role.

,2

I Tag 47&esc

6e:uired 2 Optional

&escription inter-a.e is runnin9 (ut .annot .o//uni.ate ,it) t)e data sour.e. 2 T Aa.7u* Do 31 Conne.tion: T)e inter-a.e is runnin9 and .onne.ted to t)e data sour.e (ut )as lost its .o//uni.ation to t)e 31 Server. % T Aa.7u*: T)e inter-a.e is runnin9 and .olle.tin9 data nor/all8 and is read8 to ta7e over as *ri/ar8 i- t)e *ri/ar8 inter-a.e s)uts do,n or e$*erien.es *ro(le/s. 4 T Transition: T)e inter-a.e sta8s in t)is state -or onl8 a s)ort *eriod o- ti/e. T)e transition *eriod *revents t)ras)in9 ,)en /ore t)an one inter-a.e atte/*ts to assu/e t)e role o- *ri/ar8 inter-a.e. 5 T 3ri/ar8: T)e inter-a.e is runnin9, .olle.tin9 data and sendin9 t)e data to 31.

Calue

JU#02HSTAT4:UK (1#!Dode2

0*tional

State 2 Ta9 T)e 4$Des. /ust start ,it) t)e .ase sensitive strin9: JU#02HSTAT4:UK T)e nu/(er -ollo,in9 t)e .olon ( /ust (e t)e #ailover 1D -or t)e inter-a.e runnin9 on 1#!Dode2 T)e -ailover state ta9 is re.o//ended.

Dor/all8 u*dated (8 t)e 1nter-a.e .urrentl8 in t)e 3ri/ar8 state. @alues ran9e (et,een 0 and 5. See des.ri*tion oState 1 ta9.

O C *&+ Interface

,"

0niInt /ailover Configuration

&etailed 47planation of Synchroni;ation through a Shared /ile A hase 2B


In a shared file failover configuration, there is no direct failover control information passed between the data source and the interface. This failover scheme uses five PI tags to control failover operation, and all failover communication between primary and bac*up interfaces passes through a shared data file. $nce the interface is configured and running, the ability to read or write to the PI tags is not re<uired for the proper operation of failover. This solution does not re<uire a connection to the PI Server after initial startup because the control point data are set and monitored in the shared file. )owever, the PI tag values are sent to the PI Server so that you can monitor them with standard $SIsoft client tools. 'ou can force manual failover by changing the #ctiveID on the data source to the bac*up failover I-.

The figure above shows a typical networ* setup in the normal or steady state. The solid magenta lines show the data path from the interface nodes to the shared file used for failover synchroniDation. The shared file can be located anywhere in the networ* as long as both interface nodes can read, write, and create the necessary file on the shared file machine. $SIsoft strongly recommends that you put the file on a dedicated file server that has no other role in the collection of data. The maCor difference between synchroniDing the interfaces through the data source "Phase A% and synchroniDing the interfaces through the shared file "Phase 1% is where the control data is located. #hen synchroniDing through the data source, the control data is ac<uired directly from the data source. #e assume that if the primary interface cannot read the failover control
,%

points, then it cannot read any other data. There is no need for a bac*up communications path between the control data and the interface. #hen synchroniDing through a shared file, however, we cannot assume that loss of control information from the shared file implies that the primary interface is down. #e must account for the possible loss of the path to the shared file itself and provide an alternate control path to determine the status of the primary interface. 4or this reason, if the shared file is unreachable for any reason, the interfaces use the PI Server as an alternate path to pass control data. #hen the bac*up interface does not receive updates from the shared file, it cannot tell definitively why the primary is not updating the file, whether the path to the shared file is down, whether the path to the data source is down, or whether the interface itself is having problems. To resolve this uncertainty, the bac*up interface uses the path to the PI Server to determine the status of the primary interface. If the primary interface is still communicating with the PI Server, than failover to the bac*up is not re<uired. )owever, if the primary interface is not posting data to the PI Server, then the bac*up must initiate failover operations. The primary interface also monitors the connection with the shared file to maintain the integrity of the failover configuration. If the primary interface can read and write to the shared file with no errors but the bac*up control information is not changing, then the bac*up is e/periencing some error condition. To determine e/actly where the problem e/ists, the primary interface uses the path to PI to establish the status of the bac*up interface. 4or e/ample, if the bac*up interface controls indicate that it has been shutdown, it may have been restarted and is now e/periencing errors reading and writing to the shared file. Both primary and bac*up interfaces must always chec* their status through PI to determine if one or the other is not updating the shared file and why.

Steady State Operation


Steady state operation is considered the normal operating condition. In this state, the primary interface is actively collecting data and sending its data to PI. The primary interface is also updating its heartbeat valueG monitoring the heartbeat value for the bac*up interface, chec*ing the active I- value, and chec*ing the device status for the bac*up interface every failover update interval on the shared file. 8i*ewise, the bac*up interface is updating its heartbeat valueG monitoring the heartbeat value for the primary interface, chec*ing the active I- value, and chec*ing the device status for the primary interface every failover update interval on the shared file. (s long as the heartbeat value for the primary interface indicates that it is operating properly, the #ctiveID has not changed, and the device status on the primary interface is good, the bac*up interface will continue in this mode of operation. (n interface configured for hot failover will have the bac*up interface actively collecting and <ueuing data but not sending that data to PI. (n interface for warm failover in the bac*up role is not actively collecting data from the data source even though it may be configured with PI tags and may even have a good connection to the data source. (n interface configured for cold failover in the bac*up role is not connected to the data source and upon initial startup will not have configured PI tags. The interaction between the interface and the shared file is fundamental to failover. The discussion that follows only refers to the data written to the shared file. )owever, every value written to the shared file is echoed to the tags on the PI Server. &pdating of the tags on the PI Server is assumed to ta*e place unless communication with the PI Server is interrupted. The updates to the PI Server will be buffered by bufserv or BufSS in this case.

O C *&+ Interface

,$

0niInt /ailover Configuration In a hot failover configuration, each interface participating in the failover solution will <ueue three failover intervals worth of data to prevent any data loss. #hen a failover occurs, there may be a period of overlapping data for up to 0 intervals. The e/act amount of overlap is determined by the timing and the cause of the failover and may be different every time. &sing the default update interval of 9 seconds will result in overlapping data between : and A9 seconds. The no data loss claim for hot failover is based on a single point of failure. If both interfaces have trouble collecting data for the same period of time, data will be lost during that time. (s mentioned above, each interface has its own heartbeat value. In normal operation, the )eartbeat value on the shared file is incremented by &niInt from A K A9 and then wraps around to a value of A again. &niInt increments the heartbeat value on the shared file every failover update interval. The default failover update interval is 9 seconds. &niInt also reads the heartbeat value for the other interface copy participating in failover every failover update interval. If the connection to the PI Server is lost, the value of the heartbeat will be incremented from AO K 0A and then wrap around to a value of AO again. $nce the connection to the PI Server is restored, the heartbeat values will revert bac* to the A K A9 range. -uring a normal shutdown process, the heartbeat value will be set to Dero. -uring steady state, the #ctiveID will e<ual the value of the failover I- of the primary interface. This value is set by &niInt when the interface enters the primary state and is not updated again by the primary interface until it shuts down gracefully. -uring shutdown, the primary interface will set the #ctiveID to Dero before shutting down. The bac*up interface has the ability to assume control as primary even if the current primary is not e/periencing problems. This can be accomplished by setting the #ctiveID tag on the PI Server to the #ctiveID of the desired interface copy. (s previously mentioned, in a hot failover configuration the bac*up interface actively collects data but does not send its data to PI. To eliminate any data loss during a failover, the bac*up interface <ueues data in memory for three failover update intervals. The data in the <ueue is continuously updated to contain the most recent data. -ata older than three update intervals is discarded if the primary interface is in a good status as determined by the bac*up. If the bac*up interface transitions to the primary, it will have data in its <ueue to send to PI. This <ueued data is sent to PI using the same function calls that would have been used had the interface been in a primary state when the function call was received from &niInt. If &niInt receives data without a timestamp, the primary copy uses the current PI time to timestamp data sent to PI. 8i*ewise, the bac*up copy timestamps data it receives without a timestamp with the current PI time before <ueuing its data. This preserves the accuracy of the timestamps.

,(

/ailover Configuration 0sing I IC0


The use of the PI I & is the recommended and safest method for configuring the Interface for &niInt failover. #ith the e/ception of the notes described in this section, the Interface shall be configured with the PI I & as described in the = onfiguring the Interface with the PI I &> section of this manual.
1ote8 'it) t)e e$.e*tion o- t)e //F'DID and //F'D'therID startu* .o//and! line *ara/eters, t)e Uni1nt -ailover s.)e/e reGuires t)at (ot) .o*ies o- t)e inter-a.e )ave identi.al startu* .o//and -iles. T)is reGuire/ent .auses t)e 31 1CU to *rodu.e a /essa9e ,)en .reatin9 t)e se.ond .o*8 o- t)e inter-a.e statin9 t)at t)e R3S+1D .o/(o alread8 in use (8 t)e inter-a.eS as s)o,n in #i9ure 2 (elo,. 19nore t)is /essa9e and .li.7 t)e dd (utton.

Create the Interface Instance 9ith I IC0


If the interface does not already e/ist in the I & it must first be created. The procedure for doing this is the same as for non!failover interfaces. #hen configuring the second instance for &niInt 4ailover the Point Source and Interface I- will be in yellow and a message will be displayed saying this is already in use. This should be ignored.

4igure 1? PI I & configuration screen shows that the =PS,I- combo is already in use by the interface.> The user must ignore the yellow bo/es, which indicate errors, and clic* the Add button to configure the interface for failover.

O C *&+ Interface

,,

0niInt /ailover Configuration

Configuring the 0niInt /ailover Startup arameters 9ith I IC0


There are three interface startup parameters that control &niInt failover? //F'DID, //F'D'therID, and //F'DInter$ l. The %FO stands for &niInt 4ailover. The //F'DID and //F'D'therID parameters are re<uired for the interface to operate in a failover configuration, but the //F'DInter$ l is optional. 5ach of these parameters is described in detail in onfiguring &niInt 4ailover through a Shared 4ile "Phase 1% section and Start!&p Parameters.

4igure 0? The figure above illustrates the PI I & failover configuration screen showing the &niInt failover startup parameters "Phase 1%. This copy of the interface defines its 4ailover I- as 1 "//F'DID=9) and the other interfaces 4ailover I- as A "//F'D'therID=1). The other failover interface copy must define its 4ailover I- as A "//F'DID=1) and the other interface 4ailover I- as 1 " //F'D'therID=9) in its I & failover configuration screen. It also defines the location and name of the synchroniDation file as well as the type of failover as $8-.

Creating the /ailover State &igital State Set


The &4$HState digital state set is used in conCunction with the failover state digital tag. If the &4$HState digital state set has not been created yet, it can be using either the 4ailover page of the I & "A.3.A.: or greater% or the -igital States plug!in in the S+T 0 &tility "0.:.:.O or greater%.

,-

0sing the I IC0 0tility to create &igital State Set


To use the &niInt 4ailover page to create the &4$HState digital state set right clic* on any of the failover tags in the tag list and then select the = reate &4$HState -igital Set on Server [[[[[[J>, where [[[[[[ is the PI Server where the points will be or are create on.

This choice will be grayed out if the &4$HState digital state set is already created on the [[[[[[ PI Server.

0sing the I S'T " 0tility to create &igital State Set


$ptionally the =5/port &4$HState -igital Set ".csv% can be selected to create a comma separated file to be imported via the System +anangement Tools "S+T0% "version 0.:.:.O or higher% or use the %niInt8Failo+er8,igital(et8%FO8(tate.cs+ file included in the installation *it. The procedure below outlines the steps necessary to create a digital set on a PI Sever using the =Import from 4ile> function found in the S+T0 application. The procedure assumes the user has a basic understanding of the S+T0 application. A. $pen the S+T0 application. 1. Select the appropriate PI Server from the PI Servers window. If the desired server is not listed, add it using the PI onnection +anager. ( view of the S+T application is shown in 4igure 3 below. 0. 4rom the System +anagement Plug!Ins window, select Points then -igital States. ( list of available digital state sets will be displayed in the main window for the selected PI Server. Befer to 4igure 3 below. 3. In the main window, right clic* on the desired server and select the =Import from 4ile> option. Befer to 4igure 3 below.

O C *&+ Interface

,!

0niInt /ailover Configuration

4igure 3? PI S+T application configured to import a digital state set file. The PI Servers window shows the =localhost> PI Server selected along with the System +anagement Plug!Ins window showing the -igital States Plug!In as being selected. The digital state set file can now be imported by selecting the Import from 4ile option for the localhost. 9. Navigate to and select the %niInt8Failo+er8,igital(et8%FO8(tate.cs+ file for import using the Browse icon on the display. Select the desired $verwrite $ptions. lic* on the &( button. Befer to 4igure 9 below.

4igure 9? PI S+T application Import -igital Set"s% window. This view shows the %niInt8Failo+er8,igital(et8%FO8(tate.cs+ file as being selected for import. Select the desired $verwrite $ptions by choosing the appropriate radio button.

-.

2. Navigate to and select the %niInt8Failo+er8,igital(et8%FO8(tate.cs+ file for import using the Browse icon on the display. Select the desired $verwrite $ptions. lic* on the &( button. Befer to 4igure 9 above. O. The %FO8(tate digital set is created as shown in 4igure 2 below.

4igure 2? The PI S+T application showing the %FO8(tate digital set created on the =localhost> PI Server.

O C *&+ Interface

-1

0niInt /ailover Configuration

Creating the 0niInt /ailover Control and /ailover State Tags A hase 2B
The I & can be used to create the &niInt 4ailover ontrol and State Tags. To use the I & 4ailover page to create these tags simply right clic* any of the failover tags in the tag list and select the = reate all points "&4$ Phase 1%> menu item. If this menu choice is grayed out it is because the &4$HState digital state set has not been created on the Server yet. There is a menu choice = reate &4$HState -igitial Set on Server ///////J> which can be used to create that digital state set. $nce this has been done then the = reate all points "&4$ Phase1% should be available.

$nce the failover control and failover state tags have been created the 4ailover page of the I & should loo* similar to the illustration below.

-2

Chapter 12.

Interface 1ode Cloc#

+a*e sure that the time and time Done settings on the computer are correct. To confirm, run the -ate,Time applet located in the #indows ontrol Panel. If the locale where the Interface Node resides observes -aylight Saving Time, chec* the = Automaticall! ad6ust cloc7 for da!light saving changes> bo/. 4or e/ample,

In addition, ma*e sure that the TL environment variable is not defined. (ll of the currently defined environment variables can be viewed by opening a ommand Prompt window and typing set. That is,
C:= set

onfirm that TL is not in the resulting list. If it is, run the System applet of the ontrol Panel, clic* the =.nvironment 8ariables9 button under the (dvanced Tab, and remove TL from the list of environment variables.

O C *&+ Interface

-"

Chapter 1".

Security

=indo9s
The PI 4irewall -atabase and the PI Pro/y -atabase must be configured so that the interface is allowed to write data to the PI Server. See =+odifying the 4irewall -atabase> and =+odifying the Pro/y -atabase> in the PI Server manuals. Note that the Trust -atabase, which is maintained by the Base Subsystem, replaces the Pro/y -atabase used prior to PI version 0.0. The Trust -atabase maintains all the functionality of the pro/y mechanism while being more secure. See =Trust 8ogin Security> in the chapter =+anaging Security> of the PI Server S!stem Management 'uide. If the interface cannot write data to the PI Server because it has insufficient privileges, a !.L$L. error will be reported in the &i&c.log file. If the interface cannot send data to a PI1 Serve, it writes a 7BBB error. See the section (ppendi/ (? 5rror and Informational +essages for additional information on error messaging. I Server v"." and *igher #ecurity configuration u!ing &iconfig 4or PI Server v0.0 and higher, the following e/ample demonstrates how to edit the PI Trust table?
C:\PI\adm= &iconfig Ata le &itr!st Amode create Aistr 'r!stEIP2ddrE<etMasGEPI%ser a8tr!st8nameE.B/..68..LL...E/11./11./11./11E&iadmin A)!it

4or the above,


'r!st? (n arbitrary name for the trust table entryG in the above e/ample, a8tr!st8name IP2ddr? the IP (ddress of the computer running the InterfaceG in the above e/ample, .B/..68..LL... <etMasG? the networ* mas*G /11./11./11./11 specifies an e/act match with IP2ddr PI%ser? the PI user the Interface to be entrusted asG &iadmin is usually an appropriate user

O C *&+ Interface

-$

#ecurity Configuring u!ing %ru!t Editor The Trust 5ditor plug!in for PI System +anagement Tools 0./ may also be used to edit the PI Trust table. See the PI System +anagement chapter in the PI Server manual for more details on security configuration. I Server v".2 4or PI Server v0.1, the following e/ample demonstrates how to edit the PI Pro/y table?
C:\PI\adm= &iconfig Ata le &i8genE&i&rox; Amode create Aistr :ostE&rox;acco!nt &ia&imac:ineE&iadmin A)!it

In place of &ia&imac:ine, put the name of the PI Interface node as it is seen b! PI Server.

O C *&+ Interface

-(

Chapter 1%.

Starting 2 Stopping the Interface

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 Service


If the Interface was installed as service, it can be started from PI I &, the Services control panel or with the command?
PIOPCH,2Int.exe 9start

To start the interface service with PI I &, use the

button on the PI I & toolbar.

( message will inform the user of the status of the interface service. 5ven if the message indicates that the service has started successfully, double chec* 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 . at file. @erify that the root name of the . at file and the .exe file are the same, and that the . at file and the .exe file are in the same directory. 4urther troubleshooting of services might re<uire consulting the &i&c.log file, #indows 5vent @iewer, or other sources of log messages. See the section (ppendi/ (? 5rror and Informational +essages for additional information.

Stopping Interface 6unning as a Service


If the Interface was installed as service, it can be stopped at any time from PI I &, the Services control panel or with the command?
PIOPCH,2Int.exe 9sto&

The service can be removed by?


PIOPCH,2Int.exe 9remo+e

To stop the interface service with PI I &, use the

button on the PI I & toolbar.

O C *&+ Interface

-,

Chapter 1$.

3uffering

Buffering refers to an Interface Nodes ability to temporarily store the data that interfaces collect and to forward these data to the appropriate PI Servers. $SIsoft strongly recommends that you enable buffering on your Interface Nodes. $therwise, if the Interface Node stops communicating with the PI Server, you lose the data that your interfaces collect. The PI S-. installation *it installs two buffering applications? the PI Buffer Subsystem "PIBufss% and the PI (PI Buffer Server "Bufserv%. PIBufss and Bufserv are mutually e/clusiveG that is, on a particular computer, you can run only one of them at any given time. If you have PI Servers that are part of a PI collective, PIBufss supports n5wa! buffering. N! way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI collective. "Bufserv also supports n!way buffering, but $SIsoft recommends that you run PIBufss instead.%

=hich 3uffering +pplication to 0se


'ou should use PIBufss whenever possible because it offers better throughput than Bufserv. In addition, if the interfaces on an Interface Node are sending data to a PI collective, PIBufss guarantees identical data in the archive records of all the PI Servers that are part of that collective. 'ou can use PIBufss only under the following conditions? the PI Server version is at least 0.3.0O9./G and all of the interfaces running on the Interface Node send data to the same PI Server or to the same PI ollective. If any of the following scenarios apply, you must use Bufserv? the PI Server version is earlier than 0.3.0O9./G or the Interface node runs multiple interfaces, and these interfaces send data to multiple PI Servers that are not part of a single PI ollective. If an Interface Node runs multiple interfaces, and these interfaces send data to two or more PI collectives, then neither PIBufss nor Bufserv is appropriate. The reason is that PIBufss and Bufserv can buffer data only to a single collective. If you need to buffer to more than one PI collective, you need to use two or more Interface Nodes to run your interfaces. It is technically possible to run Bufserv on the PI Server Node. )owever, $SIsoft does not recommend this configuration.

O C *&+ Interface

-!

*o9 3uffering =or#s


( complete technical description of PIBufss and Bufserv is beyond the scope of this document. )owever, the following paragraphs provide some insights on how buffering wor*s. #hen an Interface Node has Buffering enabled, the buffering application "PIBufss or Bufserv% connects to the PI Server. It also creates shared memory storage. #hen an interface program ma*es a PI (PI function call that writes data to the PI Server "for e/ample, &isn8sendexce&tion)x()%, the PI (PI chec*s whether buffering is enabled. If it is, these data writing functions do not send the interface data to the PI Server. Instead, they write the data to the shared memory storage that the buffering application created. The buffering application "either Bufserv or PIBufss% in turn reads the data in shared memory, and if a connection to the PI Server e/ists, sends the data to the PI ServerG or if there is no connection to the PI Server, continues to store the data in shared memory "if shared memory storage is available% or writes the data to dis* "if shared memory storage is full%. #hen the buffering application re!establishes connection to the PI Server, it writes to the PI Server the interface data contained in both shared memory storage and dis*. "Before sending data to the PI Server, PIBufss performs further tas*s such data validation and data compression, but the description of these tas*s is beyond the scope of this document.% #hen PIBufss writes interface data to dis*, it writes to multiple files. The names of these buffering files are PI>%FQ8F.,2'. #hen Bufserv writes interface data to dis*, it writes to a single file. The name of its buffering file is 2PI>%F.,2'. (s a previous paragraph indicates, PIBufss and Bufserv create shared memory storage at startup. These memory buffers must be large enough to accommodate the data that an interface collects during a single scan. $therwise, the interface may fail to write all its collected data to the memory buffers, resulting in data loss. The buffering configuration section of this chapter provides guidelines for siDing these memory buffers. #hen buffering is enabled, it affects the entire Interface Node. That is, you do not have a scenario whereby the buffering application buffers data for one interface running on an Interface Node but not for another interface running on the same Interface Node.

3uffering and I Server Security


(fter you enable buffering, it is the buffering applicationZand not the interface programZ that writes data to the PI Server. If the PI Servers trust table contains a trust entry that allows all applications on an Interface Node to write data, then the buffering application is able write data to the PI Server. )owever, if the PI Server contains an interface!specific PI Trust entry that allows a particular interface program to write data, you must have a PI Trust entry specific to buffering. The following are the appropriate entries for the (pplication Name field of a PI Trust entry?

O C *&+ Interface

!.

3uffering +pplication 31 Au--er Su(s8ste/ 31 A31 Au--er Server

+pplication 1ame field for I Trust 31Au-ss.e$e A31A4 (i- t)e 31 A31 is usin9 4 .)ara.ter *ro.ess na/es A31AU# (i- t)e 31 A31 is usin9 " .)ara.ter *ro.ess na/es

To use a process name greater than 3 characters in length for a trust application name, use the 8$N;(PPN(+5FA in the PI lient.ini file.

4nabling 3uffering on an Interface 1ode 9ith the IC0


The I & allows you to select either PIBufss or Bufserv as the buffering application for your Interface Node. Bun the I & and select %ools 2 *uffering.

Choose 3uffer Type

To select PIBufss as the buffering application, choose .nable buffering with PI *uffer Subs!stem. To select Bufserv as the buffering application, choose .nable buffering with API *uffer Server. If a warning message such as the following appears, clic* :es.

O C *&+ Interface

!1

3uffering

3uffering Settings
There are a number of settings that affect the operation of PIBufss and Bufserv. The *uffering Settings section allows you to set these parameters. If you do not enter values for these parameters, PIBufss and Bufserv use default values. I3ufss 4or PIBufss, the paragraphs below describe the settings that may re<uire user intervention. Please contact $SIsoft Technical Support for assistance in further optimiDing these and all remaining settings.

Pri+ary and #econdary Me+ory Buffer #i8e (Byte!) This is a *ey parameter for buffering performance. The sum of these two memory buffer siDes must be large enough to accommodate the data that an interface collects during a single scan. ( typical event with a 4loat01 point type re<uires about 19 bytes. If an interface writes data to 9,::: points, it can potentially send A19,::: bytes "19 R 9:::% of data in one scan. (s a result, the siDe of each memory buffer should be 21,9:: bytes. The default value of these memory buffers is 01,O2P bytes. $SIsoft recommends that these two memory buffer siDes should be increased to the ma/imum of 1:::::: for the best buffering performance. #end rate (+illi!econd!) Send rate is the time in milliseconds that PIBufss waits between sending up to the Maximum transfer ob6ects "described below% to the PI Server. The default value is A::. The valid range is : to 1,:::,:::.

!2

Ma:i+u+ tran!fer o-;ect! Maximum transfer ob6ects is the ma/imum number of events that PIBufss sends between each Send rate pause. The default value is 9::. The valid range is A to 1,:::,:::. Event 7ueue .ile #i8e (M-yte!) This is the siDe of the event <ueue files. PIBufss stores the buffered data to these files. The default value is 01. The range is P to A0A:O1 "P to A1P ;bytes%. Please see the section entitled, =Queue 4ile SiDing> in the pibufss.chm file for details on how to appropriately siDe the event <ueue files. Event 7ueue Pat5 This is the location of the event <ueue file. The default value is "PIHOME#\,2'. 4or optimal performance and reliability, $SIsoft recommends that you place the PIBufss event <ueue files on a different drive,controller from the system drive and the drive with the #indows paging file. "By default, these two drives are the same.% 3ufserv 4or Bufserv, the paragraphs below describe the settings that may re<uire user intervention. Please contact $SIsoft Technical Support for assistance in further optimiDing these and all remaining settings.

Ma:i+u+ -uffer file !i8e ($B) This is the ma/imum siDe of the buffer file " "PIHOME#\,2'\2PI>%F.,2'%. #hen Bufserv cannot communicate with the PI Server, it writes and appends data to this file. #hen the buffer file reaches this ma/imum siDe, Bufserv discards data. The default value is 1,:::,::: .B, which is about 1 ;B. The range is from A to 1,:::,:::.

O C *&+ Interface

!"

3uffering Pri+ary and #econdary Me+ory Buffer #i8e (Byte!) This is a *ey parameter for buffering performance. The sum of these two memory buffer siDes must be large enough to accommodate the data that an interface collects during a single scan. ( typical event with a 4loat01 point type re<uires about 19 bytes. If an interface writes data to 9,::: points, it can potentially send A19,::: bytes "19 R 9:::% of data in one scan. (s a result, the siDe of each memory buffer should be 21,9:: bytes. The default value of these memory buffers is 01,O2P bytes. $SIsoft recommends that these two memory buffer siDes should be increased to the ma/imum of 1:::::: for the best buffering performance. #end rate (+illi!econd!) Send rate is the time in milliseconds that Bufserv waits between sending up to the Maximum transfer ob6ects "described below% to the PI Server. The default value is A::. The valid range is : to 1,:::,:::. Ma:i+u+ tran!fer o-;ect! Max transfer ob6ects is the ma/imum number of events that Bufserv sends between each Send rate pause. The default value is 9::. The valid range is A to 1,:::,:::.

3uffered Servers
The *uffered Servers section allows you to define the PI Servers or PI ollective that the buffering application writes data. I3ufss PIBufss buffers data only to a single PI Server or a PI ollective. Select the PI Server or the PI ollective from the *uffering to collective;server drop down list bo/. The following screen shows that PIBufss is configured to write data to a standalone PI Server named starlig:t. Notice that the $eplicate data to all collective member nodes chec* bo/ is disabled because this PI Server is not part of a collective. "PIBufss automatically detects whether a PI Server is part of a collective.%

!%

The following screen shows that PIBufss is configured to write data to a PI ollective named admiral. By default, PIBufss replicates data to all collective members. That is, it provides n! way buffering. 'ou can override this option by not chec*ing the $eplicate data to all collective member nodes chec* bo/. Then, unchec* "or chec*% the PI Server collective members as desired.

O C *&+ Interface

!$

3uffering

3ufserv Bufserv buffers data to a standalone PI Server, or to multiple standalone PI Servers. "If you want to buffer to multiple PI Servers that are part of a PI ollective, you should use PIBufss.% If the PI Server to which you want Bufserv to buffer data is not in the Server list, enter its name in the Add a server bo/ and clic* the Add Server button. This PI Server name must be identical to the #PI "ostname entry?

The following screen shows that Bufserv is configured to write to a standalone PI Server named etam&0BL. 'ou use this configuration when all the interfaces on the Interface Node write data to etam&0BL.

The following screen shows that Bufserv is configured to write to two standalone PI Servers, one named etam&0BL and the other one named starlig:t. 'ou use this configuration when some of the interfaces on the Interface Node write data to etam&0BL and some write to starlig:t.

!(

Installing 3uffering as a Service


Both the PIBufss and Bufserv applications run as a Service. I 3uffer Subsystem Service &se the PI *uffer Subs!stem Service page to configure PIBufss as a Service. This page also allows you to start and stop the PIBufss service. PIBufss does not re<uire the logon rights of the local administrator account. It is sufficient to use the 8ocalSystem account instead. (lthough the screen below shows asteris*s for the 8ocalSystem password, this account does not have a password.

O C *&+ Interface

!,

3uffering

+ I 3uffer Server Service &se the API *uffer Server Service page to configure Bufserv as a Service. This page also allows you to start and stop the Bufserv Service Bufserv version A.2 and later does not re<uire the logon rights of the local administrator account. It is sufficient to use the 8ocalSystem account instead. (lthough the screen below shows asteris*s for the 8ocalSystem password, this account does not have a password.

!-

O C *&+ Interface

!!

Chapter 1(.

Interface &iagnostics Configuration

The Interface Point onfiguration chapter provides information on building PI points for collecting data from the device. This chapter describes the configuration of points related to interface diagnostics.
1ote8 T)e *ro.edure -or .on-i9urin9 inter-a.e dia9nosti.s is not s*e.i-i. to t)is 1nter-a.e. T)us, -or si/*li.it8, t)e instru.tions and s.reens)ots t)at -ollo, re-er to an inter-a.e na/ed 'odbus4.

Some of the points that follow refer to a =performance summary interval>. This interval is P hours by default. 'ou can change this parameter via the Scan performance summar! bo/ in the UniInt ) ebug parameter category pane?

Scan Class erformance oints


( Scan lass Performance Point measures the amount of time "in seconds% that this Interface ta*es to complete a scan. The Interface writes this scan completion time to millisecond resolution. Scan completion times close to : indicate that the Interface is performing optimally. onversely, long scan completion times indicate an increased ris* of missed or s*ipped scans. To prevent missed or s*ipped scans, you should distribute the data collection points among several scan classes.

O C *&+ Interface

1.1

'ou configure one Scan lass Performance Point for each Scan lass in this Interface. 4rom the I &, select this Interface from the Interface drop!down list and clic* UniInt5Performance Points in the parameter category pane?

Bight clic* the row for a particular Scan #lass ' to bring up the conte/t menu?

'ou need not restart the Interface for it to write values to the Scan lass Performance Points. To see the current values "snapshots% of the Scan lass Performance Points, right clic* and select $efresh Snapshots. Create @ Create A"" To create a Performance Point, right!clic* the line belonging to the tag to be created, and select #reate. lic* #reate (ll to create all the Scan lass Performance Points. Delete To delete a Performance Point, right!clic* the line belonging to the tag to be deleted, and select elete.

O C *&+ Interface

1.2

Correct @ Correct All If the =Status> of a point is mar*ed =Incorrect>, the point configuration can be automatically corrected by I & by right!clic*ing on the line belonging to the tag to be corrected, and selecting #orrect. The Performance Points are created with the following PI attribute values. If I & detects that a Performance Point is not defined with the following, it will be mar*ed Incorrect? To correct all points clic* the #orrect All menu item. The Performance Points are created with the following PI attribute values?
+ttribute Ta9 3oint Sour.e Co/*ressin9 4$./a$ Des.ri*tor &etails Ta9 na/e t)at a**ears in t)e list (o$ 3oint Sour.e -or ta9s -or t)is inter-a.e, as s*e.i-ied on t)e -irst ta( 0-0 Interface name X R S.an Class U 3er-or/an.e 3ointS

,ena+e Bight!clic* the line belonging to the tag and select =$ename> to rename the Performance Point. Column descriptions #tatu! The Status column in the Performance Points table indicates whether the Performance Point e/ists for the scan class in column 1. #reated K Indicates that the Performance Point does e/ist "ot #reated K Indicates that the Performance Point does not e/ist eleted K Indicates that a Performance Point e/isted, but was Cust deleted by the user #can Cla!! = The Scan #lass column indicates which scan class the Performance Point in the %agname column belongs to. There will be one scan class in the Scan #lass column for each scan class listed in the Scan #lasses combo bo/ on the UniInt Parameters tab. %agna+e The %agname column holds the Performance Point tag name. P# This is the point source used for these performance points and the interface. "ocation1 This is the value used by the interface for the /ID=# point attribute.

O C *&+ Interface

1."

Interface &iagnostics Configuration E:de!c This is the used to tell the interface that these are performance points and the value is used to corresponds to the /ID=# command line parameter if multiple copies of the same interface are running on the Interface node. #na&!5ot The Snapshot column holds the snapshot value of each Performance Point that e/ists in PI. The Snapshot column is updated when the Performance Points;#ounters tab is clic*ed, and when the interface is first loaded. 'ou may have to scroll to the right to see the snapshots.

erformance Counters oints


#hen running as a Service or interactively, this Interface e/poses performance data via #indows Performance ounters. Such data include items li*e? the amount of time that the Interface has been runningG the number of points the Interface has added to its point listG the number of tags that are currently updating among others There are two types or instances of Performance ounters that can be collected and stored in PI Points. The first is "HTotal% which is a total for the Performance ounter since the interface instance was started. The other is for individual Scan lasses "Scan lass /% where / is a particular scan class defined for the interface instance that is being monitored. $SIsofts PI Performance +onitor Interface is capable of reading these performance values and writing them to PI points. Please see the Performance Monitor Interface for more information. If there is no PI Performance +onitor Interface registered with the I & in the +odule -atabase for the PI Server the interface is sending its data to, you cannot use the I & to create any Interface instances Performance ounters Points?

1.%

(fter installing the PI Performance +onitor Interface as a service, select this Interface instance from the Interface drop!down list, then clic* Performance #ounters in the parameter categories pane, and right clic* on the row containing the Performance ounters Point you wish to create. This will bring up the conte/t menu?

lic* #reate to create the Performance ounters Point for that particular row. lic* #reate All to create all the Performance ounters Points listed which have a status of Not reated. To see the current values "snapshots% of the created Performance ounters Points, right!clic* on any row and select $efresh Snapshots.
1ote8 T)e 31 3er-or/an.e :onitor 1nter-a.e W and not t)is 1nter-a.e W is res*onsi(le -or u*datin9 t)e values -or t)e 3er-or/an.e Counters 3oints in 31. So, /a7e sure t)at t)e 31 3er-or/an.e :onitor 1nter-a.e is runnin9 .orre.tl8.

erformance Counters
In the following lists of Performance ounters the naming convention used will be? =Performance ounterName> ".Performance ountersPoint Suffi/% The tagname created by the I & for each Performance ounter point is based on the setting found under the Tools $ptions Naming onventions Performance ounter Points. The default for this is =sy.perf.6machine7.6if service7 followed by the Performance ounter Point suffi/.

erformance Counters for both A)TotalB and AScan Class 7B


F oint CountG A.point)countB ( .point<count Performance ounters Point is available for each Scan lass of this Interface as well as a Total for the interface instance.

O C *&+ Interface

1.$

Interface &iagnostics Configuration The .point<count Performance ounters Point indicates the number of PI Points per Scan lass or the total number for the interface instance. This point is similar to the )ealth Point 6&IHS P$INT $&NT7 for scan classes and 6&IHP$INT $&NT7 for totals. The I & uses a naming convention such that the tag containing ="Scan lass A%> "for e/ample, =sy+(er*+etam(,-.+!)/Scan&Class&)0+(oint%co1ntD refers to Scan lass A, ="Scan lass 1%> refers to Scan lass 1, and so on. The tag containing ="HTotal%> refers to the sum of all Scan lasses. FScheduled Scans8 H 'issedG A.sched)scans)HmissedB ( .sched<scans<=missed Performance ounters Point is available for each Scan lass of this Interface as well as a Total for the interface instance. The .sched<scans<=missed Performance ounters Point indicates the percentage of scans the Interface missed per Scan lass or the total number missed for all scan classes since startup. ( missed scan occurs if the Interface performs the scan one second later than scheduled. The I & uses a naming convention such that the tag containing ="Scan lass A%> "for e/ample, =sy+(er*+etam(,-.+!)/Scan&Class&)0+sched%scans%2missedD refers to Scan lass A, ="Scan lass 1%> refers to Scan lass 1, and so on. The tag containing ="HTotal%> refers to the sum of all Scan lasses. FScheduled Scans8 H S#ippedG A.sched)scans)Hs#ippedB ( .sched<scans<=s7ipped Performance ounters Point is available for each Scan lass of this Interface as well as a Total for the interface instance. The .sched<scans<=s7ipped Performance ounters Point indicates the percentage of scans the Interface s*ipped per Scan lass or the total number s*ipped for all scan classes since startup. ( s*ipped scan is a scan that occurs at least one scan period after its scheduled time. This point is similar to the 6&IHS S.IPP5-7 )ealth Point. The I & uses a naming convention such that the tag containing ="Scan lass A%> "for e/ample, =sy+(er*+etam(,-.+!)/Scan&Class&)0+sched%scans%2s3i((edD refers to Scan lass A, ="Scan lass 1%> refers to Scan lass 1, and so on. The tag containing ="HTotal%> refers to the sum of all Scan lasses. FScheduled Scans8 Scan count this intervalG A.sched)scans)this)intervalB ( .sched<scans<this<interval Performance ounters Point is available for each Scan lass of this Interface as well as a Total for the interface instance. The .sched<scans<this<interval Performance ounters Point indicates the number of scans that the Interface performed per performance summary interval for the scan class or the total number of scans performed for all scan classes during the summary interval. This point is similar to the 6&IHS S (N $&NT7 )ealth Point. The I & uses a naming convention such that the tag containing ="Scan lass A%> "for e/ample, =sy+(er*+etam(,-.+!)/Scan&Class&)0+sched%scans%this%intervalD refers to Scan lass A, ="Scan lass 1%> refers to Scan lass 1, and so on. The tag containing ="HTotal%> refers to the sum of all Scan lasses.

1.(

erformance Counters for A)TotalB only


F&evice +ctual ConnectionsG A.&evice)+ctual)ConnectionsB The . evice<Actual<#onnections Performance ounters Point stores the actual number of foreign devices currently connected and wor*ing properly out of the e/pected number of foreign device connections to the interface. This value will always be less than or e<ual to the 5/pected onnections. F&evice 47pected ConnectionsG A.&evice)47pected)ConnectionsB The . evice<.xpected<#onnections Performance ounters Point stores the total number of foreign device connections for the interface. This is the e/pected number of foreign device connections configured that should be wor*ing properly at runtime. If the interface can only communicate with A foreign device then the value of this counter will always be one. If the interface can support multiple foreign device connections then this is the total number of e/pected wor*ing connections configured for this Interface. F&evice StatusG A.&evice)StatusB The . evice<Status Performance ounters Point stores communication information about the interface and the connection to the foreign device"s%. The value of this counter is based on the e/pected connections, actual connections and value of the /Percent/p command line option. If the device status is good then the value is Y:. If the device status is bad then the value is YA. If the interface only supports connecting to A foreign device then the /Percent/p command line value does not change the results of the calculation. If for e/ample the Interface can connect to A: devices and 9 are currently wor*ing then the value of the /Percent/p command line parameter is applied to determine the -evice Status. If the value of the /Percent/p command line parameter is set to 9: and at least 9 devices are wor*ing then the -eviceStatus will remain good "i.e. have a value of Dero%. F/ailover StatusG A./ailover)StatusB The .>ailover<Status Performance ounters Point stores the failover state of the interface when configured for &niInt interface level failover. The value of the counter will be Y: when the interface is running as the YPrimary interface in the failover configuration. If the interface is running in bac*up mode then the value of the counter will be YA. FInterface up<time AsecondsBG A.up)timeB The .up<time Performance ounters Point indicates the amount of time "in seconds% that this Interface has been running. (t startup the value of the counter is Dero. The value will continue to increment until it reaches the ma/imum value for an unsigned integer. $nce it reaches this value then it will start bac* over at Dero. FIO 6ate Aevents2secondBG A.io)ratesB The .io<rates Performance ounters Point indicates the rate "in event per second% at which this Interface writes data to its input tags. "(s of &niInt 3.9.:./ and later this performance counters point will no longer be available.%

O C *&+ Interface

1.,

Interface &iagnostics Configuration FLog file message countG A.log)file)msg)countB The .log<file<msg<count Performance ounters Point indicates the number of messages that the Interface has written to t:e log file. This point is similar to the 6&IH+S; $&NT7 )ealth Point. F I StatusG A I)StatusB The .PI<Status Performance ounters Point stores communication information about the interface and the connection to the PI Server. If the interface is properly communicating with the PI server then the value of the counter is Y:. If the communication to the PI Server goes down for any reason then the value of the counter will be YA. $nce the interface is properly communicating with the PI server again then the value will change bac* to Y:. F oints added to the interfaceG A.pts)added)to)interfaceB The .pts<added<to<interface Performance ounter Point indicates the number of points the Interface has added to its point list. This does not include the number of points configured at startup. This is the number of points added to the interface after the interface has finished a successful startup. F oints edited in the interfaceGA.pts)edited)in)interfaceB The .pts<edited<in<interface Performance ounters Point indicates the number of point edits the Interface has detected. The Interface detects edits for those points whose Point(o!rce attribute matches the Point Source parameter and whose -ocation. attribute matches the Interface ID parameter of the Interface. F oints >oodG A. oints)>oodB The .Points<'ood Performance ounters Point is the number of points that have sent a good current value to PI. ( good value is defined as any value that is not a system digital state value. ( point can either be ;ood, In 5rror or Stale. The total of Points ;ood, Points In 5rror and Points State will e<ual the Point ount. There is one e/ception to this rule. (t startup of an interface, the Stale timeout must elapse before the point will be added to the Stale ounter. Therefore the interface must be up and running for at least A: minutes for all tags to belong to a particular ounter. F oints In 4rrorG A. oints)In)4rrorB The .Points<In<.rror Performance ounters Point indicates the number of points that have sent a current value to PI that is a system digital state value. $nce a point is in the In 5rror count it will remain in the In 5rror count until the point receives a new, good value. Points in 5rror do not transition to the Stale ounter. $nly good points become stale. F oints removed from the interfaceG A.pts)removed)from)interfaceB The .pts<removed<from<interface Performance ounters Point indicates the number of points that have been removed from the Interface configuration. ( point can be removed from the interface when one of the tag properties for the interface is updated and the point is no longer a part of the interface configuration. 4or e/ample, changing the point source, location A, or scan property can cause the tag to no longer be a part of the interface configuration.

1.-

F oints Stale 1.AminBG A. oints)Stale)1.minB The .Points<Stale<+?min Performance ounters Point indicates the number of good points that have not received a new value in the last A: min. If a point is ;ood, then it will remain in the good list until the Stale timeout elapses. (t this time if the point has not received a new value within the Stale Period then the point will move from the ;ood count to the Stale count. $nly points that are ;ood can become Stale. If the point is in the In 5rror count then it will remain in the In 5rror count until the error clears. (s stated above, the total count of Points ;ood, Points In 5rror and Points Stale will match the Point ount for the Interface. F oints Stale ".AminBG A. oints)Stale)".minB The .Points<Stale<@?min Performance ounters Point indicates the number of points that have not received a new value in the last 0: min. 4or a point to be in the Stale 0: minute count it must also be a part of the Stale A: minute count. F oints Stale (.AminBG A. oints)Stale)(.minB The .Points<Stale<@?min Performance ounters Point indicates the number of points that have not received a new value in the last 2: min. 4or a point to be in the Stale 2: minute count it must also be a part of the Stale A: minute and 0: minute count. F oints Stale 2%.AminBG A. oints)Stale)2%.minB The .Points<Stale<4A?min Performance ounters Point indicates the number of points that have not received a new value in the last 13: min. 4or a point to be in the Stale 13: minute count it must also be a part of the Stale A: minute, 0: minute and 2: minute count.

erformance Counters for AScan Class 7B only


F&evice Scan Time AmillisecondsBG A.&evice)Scan)TimeB ( . evice<Scan<%ime Performance ounter Point is available for each Scan lass of this Interface. The . evice<Scan<%ime Performance ounters Point indicates the number of milliseconds the Interface ta*es to read the data from the foreign device and pac*age the data to send to PI. This counter does not include the amount of time to send the data to PI. This point is similar to the 6&IHS IN-5@S (NTI+57 )ealth Point. The I & uses a naming convention such that the tag containing ="Scan lass A%> "for e/ample, =sy+(er*+etam(,-.+!)&/Scan&Class&)0+device%scan&%time> refers to Scan lass A, ="Scan lass 1% refers to Scan lass 1, and so on. FScan Time AmillisecondsBG A.scan)timeB ( .scan<time Performance ounter Point is available for each Scan lass of this Interface. The .scan<time Performance ounter Point indicates the number of milliseconds the Interface ta*es to both read the data from the device and send the data to PI. This point is similar to the 6&IHS INS (NTI+57 )ealth Point.

O C *&+ Interface

1.!

Interface &iagnostics Configuration The I & uses a naming convention such that the tag containing ="Scan lass A%> "for e/ample, =sy+(er*+etam(,-.+!)/Scan&Class&)0+scan%timeD refers to Scan lass A, ="Scan lass 1%> refers to Scan lass 1, and so on.

11.

Interface *ealth 'onitoring oints


Interface )ealth +onitoring Points provide information about the health of this Interface. To use the I & to configure these points, select this Interface from the Interface drop!down list and clic* ,ealth Points from the parameter category pane?

Bight!clic* the row for a particular )ealth Point to display the conte/t menu?

lic* #reate to create the )ealth Point for that particular row. lic* #reate All to create all the )ealth Points. To see the current values "snapshots% of the )ealth Points, right clic* and select $efresh Snapshots.
O C *&+ Interface

111

Interface &iagnostics Configuration 4or some of the )ealth Points described subse<uently, the Interface updates their values at each performance summary interval "typically, P hours%. I0I)*4+6T34+TJ The 6&IH)5(BTB5(T7 )ealth Point indicates whether the Interface is currently running. The value of this point is an integer that increments continuously from A to A9. (fter reaching A9, the value resets to A. The fastest scan class fre<uency determines the fre<uency at which the Interface updates this point?
/astest Scan /re:uency Less t)an 1 se.ond Aet,een 1 and &0 se.onds, in.lusive :ore t)an &0 se.onds 0pdate fre:uency 1 se.ond S.an -reGuen.8 &0 se.onds

If the value of the 6&IH)5(BTB5(T7 )ealth Point is not changing, then this Interface is in an unresponsive state. I0I)&4CST+TJ The Interface is built with a version of &NIINT that is higher than 3.0.:./ and that supports interface health points. The health point with the point attribute 5/desc F 6&IH-5@ST(T7, is used to represent the status of the source devices. The following events can be written to the point? =;ood> The interface is properly communicating and reading data from the devices. If no data collection points have been defined, this indicates the interface has successfully started. =0 I A devices"s% in error = The interface has determined that the listed device"s% are offline. ( device is considered offline when the connection to the )-( Server has failed. Please refer to the UniInt Interface User Manual for more information on how to configure interface health points. I0I)SCI1/OJ The 6&IHS IN4$7 )ealth Point provides scan class information. The value of this point is a string that indicates the number of scan classesG the update fre<uency of the 6&IH)5(BTB5(T7 )ealth PointG and the scan class fre<uencies (n e/ample value for the 6&IHS IN4$7 )ealth Point is?
0 R 1 R 1 R 6L R ./L

The Interface updates the value of this point at startup and at each performance summary interval.
112

I0I)IO6+T4J The 6&IHI$B(T57 )ealth Point indicates the sum of A. the number of scan!based input values the Interface collects before it performs e/ception reportingG and 1. the number of event!based input values the Interface collects before it performs e/ception reportingG and 0. the number of values that the Interface writes to output tags that have a (o!rce'ag. The Interface updates this point at the same fre<uency as the 6&IH)5(BTB5(T7 point. The value of this 6&IHI$B(T57 )ealth Point may be Dero. ( stale timestamp for this point indicates that this Interface has stopped collecting data. I0I)'S>CO01TJ The 6&IH+S; $&NT7 )ealth Point trac*s the number of messages that the Interface has written to the &i&c.log file since start!up. In general, a large number for this point indicates that the Interface is encountering problems. 'ou should investigate the cause of these problems by loo*ing in &i&c.log. The Interface updates the value of this point every 2: seconds. #hile the Interface is running, the value of this point never decreases. I0I) OI1TCO01TJ The 6&IHP$INT $&NT7 )ealth Point counts number of PI tags loaded by the interface. This count includes all input, output and triggered input tags. This count does N$T include any Interface )ealth tags or performance points. The interface updates the value of this point at startup, on change and at shutdown. I0I)O0T 0T6+T4J (fter performing an output to the device, this Interface writes the output value to the output tag if the tag has a (o!rce'ag. The 6&IH$&TP&TB(T57 )ealth Point trac*s the number of these values. If there are no output tags for this Interface, it writes the System -igital State <o *es!lt to this )ealth Point. The Interface updates this point at the same fre<uency as the 6&IH)5(BTB5(T7 points. The Interface resets the value of this point to Dero at each performance summary interval. I0I)O0T 0T3C6+T4J The 6&IH$&TP&TB@B(T57 )ealth Point trac*s the number of System -igital State values that the Interface writes to output tags that have a (o!rce'ag. If there are no output tags for this Interface, it writes the System -igital State <o *es!lt to this )ealth Point. The Interface updates this point at the same fre<uency as the 6&IH)5(BTB5(T7 points. The Interface resets the value of this point to Dero at each performance summary interval.

O C *&+ Interface

11"

Interface &iagnostics Configuration I0I)T6I>>466+T4J The 6&IHTBI;;5BB(T57 )ealth Point trac*s the number of values that the Interface writes to event!based input tags. If there are no event!based input tags for this Interface, it writes the System -igital State <o *es!lt to this )ealth Point. The Interface updates this point at the same fre<uency as the 6&IH)5(BTB5(T7 points. The Interface resets the value of this point to Dero at each performance summary interval. I0I)T6I>>463C6+T4J The 6&IHTBI;;5BB(T57 )ealth Point trac*s the number of System -igital State values that the Interface writes to event!based input tags. If there are no event!based input tags for this Interface, it writes the System -igital State <o *es!lt to this )ealth Point. The Interface updates this point at the same fre<uency as the 6&IH)5(BTB5(T7 points. The Interface resets the value of this point to Dero at each performance summary interval. I0I)SCIO6+T4J 'ou can create a 6&IHS I$B(T57 )ealth Point for each Scan lass in this Interface. The I & uses a tag naming convention such that the suffi/ =.scA> "for e/ample, s;.st.etam&0BL.E..(can Class IO *ate.sc.% refers to Scan lass A, =.sc1> refers to Scan lass 1, and so on. ( particular Scan lasss 6&IHS I$B(T57 point indicates the number of values that the Interface has collected. If the current value of this point is between Dero and the corresponding 6&IHS P$INT $&NT7 point, inclusive, then the Interface e/ecuted the scan successfully. If a 6&IHS I$B(T57 point stops updating, then this condition indicates that an error has occurred and the tags for the scan class are no longer receiving new data. The Interface updates the value of a 6&IHS I$B(T57 point after the completion of the associated scan. (lthough the I & allows you to create the point with the suffi/ =.sc:>, this point is not applicable to this Interface. I0I)SC3C6+T4J 'ou can create a 6&IHS B@B(T57 )ealth Point for each Scan lass in this Interface. The I & uses a tag naming convention such that the suffi/ =.scA> "for e/ample, s;.st.etam&0BL.E..(can Class >ad Nal!e *ate.sc.% refers to Scan lass A, =.sc1> refers to Scan lass 1, and so on. ( particular Scan lasss 6&IHS B@B(T57 point indicates the number System -igital State values that the Interface has collected. The Interface updates the value of a 6&IHS B@B(T57 point after the completion of the associated scan. (lthough the I & allows you to create the point with the suffi/ =.sc:>, this point is not applicable to this Interface. I0I)SCSC+1CO01TJ 'ou can create a 6&IHS S (N $&NT7 )ealth Point for each Scan lass in this Interface. The I & uses a tag naming convention such that the suffi/ =.scA> "for e/ample,

11%

s;.st.etam&0BL.E..(can Class (can Co!nt.sc.% refers to Scan

lass A, =.sc1>

refers to Scan lass 1, and so on. ( particular Scan lasss 6&IH S S (N $&NT7 point trac*s the number of scans that the Interface has performed. The Interface updates the value of this point at the completion of the associated scan. The Interface resets the value to Dero at each performance summary interval. (lthough there is no =Scan lass :>, the I & allows you to create the point with the suffi/ =.sc:>. This point indicates the total number of scans the Interface has performed for all of its Scan lasses. I0I)SCS5I 4&J

'ou can create a 6&IHS S.IPP5-7 )ealth Point for each Scan lass in this Interface. The I & uses a tag naming convention such that the suffi/ =.scA> "for e/ample, s;.st.etam&0BL.E..(can Class (cans (Gi&&ed.sc.% refers to Scan lass A, =.sc1> refers to Scan lass 1, and so on. ( particular Scan lasss 6&IHS S.IPP5-7 point trac*s the number of scans that the Interface was not able to perform before the scan time elapsed and before the Interface performed the ne/t scheduled scan. The Interface updates the value of this point each time it s*ips a scan. The value represents the total number of s*ipped scans since the previous performance summary interval. The Interface resets the value of this point to Dero at each performance summary interval. (lthough there is no =Scan lass :>, the I & allows you to create the point with the suffi/ =.sc:>. This point monitors the total s*ipped scans for all of the Interfaces Scan lasses. I0I)SC OI1TCO01TJ 'ou can create a 6&IHS P$INT $&NT7 )ealth Point for each Scan lass in this Interface. The I & uses a tag naming convention such that the suffi/ =.scA> "for e/ample, s;.st.etam&0BL.E..(can Class Point Co!nt.sc.% refers to Scan lass A, =.sc1> refers to Scan lass 1, and so on. This )ealth Point monitors the number of tags in a Scan lass. The Interface updates a 6&IHS P$INT $&NT7 )ealth Point when it performs the associated scan. (lthough the I & allows you to create the point with the suffi/ =.sc:>, this point is not applicable to this Interface. I0I)SCI1SC+1TI'4J 'ou can create a 6&IHS INS (NTI+57 )ealth Point for each Scan lass in this Interface. The I & uses a tag naming convention such that the suffi/ =.scA> "for e/ample, s;.st.etam&0BL.E..(can Class (can 'ime.sc.% refers to Scan lass A, =.sc1> refers to Scan lass 1, and so on. ( particular Scan lasss 6&IH S INS (NTI+57 point represents the amount of time "in milliseconds% the Interface ta*es to read data from the device, fill in the values for the tags, and send the values to the PI Server. The Interface updates the value of this point at the completion of the associated scan.

O C *&+ Interface

11$

Interface &iagnostics Configuration I0I)SCI1&4CSC+1TI'4J 'ou can create a 6&IHS IN-5@S (NTI+57 )ealth Point for each Scan lass in this Interface. The I & uses a tag naming convention such that the suffi/ =.scA> "for e/ample, s;.st.etam&0BL.E..(can Class ,e+ice (can 'ime.sc.% refers to Scan lass A, =.sc1> refers to Scan lass 1, and so on. ( particular Scan lasss 6&IH S IN-5@S (NTI+57 point represents the amount of time "in milliseconds% the Interface ta*es to read data from the device and fill in the values for the tags. The value of a 6&IH S IN-5@S (NTI+57 point is a fraction of the corresponding 6&IHS INS (NTI+57 point value. 'ou can use these numbers to determine the percentage of time the Interface spends communicating with the device compared with the percentage of time communicating with the PI Server. If the 6&IHS S.IPP5-7 value is increasing, the 6&IHS IN-5@S (NTI+57 points along with the 6&IHS INS (NTI+57 points can help identify where the delay is occurring? whether the reason is communication with the device, communication with the PI Server, or elsewhere. The Interface updates the value of this point at the completion of the associated scan.

I2O 6ate oint


(n I,$ Bate point measures the rate at which the Interface writes data to its input tags. The value of an I,$ Bate point represents a A:!minute average of the total number of values per minute that the Interface sends to the PI Server. #hen the Interface starts, it writes : to the I,$ Bate point. (fter running for ten minutes, the Interface writes the I,$ Bate value. The Interface continues to write a value every A: minutes. #hen the Interface stops, it writes :. The I & allows you to create one I,$ Bate point for each copy of this Interface. Select this Interface from the Interface drop!down list, clic* I& $ate in the parameter category pane, and chec* .nable I&$ates for this Interface.

11(

(s the preceding picture shows, the I & suggests an .vent #ounter number and a %agname for the I,$ Bate Point. lic* the Save button to save the settings and create the I,$ Bate point. lic* the Appl! button to apply the changes to this copy of the Interface. 'ou need to restart the Interface in order for it to write a value to the newly created I,$ Bate point. Bestart the Interface by clic*ing the $estart button?

"The reason you need to restart the Interface is that the Point(o!rce attribute of an I,$ Bate point is -a .% To confirm that the Interface recogniDes the I,$ Bate Point, loo* in the &i&c.log for a message such as?
PI7Mod>!s .= IO*2'E: tag s;.io.etam&0BL.Mod !sE. config!red.

To see the I,$ Bate points current value "snapshot%, clic* the $efresh snapshot button?

4nable IO6ates for this Interface The .nable I&$ates for this interface chec* bo/ enables or disables I,$ Bates for the current interface. To disable I,$ Bates for the selected interface, unchec* this bo/. To enable I,$ Bates for the selected interface, chec* this bo/. Event Counter The .vent #ounter correlates a tag specified in the iorates.dat file with this copy of the interface. The command!line e<uivalent is /ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file. %agna+e The tag name listed under the %agname column is the name of the I,$ Bate tag. %ag #tatu! The %ag Status column indicates whether the I,$ Bate tag e/ists in PI. The possible states are? reated K This status indicates that the tag e/ist in PI Not reated K This status indicates that the tag does not yet e/ist in PI -eleted K This status indicates that the tag has Cust been deleted &n*nown K This status indicates that the PI I & is not able to access the PI Server
11,

O C *&+ Interface

Interface &iagnostics Configuration In .ile The In >ile column indicates whether the I,$ Bate tag listed in the tag name and the event counter is in the I$Bates.dat file. The possible states are? 'es K This status indicates that the tag name and event counter are in the I$Bates.dat file No K This status indicates that the tag name and event counter are not in the I$Bates.dat file #na&!5ot The Snapshot column holds the snapshot value of the I,$ Bate tag, if the I,$ Bate tag e/ists in PI. The Snapshot column is updated when the I&$ates;Status %ags tab is clic*ed, and when the Interface is first loaded. 6ight 'ouse 3utton 'enu Options Create reate the suggested I,$ Bate tag with the tag name indicated in the %agname column. Delete -elete the I,$ Bate tag listed in the %agname column. ,ena+e (llow the user to specify a new name for the I,$ Bate tag listed in the %agname column. Add to .ile (dd the tag to the I$Bates.dat file with the event counter listed in the .vent #ounter olumn. #earc5 (llow the user to search the PI Server for a previously defined I,$ Bate tag.

Interface Status oint


The PI Interface Status &tility "IS&% alerts you when an interface is not currently writing data to the PI Server. This situation commonly occurs if the monitored interface is running on an Interface Node, but the Interface Node cannot communicate with the PI ServerG or the monitored interface is not running, but it failed to write at shutdown a System state such as Intf (:!t. The IS& wor*s by periodically loo*ing at the timestamp of a #atchdog Tag. The #atchdog Tag is a tag whose value a monitored interface "such as this Interface% fre<uently updates. The #atchdog Tag has its excde+, excmin, and excmax point attributes set to :. So, a non! changing timestamp for the #atchdog Tag indicates that the monitored interface is not writing data. Please see the Interface Status Interface for complete information on using the IS&. PI Interface Status runs only on a PI Server Node.

11-

If you have used the I & to configure the PI Interface Status &tility on the PI Server Node, the I & allows you to create the appropriate IS& point. Select this Interface from the Interface drop!down list and clic* Interface Status in the parameter category pane. Bight clic* on the IS& tag definition window to bring up the conte/t menu?

lic* #reate to create the IS& tag. &se the %ag Search button to select a #atchdog Tag. "Becall that the #atchdog Tag is one of the points for which this Interface collects data.% Select a Scan freBuenc! from the drop!down list bo/. This Scan fre<uency is the interval at which the IS& monitors the #atchdog Tag. 4or optimal performance, choose a Scan freBuenc! that is less fre<uent than the maCority of the scan rates for this Interfaces points. 4or e/ample, if this Interface scans most of its points every 0: seconds, choose a Scan freBuenc! of 2: seconds. If this Interface scans most of its points every second, choose a Scan freBuenc! of A: seconds. If the %ag Status indicates that the IS& tag is Incorrect, right clic* to enable the conte/t menu and select #orrect.
1ote8 T)e 31 1nter-a.e Status Utilit8 W and not t)is 1nter-a.e W is res*onsi(le -or u*datin9 t)e 1SU ta9. So, /a7e sure t)at t)e 31 1nter-a.e Status Utilit8 is runnin9 .orre.tl8.

O C *&+ Interface

11!

4rror and Informational 'essages


( string <ameI, is pre!pended to error messages written to the message log. <ame is a non! configurable identifier that is no longer than E characters. I, is a configurable identifier that is no longer than E characters and is specified using the /id parameter on the startup command!line.

'essage Logs
The location of the message log depends upon the platform on which the Interface is running. See the UniInt Interface User Manual for more information. +essages are written to P4HO"!5dat5(i(c+log at the following times. #hen the Interface starts many informational messages are written to the log. These include the version of the interface, the version of &niInt, the command!line parameters used, and the number of points. (s the Interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points. If the /d2/niInt is used on the command!line, then various informational messages are written to the log file.

'essages
This section contains a partial list of the error messages you might find in the message log along with an e/planation of the message. 5rrors will generally either have a he/ number after these phrases "li*e :/P:::O::9% or they will have another message after the phrase, if the $P )-( Server provided an e/planation for the error. $ther error messages are produced by the standard $SI interface routines, or by the (PI, and those error messages are not documented here. If any error message has a point number as well as a tag name, always use the point number to identify the problem tag, because often the tagname field that is used is one that only has A1 characters, so the tagname printed in the logfile will not be complete. These error messages may not e/actly match the error messages in the version running locally. This list shows the general part of the message. 'ou can search this document to find words that appear in the error message. Out of +e+ory Una-le to add tag There are several formats for messages that mean the system has run out of resources. &se the Tas* +anager to chec* the resources being used? press the ontrol, Shift, and 5scape

O C *&+ Interface

121

*eys all together to get to the Tas* +anager, then select the Processes tab. 4rom the menu, select @iewSSelect olumns, then chec* the bo/es for +emory &sage and @irtual +emory SiDe to see whos eating up all the memory. If its PI$P )-(Int.e/e, there may be a bottlenec* between the interface and the PI system K additional messages should appear in the PIP .8$; file "see below for =Bunning low on memory, dropping data>%. Error fro+ CoInitiali8e Error fro+ CoInitiali8e#ecurity $+ may not be properly installed on the system. This is a maCor problem. C"#ID.ro+ProgID The Servers Begistry entries are not valid. CoCreateIn!tanceE: This is almost always a problem with - $+ N4;. See the section on onfiguring - $+. IOPC HDA#erver This error indicates that the pro/y stub is not registered. The $P pro/y.dll and $P comnHps.dll files are included in this distribution. To register them, open a ommand Prompt window, change to the directory where the interface was installed, and type the following commands. The system should pop up a window after each line that says the -88 was registered. \regsvr01 $P pro/y.dll \regsvr01 $P comnHps.dll Add,ef This means the $P )-( Server would not let the interface do the simplest function. If the PIH)-(Tool is able to read and write tags, but this error occurs, there is almost certainly a permissions problem. Bechec* the - $+ settings, chec* what user the interface is running as, try running the interface interactively "see above on how to do this% No ConnectionPoint for OPC HDA#5utdo/n #5utdo/n Advi!e .ailed There are not fatal errors, it Cust means that the $P )-( Server does not implement the Shutdown interface, or doesnt implement it properlyG if the server goes down, the interface will only *now about it because it stops answering our calls. This will not prevent proper operation of our interface. hec* the server installation instructions.

O C *&+ Interface

122

AddIte+! failed for tag A! AddIte+ failed for A! Write failed Write error AB for tag ,ead2 (!o+e !tring fro+ !erver 5ere6 5o&efully) ,e+oveIte+ failed for tag A! dev?re+ove?tag2 Una-le to Dunadvi!e A! AddIte+! failed6 !erver not in ,UNNIN< !tate6 /ill try later This is informational. Some servers ta*e a while to fully start. The interface will wait around, and when the server enters B&NNIN; mode, the interface will continue. &se the PIH)-(Tool to see the state of the server "use the ;et Status button%. If the server doesnt enter the B&NNIN; mode, investigate the cause. QueryInterface?II-HIconnectionPoint ontainer failed Write una-le to get value!2 <et!na&!5ot: error Ad This means the interface tried to read a value from PI to write to the $P )-( Server, and was unable to read the value. +a*e sure PI is running K try using apisnap "in the (PI directory%. hec* the tag configuration to ma*e sure the interface isnt configured to write a string value into a numeric output. No Ite+ na+e 9 In!tru+ent%ag and E:De!c -ot5 e+&ty Una-le to get &oint ty&e Event Point 5a! invalid !can cla!! (CD E) Point 5a! invalid !can cla!! (D D E) Point 5a! invalid !can cla!! <et#tatu! This means the $P )-( Server didnt respond to a status <uery. It may be down or disconnected. CanFt get PI #erver ti+e This is actually a maCor error, as the interface is actually as*ing the (PI for the timestamp. If this message occurs, call for help, unless the system was Cust installed. If the system was Cust installed, try rebooting, then ensure the machine can connect to PI. Try pinging the PI machine "\ping machinename%G ma*e sure PI is runningG try using (PIsnap to connect to PI "loo* in the (PI directory for apisnap.e/e%.

O C *&+ Interface

12"

4rror and Informational 'essages <et#tatu!2 #erver 5a! no current ti+e' This is a really bro*en server that refuses to even provide the time of day "literally%. The server is supposed to include current time when it sends its status. This one sent trash. The interface will assume its a very stupid server, and try to guess at what correct timestamps would be, but the user should not assume that the timestamps are highly accurate. Cleaning u& connection! Cleaned u& connection! The interface will print these messages when its been told to e/it. The first indicates that the interface is beginning the process of disconnecting from the $P )-( Server. The second indicates that the interface disconnected and will be dying shortly. Interface failed to /rite !o+e A! !tate! #hen the $P )-( Server shuts down, the interface will send a shutdown status to each tag, if the interface was configured to do that "using the ,ST$PST(T parameter on the command line%. If the interface tried, but could not send some or all of them "because it cannot tal* to the PI Server, and bufserv is not being used%, this message will appear. #erver !ent !5utdo/n notice This is printed when the interface receives a shutdown notification from the $P )-( Server. It may be followed by a message from the server indicating why it was going down. The interface will wait forever, trying to reconnect to the server periodically, until it is told to shutdown or until it is able to reconnect. OnDataC5ange2 *ariantCo&y This is a serious problem, it indicates that the $P )-( Server sent what loo*ed li*e data, but its Cun*. It may be a transmission error, or a server bug. #hatever it was, the interface dumped the bad data, since it is unusable, and written B(-ST(T to the tag "the timestamp was good, after all%. OnDataC5ange2 Bad %i+e!ta+& The interface received an invalid timestamp from the $P )-( Server. The interface grabbed a timestamp when the data came in, and will use that, but chec* the server. PIH)-(Tool will display the timestamps. Invalid ti+e!ta+& for tag2 A!6 Ad and A'46f The interface received an invalid timestamp from the $P )-( Server. Try using PIH)-(Tool to loo* at the same ItemI-. &sing Befresh or (dvise or (syncBead will display a timestamp. This usually indicates a bug in the $P )-( Server. Put!na& !y!te+ error Ad6 Ad Put!na& no longer in !y!te+ error Ad6 Ad The interface has,had a problem sending data to PI. These are system errors.

12%

Put!na& error !tate c5anged6 /a! Ad6 no/ Ad Put!na& no longer in error Ad6tag2 A! The interface has,had a problem sending data for this tag. Put!na&!: not i+&le+ented Ad <et!na&!5ot: not i+&le+ented Install a more recent version of the (PI. This one doesnt handle e/tended (PI calls, and the interface re<uires those. Una-le to tran!late !tring The interface must spea* &nicode to the $P )-( Server, because its re<uired for $+. The interface tried to translate some string value from a PI tag from its (S II to &nicode, and failed. The particular value in that particular tag would be most interesting to loo* at, since if its valid (S II printable data, it should be translatable. Una-le to initiali8e !erver o-;ect The interface cant run. It would be a surprise if anything is running on the machine. $r maybe the interface is configured to run under an account with no privileges at all. No OPC HDA #erver !&ecified ,S5B@5BFservername is not found in the $P )-(Int.bat file. $r the interface ran interactively rather than as a service, but the $P )-(Int.bat file was not edited to put everything on one line first. CanFt connect to OPC HDA #erver6 going into !lo/ cycle /ait The tried to connect to the server, but couldnt. It will *eep trying. There should be another message before this one that gives more information about e/actly what call failed. 8oo* at that message, and fi/ whatever it says is wrong. $therwise, the interface will sit here forever. Infor+ational +e!!age! $n startup, the interface will print the scan classes with the count of tags in each class, and the update rate for the class. (fter the interface is started, if points are edited in PI, the interface will log the changes in the log file.

System 4rrors and I 4rrors


System errors are associated with positive error numbers. 5rrors related to PI are associated with negative error numbers. 4rror &escriptions -escriptions of system and PI errors can be obtained with the &idiag utility? #indows? &NI[?
\PI\adm\&idiag 9 e error8n!m er ?PI?adm?&idiag 9e error8n!m er

O C *&+ Interface

12$

4rror and Informational 'essages

0niInt /ailover Specific 4rror 'essages


Informational
'essage

.67Ma;7L6 .L:08:LL OPCH,2Int .= %niInt failo+er: Interface in t:e C>acG!&D state.


U*on s8ste/ startu*, t)e initial transition is /ade to t)is state. ')ile in t)is state t)e inter-a.e /onitors t)e status o- t)e ot)er inter-a.e *arti.i*atin9 in -ailover. ')en .on-i9ured -or 6ot -ailover, data re.eived -ro/ t)e data sour.e is Gueued and not sent to t)e 31 Server ,)ile in t)is state. T)e a/ount o- data Gueued ,)ile in t)is state is deter/ined (8 t)e -ailover u*date interval. 1n an8 .ase, t)ere ,ill (e t8*i.all8 no /ore t)an t,o u*date intervals o- data in t)e Gueue at an8 9iven ti/e. So/e transition .)ains /a8 .ause t)e Gueue to )old u* to -ive -ailover u*date intervals ,ort) o- data.

'eaning

'essage

.67Ma;7L6 .L:08:L1 OPCH,2Int .= %niInt failo+er: Interface in t:e CPrimar;D state and acti+el; sending data to PI. >acG!& interface not a+aila le.
')ile in t)is state, t)e inter-a.e is in its *ri/ar8 role and sends data to t)e 31 Server as it is re.eived. T)is /essa9e also states t)at t)ere is not a (a.7u* inter-a.e *arti.i*atin9 in -ailover.

'eaning

'essage

.67Ma;7L6 .6:0S:/. OPCH,2Int .= %niInt failo+er: Interface in t:e CPrimar;D state and acti+el; sending data to PI. >acG!& interface a+aila le.
')ile in t)is state, t)e inter-a.e sends data to t)e 31 Server as it is re.eived. T)is /essa9e also states t)at t)e ot)er .o*8 o- t)e inter-a.e a**ears to (e read8 to ta7e over t)e role o- *ri/ar8.

'eaning

12(

4rrors A hase 1 K 2B
'essage

.67Ma;7L6 .S:/B:L6 OPCH,2Int .= One of t:e re)!ired Failo+er (;nc:roniTation &oints 4as not loaded. Error 5 L: ':e 2cti+e I, s;nc:roniTation &oint 4as not loaded. ':e in&!t PI tag 4as not loaded
T)e A.tive 1D ta9 is not .on-i9ured *ro*erl8. C)e.7 validit8 o- *oint attri(utes. #or e$a/*le, /a7e sure Lo.ation1 attri(ute is valid -or t)e inter-a.e. All -ailover ta9s /ust )ave t)e sa/e Point(o!rce and -ocation. attri(utes. :odi-8 *oint attri(utes as ne.essar8 and restart t)e inter-a.e.

Cause 6esolution

'essage

.67Ma;7L6 .S:08:L6 OPCH,2Int .= One of t:e re)!ired Failo+er (;nc:roniTation &oints 4as not loaded. Error 5 L: ':e Heart eat &oint for t:is co&; of t:e interface 4as not loaded. ':e in&!t PI tag 4as not loaded
T)e 6eart(eat ta9 is not .on-i9ured *ro*erl8. C)e.7 validit8 o- *oint attri(utes. #or e$a/*le, /a7e sure Lo.ation1 attri(ute is valid -or t)e inter-a.e. All -ailover ta9s /ust )ave t)e sa/e 3ointSour.e and Lo.ation1 attri(utes. :odi-8 *oint attri(utes as ne.essar8 and restart t)e inter-a.e.

Cause 6esolution

'essage

.S7Ma;7L6 LB:L6:L0 OPCH,2Int = ':e %niint FailO+er I, (//F'DID) m!st &ositi+e integer.
T)e U#0H1D *ara/eter )as not (een assi9ned a *ositive inte9er value.

e a

Cause 6esolution 'essage

C)an9e and veri-8 t)e *ara/eter to a *ositive inte9er and restart t)e inter-a.e.

.S7Ma;7L6 LB:L6:L0 OPCH,2Int .= ':e Failo+er I, &arameter (//F'DID) 4as fo!nd !t t:e I, for t:e red!ndant co&; 4as not fo!nd
T)e //F'D'therID *ara/eter is not de-ined or )as not (een assi9ned a *ositive inte9er value. C)an9e and veri-8 t)e //F'D'therID *ara/eter to a *ositive inte9er and restart t)e inter-a.e.

Cause 6esolution

O C *&+ Interface

12,

4rror and Informational 'essages

4rrors A hase 2B

0nable to open synchroni;ation file


'essage

/S7U!n7L8 .S:/S:.S PI Eig:t 'racG . .= Error 1: %na le to create file H\\georgiaGing\@eorgiaMing(torage\%nIntFailo+er\\PIEig:t' racG8eig:t8..datI Nerif; t:at interface :as read?4rite?create access on file ser+er mac:ine. IntialiTing !niint li rar; failed (to&&ing Interface
T)is /essa9e ,ill (e seen ,)en t)e inter-a.e is una(le to .reate a ne, -ailover s8n.)roniBation -ile at startu*. T)e .reation o- t)e -ile onl8 ta7es *la.e t)e -irst ti/e eit)er .o*8 o- t)e inter-a.e is started and t)e -ile does not e$ist. T)e error nu/(er /ost .o//onl8 seen is error nu/(er 5. 4rror nu/(er 5 is an Ra..ess deniedS error and is li7el8 t)e result o- a *er/issions *ro(le/. 4nsure t)e a..ount t)e inter-a.e is runnin9 under )as read and ,rite *er/issions -or t)e -older. T)e Rlo9 on asS *ro*ert8 o- t)e 'indo,s servi.e /a8 need to (e set to an a..ount t)at )as *er/issions -or t)e -older.

Cause

6esolution

4rror Opening Synchroni;ation /ile


'essage

(!n U!n /B .S:.8:1. /LL8 PI Eig:t 'racG . /= J2*<I<@= Failo+er Jarning: Error 5 6$ %na le to o&en Failo+er Control File H\\georgiaGing\@eorgiaMing(torage\Eig:t\PIEig:t'racG8eig: t8..datI ':e interface 4ill not e a le to c:ange state if PI is not a+aila le
T)is /essa9e ,ill (e seen ,)en t)e inter-a.e is una(le to o*en t)e -ailover s8n.)roniBation -ile. T)e inter-a.e -ailover ,ill .ontinue to o*erate .orre.tl8 as lon9 as .o//uni.ation to t)e 31 Server is not interru*ted. 1- .o//uni.ation to 31 is interru*ted ,)ile one or (ot) inter-a.es .annot a..ess t)e s8n.)roniBation -ile, t)e inter-a.es ,ill re/ain in t)e state t)e8 ,ere in at t)e ti/e o- t)e se.ond -ailure, so t)e *ri/ar8 inter-a.e ,ill re/ain *ri/ar8 and t)e (a.7u* inter-a.e ,ill re/ain (a.7u*. 4nsure t)e a..ount t)e inter-a.e is runnin9 under )as read and ,rite *er/issions -or t)e -older and -ile. T)e Rlo9 on asS *ro*ert8 o- t)e 'indo,s servi.e /a8 need to (e set to an a..ount t)at )as *er/issions -or t)e -older and -ile.

Cause

6esolution

12-

I S&5 Options
To access the PI S-. settings for this Interface, select this Interface from the Interface drop! down list and clic* UniInt ) PI S ( in the parameter category pane.

&isable I S&5 Select isable PI S ( to tell the Interface not to use the PI S-.. If you want to run the Interface in -isconnected Startup mode, you must choose this option. The command line e<uivalent for this option is /pisd3=-. 0se the InterfaceLs default setting This selection has no effect on whether the Interface uses the PI S-.. )owever, you must not choose this option if you want to run the Interface in -isconnected Startup mode. 4nable I S&5 Select .nable PI S ( to tell the Interface to use the PI S-.. hoose this option if the PI Server version is earlier than 0.3.0O:./ or the PI (PI is earlier than A.2.:.1, and you want to use e/tended lengths for the 'ag, ,escri&tor, Ex,esc, Instr!ment'ag, or Point(o!rce point attributes. The ma/imum lengths for these attributes are?
+ttribute 4nable the Interface to use the I S&5 102% 102% 102% 102% 102% I Server earlier than ".%.",..7 or I + I earlier than 1.(...2, 9ithout the use of the I S&5 255 2& "0 %2 1

Ta9 Des.ri*tor 4$Des. 1nstru/entTa9 3ointSour.e

)owever, if you want to run the Interface in -isconnected Startup mode, you must not choose this option. The command line e<uivalent for this option is /pisd3=1.

O C *&+ Interface

12!

O C *&+ Interface

1".

O C *&+ Server Issues


The $P )-( specification offers a great deal of fle/ibility in how $P )-( Servers are designed, and in what features they will support. This section describes how the server design and features might affect use of this interface.

3ro9sing
Point browsing is a re<uirement of the $P )-( specification. If the $P )-( Server does not support browsing, the user must have access to a list of the points which it will accept, or the format of point names it will allow. If browsing is allowed, use PIH)-(Tool to see the points which the $P )-( Server recogniDes.

&isconnecting
If the interface disconnects improperly from an $P )-( Server "such as if the networ* connection goes down, or the #indows system crashes%, the server may not clean up the connection on its side. This might result in the interface unable to reconnect with the server. &se the PIH)-(Tool to verify that this is occurring. To resolve, chec* the documentation that came with the server to see if they address this issue. If not, try shutting down the $P )-( Server. (lternatively, if you understand #indows and the programs running on the machine <uite well, use Tas* +anager to *ill the thread, if in doubt, reboot the machine. 'ou cannot resolve this problem with the interface? $nce the connection is bro*en, the interface cannot tell the server to clean up the connection.

O C *&+ Interface

1"1

&ebugging
&se the debugging parameter if you want to understand problematic or une/plained behavior, such as duplicate values or invalid timestamps. 8imit use of the debugging parameter to short periods of time, as the parameter can create large files "files larger than 1:: +b would not be unusual%. The parameter itself is actually a bitmas*, which means more than one option can be set at the same time. 4or e/ample, a value of /DB=: is the same as /DB=1 and /DB==. @DBD1 This is for internal testing only and is not useful to users. @DBD3 8ogging of startup, including InstrumentTag and 5/-esc for each tag. @DBD This setting causes a number of messages to be written to the pipc.log file when write operations are performed. This parameter causes the $P )-( Interface to log every time it sends a write. @DBDG This parameter causes the $P )-( Interface to log every time a scan starts and a scan ends. This setting causes a number of messages to be written to the pipc.log file. @DBD43 This setting logs the timestamp with the data, the adCusted timestamp, the PITime, and the scanclass for each data value that the interface receives. This is a RlotR of data. It all goes into the PIP .log file. -o not leave this setting on for more than a few minutes. See the section below for more information. @DBD6 This setting logs the same items as ,-BF01, but it logs them for only the tag specified as the debug tag ",-TFtagname%. If there is no tag specified, the first input tag that is found at startup is declared the debug tag. @DBD13G This setting logs messages when the interface is trying to connect to the $P )-( Server. The start and end of each scan will also be logged with the amount of time it too* to finish the scan and the number of values sent to PI

O C *&+ Interface

1""

@DBD3H6 This setting logs when a numeric value is being read for a -igital tag and the number is above the possible number of digital states. The $ver Bange system digital state is sent to PI in this case.

O C *&+ Interface

1"%

Technical Support and 6esources


'ou can read complete information about technical support options, and access all of the following resources at the $SIsoft Technical Support #eb site? httpC;;techsupport.osisoft.com "http?,,techsupport.osisoft.com%

3efore Mou Call or =rite for *elp


#hen you contact $SIsoft Technical Support, please provide? Product name, version, and,or build numbers omputer platform " P& type, operating system, and version number% The time that the difficulty started The log file"s% at that time

*elp &es# and Telephone Support


'ou can contact $SIsoft Technical Support 13 hours a day. &se the numbers in the table below to find the most appropriate number for your area. -ialing any of these numbers will route your call into our global support <ueue to be answered by engineers stationed around the world.
Office Location San Leandro, CA, USA 3)iladel*)ia, 3A, USA >o)nson Cit8, TD, USA :ontreal, EC, Canada Sao 3aulo, AraBil #ran7-urt, 5er/an8 :ana/a, Aa)rain Sin9a*ore 3ert), 'A, Australia +ccess 1umber 1 510 297 5"2" 1 215 &0& 0705 1 42% &10 %"00 1 514 49% 0&&% 55 11 %05% 5040 49 &047 9"9 %%% 97% 175" 4429 &5 &%91 1"11 "& 021 2%27 "&"& &1 " 92"2 9220 Local Language Options 4n9lis) 4n9lis) 4n9lis) 4n9lis), #ren.) 4n9lis), 3ortu9uese 4n9lis), 5er/an 4n9lis), Ara(i. 4n9lis), :andarin :andarin 4n9lis)

O C *&+ Interface

1"$

Support may be provided in languages other than 5nglish in certain centers "listed above% based on availability of attendants. If you select a local language option, we will ma*e best efforts to connect you with an available Technical Support 5ngineer "TS5% with that language s*ill. If no local language TS5 is available to assist you, you will be routed to the first available attendant. If all available TS5s are busy assisting other customers when you call, you will be prompted to remain on the line to wait for the ne/t available TS5 or else leave a voicemail message. If you choose to leave a message, you will not lose your place in the <ueue. 'our voicemail will be treated as a regular phone call and will be directed to the first TS5 who becomes available. If you are calling about an ongoing case, be sure to reference your case number when you call so we can connect you to the engineer currently assigned to your case. If that engineer is not available, another engineer will attempt to assist you.

Search Support
4rom the $SIsoft Technical Support #eb site, clic* Search Support. Quic*ly and easily search the $SIsoft Technical Support #eb sites Support Solutions, -ocumentation, and Support Bulletins using the advanced +S SharePoint search engine.

4mail<based Technical Support


techsupport]osisoft.com #hen contacting $SIsoft Technical Support by email, it is helpful to send the following information? -escription of issue? Short description of issue, symptoms, informational or error messages, history of issue 8og files? See the product documentation for information on obtaining logs pertinent to the situation.

Online Technical Support


4rom the $SIsoft Technical Support #eb site, clic* #ontact us 2 M! Support 2 M! #alls. &sing $SIsofts $nline Technical Support, you can? 5nter a new call directly into $SIsofts database "monitored 13 hours a day% @iew or edit e/isting $SIsoft calls that you entered @iew any of the calls entered by your organiDation or site, if enabled See your licensed software and dates of your Service Beliance Program agreements

O C *&+ Interface

1"(

6emote +ccess
4rom the $SIsoft Technical Support #eb site, clic* #ontact Us 2 $emote Support &ptions. $SIsoft Support 5ngineers may remotely access your server in order to provide hands!on troubleshooting and assistance. See the Bemote (ccess page for details on the various methods you can use.

On<site Service
4rom the $SIsoft Technical Support #eb site, clic* #ontact Us 2 &n5site >ield Service 8isit. $SIsoft provides on!site service for a fee. @isit our $n!site 4ield Service @isit page for more information.

5no9ledge Center
4rom the $SIsoft Technical Support #eb site, clic* (nowledge #enter. The .nowledge enter provides a searchable library of documentation and technical data, as well as a special collection of resources for system managers. 4or these options, clic* .nowledge enter on the Technical Support #eb site. The Search feature allows you to search Support Solutions, Bulletins, Support Pages, .nown Issues, 5nhancements, and -ocumentation "including user manuals, release notes, and white papers%. System +anager Besources include tools and instructions that help you manage? (rchive siDing, bac*up scripts, daily health chec*s, daylight savings time configuration, PI Server security, PI System siDing and configuration, PI trusts for Interface Nodes, and more.

0pgrades
4rom the $SIsoft Technical Support #eb site, clic* #ontact Us 2 &btaining Upgrades. 'ou are eligible to download or order any available version of a product for which you have an active Service Beliance Program "SBP%, formerly *nown as Tech Support (greement "TS(%. To verify or change your SBP status, contact your Sales Bepresentative or %echnical Support "http?,,techsupport.osisoft.com,% for assistance.

O C *&+ Interface

1",

6evision *istory
&ate 14!:a8!2004 2"!De.!2004 0%!>an!2005 2"!>an!2005 25!:a8!2005 01!>un!2005 +uthor :5ra.e C)r8s C)r8s :5ra.e :5ra.e :?ell8 Comments #irst Dra-t @ersion 0.0.0.9 <ev A @ersion 0.0.0.9 <ev C: re,rite 1CU se.tion u*dated C)an9e na/e -ro/ *i o*.)da .lient to *i o*.)da inter-a.e. 3ut in .o//ents -ro/ L Dale8. #i$ed T0C, )eaders and -ooters, re*la.ed se.tion on .on-i9urin9 t)e inter-a.e ,it) 1CU .ontrol to re-le.t ne, na/e. #i$ed -ilena/e in DC0: se.tion. #i$ed lo.ation o- 31H6DATool installation. #i$ed re-eren.e to A**endi$ 4 ,)i.) does not e$ist. <e*la.ed s.reen s)ots -ro/ 1CU -or 1+0 <ates and 3er-or/an.e *oints. :ade -inal. Too7 out re-eren.es to 03C4nu/ su(dire.tor8 and re9ister.(at #i$ed 1CU Control se.tion to .orre.t +DA *ara/eter. Too7 out t)e 25& and added in t)e value 12". De, s.reen s)ot also. #i$ed sa/*le (at.) -ile. U*dated T0C. Add +it s,it.) Added ne, s.reen s)ot -or 1CU se.tion. Added ne, .o//and line *ara/eter des.ri*tion to 1CU se.tion. U*dated t)e version nu/(er to 1.0.2.0 U*dated t)e version nu/(er to 1.0.%.0 Added 200% to availa(le *lat-or/s in -eatures ta(le. Added ne, -eatures to do.u/ent: 6ronl8 (*liU90420S1" , 6r3ause (*li U 91"40S1" Server level #ailover (*li U 91"20S1" +d(T25& (*liU95450S1" Add note on ,)at 03C s*e. is used. +d(T25& note in t)e de(u9 se.tion Add 31 301DT Con-i9uration tool <ev D. #i$ed )eaders, -ooters and T0C. :inor -or/attin9 .)an9es also. :ade .)an9es to t)e Con-i9uration Tool .o//and!line *ara/eters ta(le. @ersion 1.0.0.0 to 1.1.0.0<ev 4: 1nter-a.e does D0T su**ort inter-a.e!level -ailover as *reviousl8 stated.

0%!>un!2005 0&!>un!2005

:5ra.e :?ell8

25!>ul!2005 15!Au9!2005 "!Se*!2005 11!0.t!2005 1%!0.t!2005 17!0.t!2005

:5ra.e :?ell8 :5ra.e :5ra.e :?ell8 :5ra.e

1"!0.t!2005 07!Dov!2005 11!Dov!2005

:5ra.e :5ra.e :7ell8

12!>an!200&

C)r8s

O C *&+ Interface

1"!

&ate 19!A*r!200&

+uthor :5ra.e

Comments @ersion 1.2.0.0 <ev A Add ne, +/* startu* *ara/eter . ne, de(u9 settin9, d(T12" /eanin9. C)an9e t)e sa/*le.(at des.ri*tion to t)e (asi. one t)at sa8s to use t)e 1CU to .on-i9ure t)e startu* .(at -ile. @ersion 1.0.0.0 to 1.2.0.0 <ev A: u*dated /anual to .urrent standardsP re/oved -irst *erson re-eren.esP re/oved 312 re-eren.esP u*dated t)e 6o, to Conta.t Us *a9eP .)an9ed 9eneral re-eren.es -ro/ RDTS to R'indo,sS=P u*dated 1CU s.reen s)ots. @ersion 1.0.0.0 to 1.2.0.0 <ev C: U*dated SD? and 1CU se.tions. @ersion 1.0.0.0 to 1.2.0.0 <ev D: u*dated 6ard,are Dia9ra/s @ersion 1.2.00, <ev 4: U*dated /anual to S7eleton v2.5.%, a**lied te/*late and s*ell .)e.7ed do.u/ent. @ersion 1.%.1.0 Added 4 ne, startu* *ara/eters. Added state/ent t)at *i(u-ss s)ould not (e used ,it) t)is inter-a.e. 0nl8 (u-serv. @ersion 1.%.1.0 <ev AP U*dated all 1CU Control s.reens)ots, -i$ed .o*8ri9)t date, u*dated su**orted -eatures ta(le, u*dated installation .)e.7list, re-or/atted ta(les, u*dated 10<ates se.tion. @ersion 1.%.1.0 <evision A: u*dated *oint sour.e re-eren.es to su**ort /ulti*le .)ara.ter strin9sP -i$ed -or/attin9 on ta(les. @ersion 1.%.2.0 <ev A: Added % ne, startu* *ara/eters (+t-, +/a, +tsu . Lo.% .an also (e 1 -or in*uts as ,ell as 0. #or out*uts to ,or7, t)e 6DA Server /ust )ave S8n.U*date::1nsert<e*la.e /et)od i/*le/ented. S7eleton version %.0.% U*dated all se.tions to t)e %.0.% s7eleton. So/e se.tions ,ere -ro/ an older version o- t)e s7eleton. @ersion 1.%.2.0 <evision A: added Ter/inolo98 se.tionP u*dated )eadersP turn o-- tra.7in9 and a..e*t all .)an9esP re/oved DT4 as su**orted *lat-or/P -i$ed (ro7en )8*erlin7 #i$ /ista7e in t)e +d( and +*s des.ri*tion in t)e 6DATa9Auilder. Do *ara/eters in +d( and +*s is reGuired. T)e *rin.i*les o- o*eration sa8s .onne.tion is retried ever8 5 se.onds to *iserver and )daserver. 1t is &0 se.ond retr8 rate to t)e *iserver. 3)ase 2 -ailover. U*dated to S7eleton @ersion %.0.7 @ersion 1.4.0.0 <evision A, U*dates several se.tion and so/e s.reens)ots. #i$ed )eaders and -ooters. Corre.ted s*ellin9 errors. U*dated Ta(le o- Contents. A..e*ted all .)an9es and /ade #inal. Corre.t t)e out*ut na/e o- t)e )data9(uilder to )data9(uilder..sv. Add t)e +*s to t)e e$a/*le o- t)e )data9(uiler sin.e it is reGuired. R6istor8 <e.over8 0nl8 W 6istor8 ti/e ran9eS )eadin9

21!A*r!200&

>anelle

0"!:a8!200& 07!>ul!200& 04!De.!200& 2%!>an!200"

:5ra.e >anelle 3ro,e :5ra.e

27!#e(!200"

:7ell8

2"!#e(!200"

>anelle

0"!Au9!200"

:5ra.e

29!Se*!200" 01!0.t!200"

:5ra.e >anelle

19!Dov!200"

:5ra.e

25!#e(!2009 27!#e(!2009

:5ra.e :7ell8

%0!:ar!2009

:5ra.e

17!:ar!2010

:5ra.e

O C *&+ Interface

1%.

&ate

+uthor

Comments ,as indented so it loo7ed it ,as *art o- t)e +)r*ause se.tion. #i$ed t)e indention.

04!0.t!2010 0%!Dov!2010

D0Deill :5ra.e

U*dated to S7eleton @ersion %.0.2"

@ersion 1' '1': U&date ne/ !tartu& !/itc5e!' %oo> out +o!t of t5e DCOM !ection! and added reference to t5e DCOM Configuration <uide' @ersion A.3.A./ Bevision (6 Added note a-out t5e PI Me!!age "og and PIHOME@PIHOME6 ' Al!o added PI Me!!age "og in t5e %er+inology !ection' .i:ed ICU Control !ection' .i:ed !tyle! in ta-le!' @ersion A.3.A./ K A.3.1./G &ppdated the version number to include the new release with &niInt 3.9.1.:.

11!Dov!2010

:?ell8

2&!>ul!2011

:?ell8

O C *&+ Interface

1%1