UNIINT INTERFACE USER MANUAL PUBLICATION HSEUNI-UM001A-EN-E–July 2012
Contact Rockwell Automation Customer Support Telephone — 1.440.646.3434 Online Support — http://www.rockwellautomation.com/support Copyright Notice © 2012 Rockwell Automation Technologies, Inc. All rights reserved. Printed in USA. © 2010 OSIsoft, Inc. All rights reserved. This document and any accompanying Rockwell Software products are copyrighted by Rockwell Automation Technologies, Inc. Any reproduction and/or distribution without prior written consent from Rockwell Automation Technologies, Inc.
Table of Contents Introduction ................................................................................................................................... 1 Related Rockwell Automation Documents .......................................................... 1 Interface Startup Parameters ......................................................................................................... 3 Startup Options................................................................................................
Introduction Windows Performance Counters ................................................................................................ 33 Requirements .................................................................................................... 33 Installing and Removing Interface Performance Counters ................................ 33 Verifying Successful Performance Counter Operation ...................................... 34 Viewing Performance Counter Data ...................................
Remote Cache Builds ........................................................................................ 65 Messages .......................................................................................................... 66 Informational ...................................................................................................... 66 Configuration Errors .......................................................................................... 68 Troubleshooting ..............................
Introduction Error and Informational Messages.............................................................................................. 99 Message Logs ................................................................................................... 99 Messages on Windows ..................................................................................... 99 System Errors and PI Errors ............................................................................. 99 Error Descriptions on Windows ....
Introduction UniInt is an abbreviation for Universal Interface. UniInt is a framework for interfaces to the Historian Server. UniInt provides generic functions required by most interfaces such as establishing a connection to the Historian Server node and monitoring the Historian Point Database for changes. Using the UniInt framework ensures a standard set of features for Rockwell Automation interfaces to Historian and prevents duplication of effort.
Introduction Document Description Release notes for UniInt Release notes contain specific information about a particular version of UniInt. Release notes typically include: (UniIntReleaseNotes. doc) System requirements Installation notes Upgrading Whats new Changes in this release Outstanding issues Known limitations Contact information PI API Installation Instructions (API_Install.doc) This manual contains the installation instructions for the PI API and Bufserv.
Interface Startup Parameters Startup parameters determine the behavior of an interface. This chapter documents the available startup parameters for a UniInt based interface. Consult the interface specific documentation to discover which parameters are and are not supported by a particular interface. Startup Options Interface startup parameters can be specified using any one of the following three methods: Manually enter a series of parameters on the command-line.
Interface Startup Parameters Software\FactoryTalk Historian\PIPC\interfaces" and /path="C:\Program Files\Rockwell Software\FactoryTalk Historian\PIPC\interfaces" . Each entry in the following tables presents the parameter and its description. The Parameter column includes the UniInt default value for the parameter if there is one and whether or not the parameter is required or optional. Note: Parameter requirements vary from interface to interface.
Standard Parameters These command-line parameters are used in the every-day running of an interface. This table does not contain the entire list of parameters supported by UniInt. There are parameters that are specific to configuring disconnected start-up discussed in the Disconnect Start up section (page 54) and parameters specific to configuring UniInt Failover discussed in Configuring UniInt Failover section (page75). None of the parameters are case sensitive.
Interface Startup Parameters Parameter /DisableCounters Optional /ec or /ec=# Optional Description Point Loading 0x0040 Time Functions 0x0400 Digital State Caching 0x2000 Windows Performance counters are enabled by default. Counters can be disabled by specifying /disablecounters on the command-line. The first instance of the /ec parameter on the command-line is used to specify a counter number, #, for an I/O Rate point. If # is not specified, then the default event counter is 1.
Parameter Description an offset of 5 seconds, and the second scan class has a scanning frequency of 7 seconds with no offset. When no offset is specified, the scan class will be scheduled for immediate execution. That is, the interface will not wait for a well-defined moment in time before scanning when no offset is specified.
Interface Startup Parameters Parameter Description adhere to a wall clock for this particular scan class. Periods of 2, 3, 4, 6, 8, 12, or 24 hours or periods that are a multiple of 24 hours are implicitly scanned according to wall-clock scheduling as long as a time offset is explicitly defined for the scan class. A scan class can be explicitly defined to adhere to wall-clock scheduling by appending, L to the scan class definition.
Parameter Description /host=host:port The /host parameter is used to specify the Historian Home node. host is the IP address of the Historian Sever node or the domain name of the Historian Server node. port is the port number for TCP/IP communication. It is recommended to explicitly define the host and port on the command-line with the /host parameter. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults.
Interface Startup Parameters Parameter Description the /id parameter (such as /in, /ic, etc) to identify the copy of an interface. Consult the interface-specific documentation for more information. /IOSourceTime Optional /logps Optional /logUFOID Optional /maxstoptime= stoptime Optional Default = 120 seconds The /IOSourceTime stands for Initial output source timestamp. Some interfaces send the current value of the source tag at start-up.
Parameter Description /PISDK=# The /pisdk parameter can be used to enable or disable the PI SDK in some situations. Use /pisdk=1 to enable the PI SDK. Use /pisdk=0 to disable the PI SDK. If a particular interface requires the PI SDK, then the PI SDK will always be enabled and the /pisdk parameter will be ignored. Optional Default = 0 If the interface is running on an interface node with the PI API version 1.6.x or greater and the version of the Historian Server is 2.
Interface Startup Parameters Parameter Description /SVCEventsTO=# The /SvcEventsTO=x controls the Service Events TimeOut. The x is the timeout period specified in milliseconds. Events are serviced (retrieved from the evmexceptions queue on the Historian Server) for 500 milliseconds or until there are no more events in the queue. After either of those events, UniInt will perform the other tasks it is responsible for such as scanning for input data and checking for Historian point database changes.
Parameter Description /stopstat=digstate If the /stopstat parameter is present on the startup command-line, then the digital state Intf Shut will be written to each Historian Point when the interface is stopped. or /stopstat /stopstat only is equivalent to /stopstat="Intf Shut" Optional Default = no digital state written at shutdown. If /stopstat=digstate is present on the command-line, then the digital state, digstate, will be written to each Historian Point when the interface is stopped.
Interface Startup Parameters Parameter Description /updateinterval=# This parameter can be used to adjust the interval with which UniInt checks for point updates. The default interval is 120 seconds, the minimum interval for checking for point updates is 1 second, and the maximum interval is 300 seconds. See the section on Point Updates for more information. Optional Default = 120 seconds This parameter can be set to 0. Setting the update interval to 0 will disable checking for point updates.
Historian Point Configuration What are Historian Points? The Historian point is the basic building block for controlling data flow to and from the Historian Data Archive. Whereas a point in geometry has coordinates associated with it that define its position in space, a Historian point has attributes associated with it that determine the source and destination of data, the means by which the data is transmitted, how the data is stored in Historian, etc.
Historian Point Configuration user‘s manual for detailed discriptions of the Historian Point Attributes that are relavant to the interface. The following section describes common point attributes. The second and third sections describe how input and output points are configured and used. Point Attributes The following Historian Point Attributes are used by UniInt based interfaces.
PI API Historian Server PI SDK Maximum Length na Below 2.x Disabled 1 Below 1.6 na Disabled 1 na na Enabled 100 Case-sensitivity for PointSource Attributes In all cases, the point source character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=P and /ps=p are equivalent.
Historian Point Configuration The exception specification attributes are used to define exception-reporting specifications. Exception reporting is basically a filter. Raw values that the interface receives are filtered if they do not pass the exception-reporting specifications. If the raw values pass exception, they are sent to the Snapshot, where they can be viewed by client applications such as FactoryTalk Historian ProcessBook.
CompDev, CompMin, CompMax, CompDevPercent These are the compression specifications. CompDev is the compression deviation; CompMin is the compression minimum time; and CompMax is the compression maximum time. CompDevPercent and CompDev are related by: CompDev = CompDevPercent * Span / 100 where Span is defined by the Span Historian point attribute. The ―swinging door compression‖ algorithm is used to filter the data. The algorithm is described in the Historian Server Reference Guide manual.
Historian Point Configuration or equal to the Zero attribute and less than or equal to the Zero attribute plus the Span attribute. The TypicalValue must be between Zero and Zero plus Span. For digital points, Historian sets the Zero and Span internally. See the description of Zero and Span attributes for more information. SourceTag The SourceTag attribute is used to designate a trigger tag for output points.
ExDesc This is the extended descriptor attribute. The extended descriptor is a string attribute. Please refer to the Historian Tag String Attribute Limits section beginning on page 21 for a description of the maximum number of characters available to the interface for different configurations. Typically, if the extended descriptor is used by an interface, it is used to identify a point, address or location on the data source.
Historian Point Configuration New API functions Interface Requires SDK /PISDK Startup Parameter Max Tag Name Max Instrument Tag Max Extended Descriptor no no 0 254 32 83 no no 1 1023 1023 1023 no yes na 1023 1023 1023 yes na na 1023 1023 1023 Input Points Input points are used to write data to the Historian Data Archive. Each interface has its own rules for determining whether a given point is an input point or an output point.
timestamp of the previous value. This is different than the trigger mechanism for output points. For output points, the timestamp of the trigger value must be greater than (not greater than or equal to) the timestamp of the previous value. As of UniInt 3.3.4, conditions can be placed on trigger events. Event conditions are specified in the extended descriptor as follows: Event=‘trigger_tag_name’ event_condition The trigger tag name must be in single quotes.
Historian Point Configuration example, to write a value to a register in a PLC, one would use an output point. Each interface has its own rules for determining whether a given point is an input point or an output point. There is no de facto Historian point attribute that distinguishes a point as an input point or an output point. Outputs are triggered for UniInt-based interfaces. That is, outputs are typically not scheduled to occur on a periodic basis. There are two mechanisms for triggering an output.
I/O Rate Points I/O Rate points are used to monitor the data collection rate of an interface. An I/O Rate point can be configured to receive 10-minute averages of the total number of exceptions per minute that are sent to Historian by the interface. A value is considered an exception if it has exceeded the exception limits for a given Historian point.. Since 10-minute averages are taken, the first average is not written to Historian until 10 minutes after the interface has started.
Historian Point Configuration pipc.ini file, which is located in the %windir% directory. If both are specified, the PIPCSHARE entry takes precedence. Since the PIHOME directory is typically C:\Program Files\Rockwell Software\FactoryTalk Historian\PIPC, the full name of the iorates.dat file will typically be C:\Program Files\Rockwell Software\FactoryTalk Historian\PIPC\dat\iorates.dat. Add a line in the iorates.
specified if there is only one copy of an interface that is associated with a particular point source. 2. Set Location4 to correspond to the scan class whose performance is to be monitored. For example, to monitor scan class 2, set Location4 to 2. See the /f parameter for a description of scan classes. 3. Set the PointSource attribute to correspond to the /ps parameter on the startup command-line of the interface. 4.
Historian Point Configuration For Windows-based interfaces, PI SDK support is available beginning with version 3.2.0 of UniInt. UniInt uses the PI SDK to support the following features: Extended descriptors and instrument tags up to 1 kilobyte in length, or 1023 characters (UniInt 3.2.0). Starting with version 4.1.0 of UniInt, if version 1.6.x or greater of the PI API is installed on the interface node and the Historian Server is version 2.
Interface Operation Libraries UniInt 3.1.6 and lower versions use the PI API instead of the PI SDK. The PI API is described in detail in the FactoryTalk Historian application Programming Interface manual. The PI API library is distributed with the PI SDK. For installation instructions, refer to the PI API Installation Instructions manual. Version 1.3.x of the PI API is required for UniInt 3.x. UniInt version 3.2.0 and above use both the PI API and the PI SDK.
Interface Operation be established before the interface will continue. If the interface is started while the Historian Server is down, the interface will try to establish the connections until the Historian Server is up. Historian Point Updates When a UniInt-based interface starts, the interface searches the Historian Point Database for points that belong to the interface (see the PointSource attribute under ―Historian Point Configuration‖) and a point list is created for the interface.
Time UniInt 3.x handles time differently depending upon whether or not UniInt is running in extended PI API mode. A startup message in the pipc.log file clearly indicates whether or not UniInt is running in extended PI API mode. When the extended PI API features of UniInt are not enabled, UniInt 3.x handles time in the same manner as UniInt 2.x. This is called UniInt 2.x compatibility mode. UniInt 2.x Compatibility Mode UniInt 2.
Interface Operation However, the interface specific documentation must be consulted to determine the exact manner in which time is handled. UTC time is defined here as the number of seconds since January 1, 1970 00:00:00 in Greenwich, England. As of version 3.1.3, UniInt uses the UTC time of the Historian Server node instead of the UTC time of the local interface node. Ideally, the UTC times of the server and interface nodes are the same because UTC time is the same in every time zone.
Windows Performance Counters Counters are used to provide information as to how well an application, service, or driver is performing. Developers can define counters for an interface. The total number of interfacespecific and UniInt counters cannot exceed 200. This maximum is hard coded. Any counters in excess of 200 will be ignored. Requirements As of UniInt 3.5.
Windows Performance Counters where service_name is the interface executable name without the .exe extension and ServiceID is a service identifier that can be specified with the –serviceid command-line parameter when the service was installed. If the –serviceid command-line parameter is omitted when the service was installed, then the service identifier is NULL.
Viewing Performance Counter Data The values that are written to the performance counters can be viewed with the Windows Performance Monitor. On Window, the performance monitor is launched from Start | Programs | Administrative Tools (Common) | Performance Monitor. To view counters from within the Windows Performance Monitor, do the following. 1. Select the Add to chart command from the Edit menu. 2.
Windows Performance Counters Counter Name Description IO Rate (events/second) The number of events per second received by the interface. If this counter is viewed from the Windows performance monitor, one should increase the update time of the performance monitor to the minimum scan period for the interface. For example, say that the minimum scanning period for the interface is 5 seconds (/f=5).
counters will be installed. If performance counters are already installed, then the total number of counters for the interface is checked. If the total number of counters has changed, then the interface counters are uninstalled and re-installed. Therefore, if the developer adds a performance counter in a new interface version, the new counter will automatically be installed the next time that the interface is run as a service.
Windows Performance Counters The pictrdll.dll should be installed with version 1.3.4 and greater of the PI API in the PIPC\bin\ directory.
Interface Health Points There are several different types of points that may be used to monitor the health of an interface. The first type includes IO rate points, performance points, and Windows Performance counters. These points represent the traditional older methods for monitoring the health of an interface. IO rate and performance points are supported by UniInt based interfaces. The Windows performance counters require the Historian-PerfMon interface in order to get their values into Historian.
Interface Health Points The third type of points used to monitor interfaces is the Interface Information point. This point is different than any of the other points used for monitoring the health of an interface. There can be only one Interface Information point on a Historian Server and the pointsource does not match the /ps startup parameter for an interface. UniInt supports collecting a variety of information about the health of an interface.
Trigger Rate [UI_TRIGGERRATE] Integer Heartbeat Reporting Period Trigger Bad Value Rate [UI_TRIGGERBVRATE] Integer Heartbeat Reporting Period Scan Class IO Rate [UI_SCIORATE] Integer At Scan At Scan Scan Class Bad Value Rate [UI_SCBVRATE] Integer At Scan At Scan Scan Class Scan Count [UI_SCSCANCOUNT] Integer At Scan Reporting Period Scan Class Scans Skipped [UI_SCSKIPPED] Integer At Scan Reporting Period Scan Class Point Count [UI_SCPOINTCOUNT] Integer At Scan na Scan Clas
Interface Health Points General Interface Health Tags The general interface health tags pertain to the operation of the interface in general. A list of scan class health tags follows. The scan class health tags require a valid scan class be configured in Location4 of the Historian tag. The general Interface Health tags do not consider the Location4 value. Heartbeat ExDesc Keyword: [UI_HEARTBEAT] Update Interval: Once a second or based on scan class as described below.
Device Status ExDesc Keyword: [UI_DEVSTAT] Update Interval: On startup, on change, and shutdown. Description: The device status tag stores communication information about the interface and the foreign device. This tag will be evaluated only while the heartbeat tag is updating. The device status tag is a string type Historian point. During normal shutdown of the interface, the string text of ―4 | Intf Shutdown‖ will be written to this tag.
Interface Health Points Update Interval: Based on heartbeat tag update. Description: Counts number of all values (inputs, outputs, triggered inputs) being sent to Historian before exception processing occurs. This tag will update based on the the update rate of the heartbeat tag and may report zero for update intervals where no data was sent to Historian. If the value stops updating in Historian then this is an indication that the interface has stopped collecting data.
Counts number of output tag events that are sent to Historian before exception processing whose status is anything other than good. Output tags update based on some event and cannot be scheduled for an update rate. Therefore, the value of these tags will be updated at the same rate as the heartbeat tag and will reset after the performance summary interval. Note: If no output points are defined, the digital state value of “No Result” will be written to the point.
Interface Health Points tags configured to monitor a particular scan class, the Historian tag attribute Location4 must be set to a valid scan class. Scan classes are defined with the /f startup parameter. Please see the list of startup parameters for a description of the /f startup parameter. Scan Class Point Count ExDesc Keyword: [UI_SCPOINTCOUNT] Update Interval: When the associated class is scanned. If Location4 is 0, the point monitors the point count for unsolicited tags.
Description: The Scan Class Bad Value Rate Tag is used to calculate all the bad values being sent to Historian before exception processing from the device with a status of anything other than good. This tag can be defined for each scan class and is used for all input tags in that particular scan class. Scan Class Scans Skipped ExDesc Keyword: [UI_SCSKIPPED] Update Interval: Event driven and each performance summary interval.
Interface Health Points Scan Class Scan Time ExDesc Keyword: [UI_SCINSCANTIME] Update Interval: At the completion of associated scan class. Description: The Scan Class Scan Time is the total amount of elapsed time in milliseconds to read data from the foreign device, populate the input tags, and then send the data to Historian. The value for this tag is updated after each completed scan.
Interface Disconnected Startup Interfaces built with UniInt version 4.3.0.x or later include functionality to take advantage of the Disconnected Startup operation. Simply stated, disconnected startup allows the interface to start from a local cache file with or without a valid connection to the host Historian Server. This critical functionality prevents data loss when an interface needs to start up and it does not have a connection to the Historian Server.
Interface Disconnected Startup Interface The interface must be built against UniInt version 4.3.0.x or later. The interface node must have PI API version 1.6.1.5 or later installed. The interface must not utilize the PI SDK to retrieve the extended point attributes from the Historian Server.
Point Synchronization and Historian Server Connections An interfaces using the disconnected startup configuration has the ability to synchronize interface point configuration data with that of the host Historian Server.
Interface Disconnected Startup enabled. Once satisfied with interface operation and data collection, enable disconnected startup as described in this document and restart the interface. Limitations The following section describes the known limitations imposed on an interface running in the disconnected startup configuration. Extended Attribute Lengths To maximize the functionality of the disconnected startup configuration, the use of a Historian Server version 2 or later is recommended.
As a general rule, disconnected startup will not be supported if the Historian SDK is needed for the interface to start. However, an interface supporting disconnected startup as indicated in the supported features table which uses the PI SDK by default to retrieve extended point attribute information from the Historian Server will require additional configuration to take advantage of the disconnected startup feature.
Interface Disconnected Startup Startup Command File Configuration Note: The disconnected startup feature can not be used if the interface is using the PI SDK to retrieve extended point attribute information for points from the Historian Server. Either disable the PI SDK by defining /pisdk=0 in the startup command file or remove any disconnected startup parameters from the interface startup command file.
Sample Interface Startup Files The following is an example of an interface configured for Disconnected Startup. In this example, the interface name is ifc and the interface executable is ifc.exe. Any additional command-line parameters needed for the interface would be defined on the startup command-line file. The startup command file for the interface would be defined as follows: ifc.
Interface Disconnected Startup Figure 1: ICU configuration screen showing the UniInt Disconnected Startup parameters. Configuring for Disconnected Startup simply requires the user to select the option and enter a cache synch period if the default of 250ms is not desired. The PI SDK option is disabled and the /pisdk=0 parameter will be defined in an effort to disable the PI SDK. The synchronization period is limited to a value of 0 or a range of values from 50 to 3000 ms inclusive.
Figure 2: ICU configuration screen displaying a message that the time slice entered for the “Cache synchronization period” text field is out or range. To run in a disconnected startup configuration, the PI SDK must not be enabled. If the ICU has the ―Enable PI SDK‖ radio button selected, the ―UniInt Disconnected Startup‖ feature will be disabled. The following figure shows how the ICU display will look when the PI SDK is enabled.
Interface Disconnected Startup Figure 3: ICU configuration screen with the “Enable PI SDK” radio button selected. In this configuration, the “UniInt Disconnected Startup” feature is disabled and contains a message prompting the user to first disable the PI SDK if the disconnected startup feature is desired. UniInt version 4.3.0.x or later must be installed on the interface node to support the disconnected startup configuration.
Figure 4: ICU configuration screen with UniInt version 4.0.0.0. The UniInt version must be 4.3.0.x or later in order to support disconnected startup. In this configuration, the “UniInt Disconnected Startup” feature is disabled and the ICU displays a message indicating that disconnected startup requires UniInt 4.3.0.x or later. Disconnected Startup Architecture The architecture in the following figure shows the typical components of a UniInt interface utilizing the Disconnected Startup feature.
Interface Disconnected Startup Operation To configure the interface for disconnected startup operation, the required /CacheMode parameter must be defined in the interface startup command file. The interface will create two binary caching files on the interface node necessary for disconnected startup. These files require no user configuration. The disconnected startup configuration consists of five distinct modes of operation: creation, validation, construction, utilization, and synchronization.
Creation CAUTION: The interface will create a point cache file and digital set cache file necessary for the disconnected startup configuration. These files are automatically generated by the interface and are locked while the interface is running. To prevent data loss, these files must not be modified by the user when the interface is not running. The creation mode ensures the interface has the necessary cache files needed for the disconnected startup configuration.
Interface Disconnected Startup Validation CAUTION: Users must not modify the caching files created by the interface. User modification of either of the caching files has the potential of invalidating the file and inducing a data loss situation. If a file has been modified by the user, it should be deleted to allow the interface to create valid files necessary for the Disconnected Startup configuration. Newly created files will require a connection to the Historian Server to start the interface.
The point cache file is constructed in a similar fashion to the digital cache file. During interface startup, the interface requests and receives all points matching the required point source parameter listed in the startup command file. Upon receipt of the requested points from the Historian Server, the point record along with the associated extended attributes are requested from the Historian Server and immediately stored in the point cache file.
Interface Disconnected Startup Retrieve event counter point configuration. Retrieve system digital state set if requested. Retrieve point configuration for points matching interface point source value. This includes retrieving the digital state set for digital points. Retrieve additional points required by interface. (Trigger, Source, etc.) The interface will request point update information from the Historian Server at regular intervals.
Server becomes disconnected for any reason, point synchronization will be restarted upon reconnection to the Historian Server. The ―Messages‖ section of this document contains a listing of typical messages sent to the pipc.log file during the synchronization mode Remote Cache Builds Users have the option of building the cache files necessary for disconnected startup on a remote machine.
Interface Disconnected Startup Messages The following are examples of typical informational and error messages that can be found in the pipc.log file. Informational 21-Nov-06 16:57:51 WriteSeconds.exe>Historian-API> Attempting to initialize and validate cache file: c:/pipc/interfaces/test/test_freebird_abc_1_dgcache.dat. Meaning: The API Cache Manager will look for the digital cache file in the given path and attempt to initialize and validate the file.
21-Nov-06 16:57:51 WriteSeconds.exe>Historian-API> Successfully created cache file: c:/pipc/interfaces/test/test_freebird_abc_1_ptcache.dat. Meaning: The API Cache Manager was able to create a file with the file path and filename shown in the message. This message also means that the interface successfully connected to the Historian Server to retrieve versioning information needed to create the cache file.
Interface Disconnected Startup cache file, but the file has not been constructed with point record and attributes information. This message also indicates the digital cache will need to be constructed with digital state information. A connection to the server is required for the interface to start so the file can be constructed. 21-Nov-06 16:57:51 Historian-WriteSeconds 1> Point cache being constructed to store point information. Cache file: c:/pipc/interfaces/test/test_freebird_abc_1_ptcache.dat.
29-Nov-06 15:45:08 Historian-WriteSeconds 1> Disconnected Startup is not available with PI API prior to Version: 1.6, Build 1.5 To utilize the disconnected startup configuration, upgrade to PI API Version: 1.6, Build 1.5 or later and restart the interface. Stopping Interface. Meaning: The UniInt Cache Manager has found a PI API version currently installed on the interface node that does not support disconnected startup.
Interface Disconnected Startup Troubleshooting Interface Operation Problem: On restart, the interface is not loading all Historian Points with a fully configured cache file. Solution: 1. Make sure the cache files have been previously configured during the initial interface start using the disconnected startup configuration. This can be verified by reviewing Historian point value history on the Historian Server using the appropriate Historian client, such as DataLink and by reviewing the pipc.
3. Delete the cache files. 4. Restart the interface to generate new cache files.
UniInt Failover Scheme Introduction The UniInt failover scheme provides for a hot failover, no data loss solution given a single point of failover. The scheme requires the data source be able to communicate and service data to two interfaces simultaneously. Additionally, the failover configuration requires the interface supports outputs. UniInt interface level failover may be configured to send data to a H.A. Historian Server collective. The H.A.
UniInt Failover Scheme Active ID Heartbeat 1 Heartbeat 2 Data register 0 . . . Data register n DataSource DCS/PLC/Data Server Process Network IF-Node2 PI-Interface.exe /host=SecondaryPI /UFO_ID=2 /UFO_OTHERID=1 IF-Node1 PI-Interface.exe /host=PrimaryPI /UFO_ID=1 /UFO_OTHERID=2 Business Network Client Process Book DataLink PrimaryPI PI Server Role = 1 SecondaryPI PI Server Role = 2 Figure 1: Failover Architecture The failover architecture is shown in Figure 1.
Configuring UniInt Failover Start-Up Parameters The following table lists the start-up parameters used by UniInt Failover. All of the parameters are required expect the /UFO_Interval startup parameter. See the table below for further explanation. Parameter Value Description Failover ID /UFO_ID=1 The value is not required to be 1. The value must be a positive, non-zero integer and different from the failover ID of IF-Node2. /UFO_ID=2 The value is not required to be 2.
UniInt Failover Scheme Parameter Value Description Host Historian Server for Exceptions and Historian tag updates /Host=SecondaryPI to send data to a Historian Server collective, the value of the /host parameters should equal different members of the collective. This configuration will ensure output continue to be sent to the Data Source if one of the Historian Servers becomes unavailable for any reason.
Historian Tags The following table lists the required UniInt Failover Control Historian tags, the values they will receive and comments. Historian Tag Value Description Active ID Input Tag Updated by the redundant Interfaces The Active ID Input Tag must be configured as a valid input Historian tag for the interface and it must be configured to read the Active ID point on the data source.
UniInt Failover Scheme Historian Tag Value Description Heartbeat 2 Input Tag Updated by the Interface on IF-Node2 The Heartbeat 2 Input Tag must be configured as a valid input Historian tag for the interface and it must be configured to read the Heartbeat 2 Point on the Data Source. Exdesc: [UFO_HEARTBEAT:2] Values range between 0 and 31 Consult the Interface User‟s manual for a description of configuring input tags.
Historian Tag Value Description State 2 Tag Normally updated by the Interface on IF-Node2. The failover state tags are optional and do not require a point on the Data Source. The value of the state tag can be written to the Data Source by configuring a normal interface output tag and setting the SourceTag attribute to the failover state tag.
UniInt Failover Scheme only the control points on the data source are monitored. However, values are echoed to the Historian Server for the user to monitor. Manual failover can be accomplished by manually changing the active ID point on the data source to the appropriate failover ID. The figure above shows a typical network setup in the normal or steady state. This by no means includes the myriad of configurations that are supported, it is meant to be used for an example.
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 Historian. The primary interface is also updating its heartbeat point, monitoring the heartbeat point for the backup interface, and checking the active ID point every failover update interval. The backup interface is actively collecting and queuing data but not sending that data to Historian.
UniInt Failover Scheme interface is in a good status as determined by the backup. If the backup interface transitions to the primary, it will have data in its queue to send to Historian. This queued data is sent to Historian 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 UniInt. If UniInt receives data without a timestamp, the primary copy uses the current Historian Time to timestamp data sent to Historian.
Failover ID In a failover interface installation, each copy of the interface has its own unique positive integer identifier. This identifier is referred to as the failover ID and is specified with the interface startup parameter, /UFO_ID=n. Failover Update Interval The failover update interval determines the rate at which UniInt updates the heartbeat points, how long it takes for the interface to failover, and how much overlapping data may be sent to Historian.
UniInt Failover Scheme Input Data The term input data refers to data that originates on the data source and is collected by the interface and then written to the Historian Server. Interface Control Points An interface control point is a point on the data source that is used by UniInt to negotiate interface failover. The interface must be able to read the value of this point from the data source and write a value to this point on the data source.
Primary Interface When an interface is installed in a failover configuration, only one copy will be actively sending data from the data source to Historian and from Historian to the data source. This copy of the interface is referred to as the primary interface. Point For the discussion concerning failover, an entity that exists on the data source is referred to as a point. A point may also be referred to as a control point.
UniInt Failover Scheme The primary interface is stopped. On exit, the primary interface writes a value of 0 to its heartbeat point and to the active ID point. The backup interface reads the ActiveID. As soon as it detects a value of 0, it assumes the role of the primary interface. The primary interface may stop just after the backup checked the value of the control points on the data source.
Point Values Active_ID IF1 State IF1 Heartbeat 0 1 2 Primary Backup Off B Time Action T+0 Both interfaces are running with IF1 in the primary role. T+2.5 IF2 reads the active ID point and IF1‟s heartbeat point. Both are good so IF2 discards data in its queue older than time 0.5. T+2.8 Event A: IF1 shuts down gracefully, setting the active ID point and its heartbeat point to 0. T+3.
UniInt Failover Scheme Primary Interface Stops Updating Heartbeat Point There are a number of situations that can cause an interface to stop updating its heartbeat point. For example, the interface crashes, the interface is unable to write to the data source for any reason, or the interface is hung in a function call that does not return. The following scenario describes the steps taken by the backup copy of the interface to determine if it should assume the role as primary.
Point Values 0 1 2 Active_ID IF1 State A 15 14 13 12 11 ... 4 3 2 1 0 IF1 Heartbeat IF2 State D Primary Backup Off B C Action T+0 Both interfaces are running with IF1 in the primary role. T+2.1 Event A: IF1 stops updating its heartbeat point. T+3.5 Event B: IF2 notices that IF1‟s heartbeat has not updated. IF2 will discard data older than Time 1.5. T+4.5 Event C: IF2 notices that IF1 still has not updated its heartbeat. IF2 stops discarding old queued data. T+6.
UniInt Failover Scheme Manual Failover Initiating a manual failover requires that the backup interface be in a state equal to or better than the current primary copy of the interface. For example, if the current primary has a connection to the Historian Server and the backup does not, manual failover is not authorized. The backup interface will know the state of the primary by the value of the heartbeat point as explained in the next section.
Point Values Active_ID IF1 State 0 1 2 A Primary Backup Off Time Action T+0 Both interfaces are running with IF1 in the primary role. T+2.5 IF2 reads the active ID point and IF1‟s heartbeat point. Both are good, so IF2 discards data in its queue older than time 0.5. T+2.8 Event A: the active ID point on the data source is changed from 1 to 2. T+3 Event B: IF1 reads the active ID point and IF2‟s heartbeat point.
UniInt Failover Scheme Primary Interface Loses Connection to Historian Server Users may have criteria dependent upon continuous data flow to Historian. This failover prevents the disruption of data flow to Historian that may cause user dependent operations to fail when the connection to the Historian Server is lost. The following sequence of events is taken by the primary and backup interface if the primary interface loses its connection to the Historian Server.
Point Values 0 1 2 IF1 State IF1 Heartbeat IF2 State Time Action T+0 Both interfaces are running with IF1 in the primary role. T+2.5 IF2 reads the active ID point and IF1‟s heartbeat point. Both are good, so IF2 discards data older than time 0.5. T+3 Event A: IF1 updates its heartbeat to 30 because it has lost its connection to the Historian Server. When the connection to Historian is lost, the heartbeat for the interface increments between 17-31 and then back to 17.
UniInt Failover Scheme Primary Stops Updating Heartbeat Point for less than 5 Intervals This situation might occur if the primary interface copy fails to update its heartbeat point within four failover intervals due to the interface being ―stuck‖ somewhere in the code. In this scenario, the primary copy does come back to life and updates its heartbeat before the backup has assumed control. Moreover, it is assumed that the primary has missed scans for data during the time it failed to update its heartbeat.
Point Values Active_ID IF1 State IF1 Heartbeat IF2 State IF2 Heartbeat 0 1 2 Primary Backup Off 15 14 13 12 11 ... 4 3 2 1 0 Action T+0 Both interfaces are running with IF1 in the primary role. T+2.25 Event A: IF1 stops updating its heartbeat point for any reason. T+2.5 IF2 reads the active ID point and IF1‟s heartbeat point. Both are good so IF2 discards data older than time 0.5. T+3.5 Event B: IF2 notices that IF1‟s heartbeat point has not updated. IF2 discards data older than Time 1.5.
UniInt Failover Scheme Interfaces Connect to Data Source at Approximately the Same Time There may be a chance where both copies of the interface connect to the data source at approximately the same time and contend to become the primary interface. For example, both interfaces are running and then the data source is started, or both copies of the interface are started at the same time.
Refer to Figure 7,below which describes the failover action when both interface copies start at the same time and the latency for an update to the data source is equal to one half of an update interval. Point Values Active_ID IF1 State IF1 Heartbeat IF2 State IF2 Heartbeat C 0 1 2 D Primary Backup Off Time Action T+0 Neither interface is running T+1 Event A: IF1 starts and notices the active ID point is 0 so it transitions to active and writes a 1 to the active ID point. T+1.
UniInt Failover Scheme Time Action T+0 Both interfaces are running with IF1 in the primary role. T+2.1 IF2 reads the ActiveID and IF1‟s heartbeat. Both are good, so IF2 discards data older than time 0.1. T+2.9 Event A, IF1‟s stops for any reason just before updating its heartbeat. T+3.1 Event B, IF2 notices that IF1‟s heartbeat has not updated. IF2 will discard data older than Time 1.1. T+4.1 IF2 notices that IF1 still has not updated its heartbeat. IF2 stops discarding old queued data. T+5.
Error and Informational Messages Error messages that are written to the message log are prepended by a string NameID. Name is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id parameter on the startup command-line. Message Logs The location of the message log depends upon the platform on which the interface is running.
Error and Informational Messages Error Descriptions on Windows On Windows, descriptions of system and PI errors can be obtained with the pidiag utility: \PI\adm\pidiag –e error_number 100
Index Attribute Point CompDev, 19 CompDevPrecent, 19 CompMax, 19 CompMin, 19 Compressing, 18 DigitalSet, 21 ExcDev, 18 ExcDevPercent, 18 Exception Specification, 17 ExcMax, 18 ExcMin, 18 ExDesc, 21 Extended Descriptor, 21 Location4, 19 PointType, 17 Scan, 19 SourceTag, 20 Tag, 16 TypicalValue, 19 Bufserv ExcDevPercent, 17 Exception Specification attribute, 18 ExcDev, 18 ExcDevPercent, 18 ExcMax, 18 ExcMin, 18 ExDesc, 21 Exit handler, 30 Extended Descriptor attribute, 21, 22 Failover-UniInt, 82 Failover Sce
Error and Informational Messages Command-line, 3 Performance point, 26 Swinging-door algorithm, 19 Performance summary, 27 System errors, 99 PI errors, 99 Tag PI point Definition of, 15 Interface specific points, 15 PI SDK Support of interfaces, 28 pilogsrv, 99 Installation, 99 Point types, 17 Point updates, 30 PointSource attribute Command line parameters, 11 PointType.
