FACTORYTALK HISTORIAN TO HISTORIAN INTERFACE USER GUIDE PUBLICATION H2H-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 Chapter 1. Introduction ................................................................................................ 1 Interface Limitations ............................................................................................ 1 Interface Requirements ....................................................................................... 2 Reference Manuals .............................................................................................
Table of Contents Interface Directories ..........................................................................................32 PIHOME Directory Tree ..........................................................................32 Interface Installation Directory ................................................................32 Interface Installation Procedure ........................................................................32 Installing Interface as a Windows Service...............................
Configuring Synchronization through a Shared File (Phase 2) .........................78 Configuring UniInt Failover through a Shared File (Phase 2) ...........................81 Start-Up Parameters ...............................................................................81 Failover Control Points ...........................................................................83 Historian Tags .........................................................................................
Table of Contents Appendix A. Error and Informational Messages................................................... 137 Message Logs .................................................................................................137 Messages ........................................................................................................137 Interface Startup Messages ............................................................................137 Scan Summary ..........................................
Chapter 1. Introduction The Rockwell FactoryTalk Historian to Historian interface copies tag data from one Historian Server to another. Data is moved in one direction, meaning data is copied from the source to the receiving Historian Server (also referred to as target Historian Server). The interface must run on a Windows Intel-based operating system.
Introduction Automation recommends using n-way buffering which is supported with PI API v1.6.x and later. Please see the PI API installation manual for details. The Historian Archive subsystem may temporarily queue data in memory prior to it being committed to disk. This can lead to data gaps when using Historian to Historian for real-time data collection with history recovery enabled. To avoid data gaps the recommended configuration is to run in history recovery only mode without snapshot updates.
Reference Manuals Rockwell Automation Historian Server manuals PI API Installation manual UniInt Interface User Manual Historian Interface Status Supported Operating Systems Platforms Windows XP Windows 2003 Server Windows 7 32-bit application 64-bit application 32-bit OS Yes No 64-bit OS Yes (Emulation Mode) No 32-bit OS Yes No 64-bit OS Yes (Emulation Mode) No 32-bit OS Yes No 64-bit OS Yes (Emulation Mode) No Windows 2008 32-bit OS Yes No Windows 2008 R2 64-bit O
Introduction Feature Support Inputs to Historian: Scan-based / Unsolicited / Event Tags Scan-based Only * Supports Questionable Bit No Supports Multi-character PointSource Yes Maximum Point Count Unlimited * Uses PI SDK No PINet String Support No * Source of Timestamps Source Historian Server History Recovery Yes UniInt-based * Disconnected Startup * SetDeviceStatus Yes No Yes Failover Source Historian Server-Level UniInt Phase 2 Interface Level (Warm) * Vendor Software Required on Hi
Maximum Point Count While the interface does not have a hard-coded point count limit, there are performance dependencies that can effectively limit point count. The interface is a single-threaded process. This design exposes performance dependencies on Historian Server responsiveness and network quality. For example a high latency network connection will result in a significant decrease in data transfer rate over a network connection without high latency.
Introduction SetDeviceStatus The Historian to Historian Interface is built with UniInt 4.4.4.0. New functionality has been added to support health tags. The Health tag with the point attribute ExDesc = [UI_DEVSTAT] represents the status of the source device. The following events can be written into this tag: “1 | Starting” - the interface is starting. “Good” - the interface is properly communicating and reading data from the server.
The failover scheme is described in detail in the UniInt Interface User Manual, which is a supplement to this manual. Details for configuring this Interface to use failover are described in the UniInt Failover Configuration section of this manual. Device Point Types Real, Integer and Digital.
Introduction Figure 2: Configuration 2 PItoPI runs on the receiving Historian Server “pulling” data from the source Historian Server.
Figure 3: Configuration 3 PItoPI runs on a separate interface node.
Chapter 2. Principles of Operation The FactoryTalk Historian to Historian interface copies tag data from one Historian Server to another. It consists of a single executable and startup configuration file. No specific tag limit exists for the interface. However, data throughput (events/second) can be limited by network quality and/or system resources on the source and receiving Historian Servers. Users can configure the interface to copy exception (snapshot) or archive data.
Principles of Operation How FactoryTalk Historian to Historian Finds Source Points When the FactoryTalk Historian to Historian Interface loads a point, the interface must identify the source point from which data will be collected. In other parts of this manual, this process is referred to as mapping the interface point to a source point. The interface uses four receiving point attributes as possible links to the source point: InstrumentTag, ExDesc, UserInt1, and Tag.
source point ID and the search ends. Otherwise, proceed to the step 4. If the search ends in this step and either the UserInt1 attribute is not greater than zero or the interface is configured for source Historian Server-level failover, the interface rejects the point. 4. The source point tag name is the same as the receiving tag name. The search for the source point ends with either a source tag name or source point ID.
Principles of Operation In general the interface can sustain higher data rates (events/second) when configured for exception data collection. Exception updates are queued in memory on the source Historian Server. This is not the case for archive updates. Only the most recently accessed archive data is stored in memory, specifically the archive data cache. When the interface requests archive data it is likely a certain percentage is read from disk.
time then exits. The times specified are relative to the machine where the interface runs. This is important if the source Historian Server is in a different time zone than the machine where the interface runs. Note that backfilling data may require additional server preparations on the receiving node. For example, there may not be enough space in the target (non-primary) archive for the recovery data, or non-primary archives may not have space allocated for newly created tags.
Principles of Operation Archive Data Collection By default, the first scan class is used for exception data collection. Tags configured for any other scan class will receive archive data. However, exception data collection can be disabled entirely by specifying the /hronly interface startup switch. When specified, all scan classes update with archive data. When a scan is executed, each tag receives an incremental copy of data. An archive update begins at the interface tag‟s current value.
recovery nearly all data is obtained from disk reads. When the interface transitions to scanning for updates, disk reads should decrease as recent data is obtained from the archive memory cache. The percentage of data obtained via disk reads versus memory can be managed through the scan frequency. Increasing the scan rate should increase the percentage read from memory. Vice versa, decreasing the scan rate increases the percentages of data obtained from disk reads.
Principles of Operation Int16/32 Yes Digital No Yes String No No Yes No No Yes Interface Status Events The FactoryTalk Historian to Historian interface may update a tag to indicate a specific status event. These status events represent data that is generated by the interface and therefore will not exist for the source tag. There are three specific status events generated by the interface: IO Timeout status events are triggered when the interface loses a Historian Server connection.
number of tag edits are made, a user may choose to restart the interface. Restarting the interface will force it to process all edits by rebuilding its tag list. Error Handling When the interface encounters an error, it will print a message to the log file. If the error is tag-specific, the error message will include the tag name along with the specific error code. The tag is then marked by the interface as being in error and removed from the update list.
Principles of Operation between reconnection, and number of reconnection attempts are all user configurable parameters. Note: the default network timeout period is 60 seconds. This is not an interface configuration parameter. This is configured through the PI API configuration file, pilogin.ini. Please refer to the PI API Users Manual for information on adjusting the default timeout period. Detection of Stale Data The second failover condition is stale source data.
Failover Status When configured for server-level failover users can specify a status tag. The interface will update this tag to indicate whether the primary or secondary source server is active. It will also update this tag when it is in the process of failing over (no active source) or experiencing network communication errors. Deployment Scenarios There are two typical FactoryTalk Historian to Historian interface applications. One is to isolate users from the source Historian Server.
Principles of Operation Historian to Historian is used to transfer data within a collective when the data cannot be sent directly from the interface node. The following section describes typical configuration and deployment scenarios when running Historian to Historian within a collective. Tag Attribute Override Parameters The interface supports tag attribute override parameters. These startup parameters must be used when running the interface within a collective.
Example Architecture for Historian to Historian within a Historian Collective Tag attribute override parameters allow users to pass global settings that enable the interface to identify and build its tag list without requiring the tags to be defined explicitly for Historian to Historian. A detailed description of the tag attribute override parameters can be found in section Startup Command File section of this manual.
Principles of Operation Historian to Historian between Historian Collectives The following diagram architecture depicts a typical deployment of Historian to Historian for aggregating data between two Historian Collectives. Limitations The following limitations apply to the Historian to Historian interface when aggregating data between two collectives. Historian Collective Support The Historian to Historian interface is not collective aware.
After the interface is up and running, and if n-way buffering is enabled, the interface will collect data even if the receiving Historian Server is not available. This means data flow is not dependent on the receiving Historian Server once the interface has completed is startup initializations. Be aware that history recovery can be compromised when the interface is configured for nway buffering to a collective.
Chapter 3. Installation Checklist If you are familiar with running FactoryTalk Historian data collection interface programs, this checklist helps you get the interface running. If you are not familiar with Historian Interfaces, return to this section after reading the rest of the manual in detail. This checklist summarizes the steps for installing this Interface. You need not perform a given task if you have already done so as part of the installation of another interface.
Installation Checklist 9. Build input tags and, if desired, output tags for this Interface. Important point attributes and their use are: Location1 specifies the interface instance ID Location2 specifies for timestamp adjustment. Location3 specifies for configuring interface status events. Location4 specifies the scan class. Location5 sets the write mode of archived data on the receiving Historian Server. InstrumentTag specifies the name of the Source Tag from the Source Historian Server.
Advanced Interface Features Configure UniInt Failover; see that section in this document for details related to configuring the interface for failover.
Chapter 4. Interface Installation Rockwell Automation recommends that interfaces be installed on interface nodes instead of directly on the Historian Server node. An interface node is any node other than the Historian Server node where the FactoryTalk Historian application Programming Interface (PI API) has been installed (see the PI API manual). With this approach, the Historian Server need not compete with interfaces for the machine‟s resources.
Interface Installation Interface Directories PIHOME Directory Tree The [PIHOME] directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the %windir% directory. For 32-bit operating systems a typical pipc.ini file contains the following lines: [PIPC] PIHOME=C:\Program Files\Rockwell Software\FactoryTalk Historian\PIPC For 64-bit operating systems a typical pipc.
Installing Interface Service with Historian Interface Configuration Utility The Historian Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service: Service Configuration Service name The Service name box shows the name of the current interface service. This service name is obtained from the interface executable. ID This is the service ID used to distinguish multiple instances of the same interface using the same executable.
Interface Installation Log on as The Log on as text box shows the current “Log on as” Windows User Account of the interface service. If the service is configured to use the Local System account, the Log on as text box will show “LocalSystem.” Users may specify a different Windows User account for the service to use. Password If a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password.
If the Auto option is selected, the service will be installed to start automatically when the machine reboots. If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service. If the Disabled option is selected, the service will not start at all. Generally, interface services are set to start automatically.
Interface Installation Windows Service Installation Commands on an interface node or a Historian Server Node without Bufserv implemented Manual service PItoPI.exe -install -depend tcpip Automatic service PItoPI.exe -install -auto -depend tcpip *Automatic service with service ID PItoPI.exe -serviceid X -install -auto -depend tcpip *When specifying service ID, the user must include an ID number. It is suggested that this number correspond to the interface ID (/id) parameter found in the interface .
Chapter 5. PointSource The PointSource is a unique, single or multi-character string that is used to identify the Historian point as a point that belongs to a particular interface. For example, the string Boiler1 may be used to identify points that belong to the MyInt Interface. To implement this, the PointSource attribute would be set to Boiler1 for every Historian Point that is configured for the MyInt Interface.
Chapter 6. Historian Point Configuration The Historian point is the basic building block for controlling data flow to and from the Historian Server. A single point is configured for each measurement value that needs to be archived. The following tag attributes are used for defining interface points on the receiving Historian Server. Point Attributes Use the point attributes below to define the Historian point configuration for the interface, including specifically what data to transfer.
Historian Point Configuration The Historian 2 tag name attribute LongName is used if it exists. The receiving and source tag names do not need to be identical. However, unless the receiving tag attributes InstrumentTag or ExDesc specify the source tag name or the /ptid interface parameter is used, the receiving tag name is assumed to be the same as the source tag name.
Location2 Location2 specifies data timestamp adjustment. The source Historian Server supplies a timestamp for each data event. Users have the option of adjusting these timestamps to account for time differences between Historian Servers. It is required that each Historian Server have the correct system time for its configured time zone. See section Data Timestamps for a complete discussion.
Historian Point Configuration Location3 Value Write “I/O Timeout” Write “Access Denied” Include Snapshot Point Level Debugging 13 -- Yes Yes Yes 14 Yes -- Yes Yes 15 -- -- Yes Yes Location4 Scan-based Inputs For interfaces that support scan-based collection of data, Location4 defines the scan class for the Historian point. The scan class determines the frequency at which input points are scanned for new values.
modes. It is not possible for PI2 to have two values with the same timestamp. InstrumentTag Note: If the source tag name length exceeds 80 characters, users must use the UserInt1 attribute for source point mapping. This is due to a limitation with the PI API programming library which supports tag names of 80 characters or less for point ID resolution.
Historian Point Configuration following table indicates the maximum length of this attribute for all the different combinations of PI API and Historian Server versions. PI API Historian Server Maximum Length 1.6.0.2 or higher 2.x or higher 1023 1.6.0.2 or higher Below 2.x 80 Below 1.6.0.2 2.x or higher 80 Below 1.6.0.2 Below 2.x 80 If the Historian Server version is earlier than 2.x or the PI API version is earlier than 1.6.0.
Scan By default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the Scan attribute to 0 turns scanning off. If the Scan attribute is 0 when the interface starts, a message is written to the pipc.log and the tag is not loaded by the interface. There is one exception to the previous statement.
Historian Point Configuration Interface Configurations Data collected by the interface has already passed exception on the source Historian Server. For this reason interface exception filtering should be disabled. This can be done by specifying the /sn switch in the startup configuration file. This tells the interface to bypass exception and send data directly to the snapshot table on the receiving Historian Server.
DataAccess, PtAccess Historian 3 nodes use these attributes to control client read/write access to the data and point attributes. Access may be specified for owner, group and world. The user and groups used must be created before assignment. Example: dataaccess=o:rw g:rw w:r, ptaccess=o:rw g:r w:r. Zero, Span These attributes should match for the source and receiving points.
Chapter 7. Interface Status Tag Configuration The following procedure describes how to create and configure interface status tags. These tags are created on the receiving Historian Server. See section Interface Status Tags for a complete description of this functionality. 1. Create a digital state set for the status tag. The following tables display the digital state set definitions.
Chapter 8. Startup Command File Command-line parameters can begin with a / or with a -. For example, the /ps=M and -ps=M command-line parameters are equivalent. Command file names have a .bat extension. The Windows continuation character (^) allows for the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters.
Startup Command File Interface name as displayed in the ICU (optional) will have Historian- pre-pended to this name and it will be the display name in the services menu. Click Add. The following display should appear: Note that in this example the Host FactoryTalk Historian System is mkellyD630. To configure the interface to communicate with a remote Historian Server, select „Interface => Connections…‟ item from ICU menu and select the default server.
The PItoPI ICU control has 7 tabs for each scan class, plus the All Scan Classes settings. A yellow text box indicates that an invalid value has been entered, or that a required value has not been entered. The next figure shows the All Scan Classes settings. Notice the box for the Source host. This parameter is required and must be replaced with your server name, where the Historian to Historian data will be retrieved from.
Startup Command File FactoryTalk Historian to Historian Interface page Since the startup file of the FactoryTalk Historian to Historian Interface is maintained automatically by the ICU, use the PItoPI page to configure the startup parameters and do not make changes in the file manually. The following is the description of interface configuration parameters used in the ICU Control and corresponding manual parameters.
PI2 Security File – Use PI2 security file The PI2 Security File section is used only if the source host is a PI2 server. If a security file is to be used, select the Use PI2 security file check box. PI2 Security File - Unique Part The Unique part is the name suffix of tag security file on a Historian 2 system. The full name on the Historian 2 system is PItoPI.SEC, where is the portion specified in the Unique part box. (/SF=uniquename).
Startup Command File History Recovery Tab Maximum hours of history to recover Number of hours to recover history for all points. Setting the value to 0 disables history recovery for all points. See section History Recovery for more information about history recovery. (/RH=hours) The Use Default button is used to reset the value to the default setting of 8 maximum hours of history to recover.
Millisecond pause between history calls The number of milliseconds to pause between history recovery calls. (/HRPAUSE=millisecond) The Use Default button is used to reset the value to the default setting of 0 milliseconds to pause between history recovery calls. Use history recovery only (no snapshot data collection) If this check box is selected, tags do not sign up for exceptions. Each scheduled scan time (each scan class), history recovery is done from the last snapshot value to the current time.
Startup Command File Debug Tab Debug Parameters The Debug Levels parameter is used to set a debug level for debug messaging per scan class. Check all types of debug messages that you would like to see logged. Any combination of debug levels can be applied. (/DB=#,#,#,#...) Interface Status Tag on Receiving Historian Server: This is the name of an interface status tag configured on receiving server.
Location Tab Use the Override Tag Location Code Settings check boxes to configure the interface to ignore individual tag location codes and to apply specific settings for each of the location codes. Override Location 1 Ignore Location1 for each tag and load all tags configured for the specified point source regardless of Location1 and interface ID values. (/C1) Override Location 2 Ignore Location2 for each tag and set Location2 value to be this number for all interface tags.
Startup Command File Optional Tab Apply tag’s compression specifications to data retrieved during history recovery. Use compression specifications in tag configurations to send data retrieved during history recovery with compression. Usually data is retrieved from source server and sent to receiving server without compression during history recovery. (/DC) Source tag definition attribute. Use TagName on both (Ignoring ExDesc and InstrumentTag point attributes).
Specify maximum events to retrieve for a single point in each call to get history. This parameter is available for PI 2.0 and later receiving servers. It sets the maximum number of events to retrieve for a single point in each call to get history. With each call to retrieve history, one call is made to put it into the receiving server. At least one of these calls will be over the network, so using a small number could result in performance problems.
Startup Command File Opt Cont Tab Source Host reconnection delay. This parameter sets the time delay for attempting to reconnect to source Historian Server after a disruption. The number is entered in seconds and converted to milliseconds before being saved in the batch file. This number must be between 1 second and 8 hours. (/DELAYS=x, default: 0 seconds) Receiving Host reconnection delay. This parameter set the time delay for attempting to reconnect to receiving Historian Server after a disruption.
Source Historian Server Failover Tab Enable PItoPI Failover This check box is used to allow the configuration of the failover. Until this box is checked none of the items on this tab are enabled. Note that having this check makes items 2 and 3 required since they are in yellow. Source Server Interface Status Utility Tag This is the name of a Historian Interface Status Utility tag configured on the source server defined in /SRC_HOST=hostname.
Startup Command File Number of connection attempts to source server This parameter is used to specify the number of times to try connecting to source server if connection fails the first time. It can be used to restrict failover from occurring until after a certain number of attempts made to connect to the primary server have failed. The default number of attempts is 1.(/NT=x) Enable failover status logging. This check box is used to enable failover status logging.
General Interface Operation .BAT .INI Description /db=# DebugFlags /db=1 /db=2 /db=3 /db=4 /db=5 /db=6 /db=7 Optional : Max debug : Startup processing : Historian Server connections : PI2 security validation : Tag additions, edits, deletions : Data read & writes : Failover Example: /db=2,4,5 /delayr=# -- Millisecond time delay between reconnection attempts to the receiving Historian Server. Units are in milliseconds. Valid values are between 0 and 28800000ms (8 hours).
Startup Command File .BAT .INI Description the interface; the second occurrence defines the second scan class, and so on. Historian Points are associated with a particular scan class via the Location4 Historian Point attribute. For example, all Historian Points that have Location4 set to 1 will receive input values at the frequency defined by the first scan class. Similarly, all points that have Location4 set to 2 will receive input values at the frequency specified by the second scan class, and so on.
.BAT .INI Description Previously, wall clock scheduling was possible, but not across daylight saving time. For example, /f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a Daylight Saving Time change, the scan would occur either at 7 AM or 9 AM, depending upon the direction of the time shift. To schedule a scan once a day at 8 AM (even across daylight saving time), use /f=24:00:00,00:08:00,L.
Startup Command File .BAT .INI Description /ist=tagname -- Name of interface status tag. /ist= where < tagname> is a digital tag on the Optional receiving Historian Server. /ln=username SourceLogin Login name of PI user on Historian 2 node. This is used when source server is Historian 2. -- Number of seconds between calculating time offset between the interface and Historian Server nodes. -- The /ps parameter specifies the point source for the interface.
.BAT .INI Description /stopstat -- 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. 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. UniInt uses the first occurrence in the table.
Startup Command File History Recovery and Archive Data Collection .BAT .INI Description /dc -- Apply data compression to history recovery and archive scan updates. The default behavior is for this data to bypass compression. This switch must be specified to prevent data mismatches if tags are configured to include snapshot value with archive scan updates. HistOnly Used without "=start,end" to disable exception data collection.
.BAT .INI Description /ns -- Boundary condition for data retrieval with a timerange specific history recovery. When specified the interface will start history recovery beginning with the first value prior to the start time. The default behavior is to begin with the first value after the start time. HistRecovery Hours of history recovery to perform. There is no limit on the number of hours for history recovery.
Startup Command File Tag Attribute Override .BAT .INI Description /c1 -- Location1 tag attribute override. Optional /c2=# Load all tags configured for the specified point source regardless of Location1and interface ID values. -- Optional Location2 tag attribute override. Ignore Location2 for each tag and use the specified value. Valid values are 0-7. /c3=# -- Optional Location3 tag attribute override. Ignore Location3 for each tag and use the specified value. Valid values are 0-15.
.BAT .INI Description /sec_src= node :port -- Name or IP address of the secondary source Historian Server. /sec_src=node_name:tcpip_port Required The port number is 5450 (PI3). PI2 is not supported for source Historian Server failover. /ssu1=tag -- Required Historian Interface Status Utility tag name for the /src_host source Historian Server. /ssu1= Required for monitoring source data quality (current or stale data).
Startup Command File Sample PItoPI.ini File ; Sample PItoPI.ini ; ;-----------------------------------------------------------------; Purpose: ; This file should be used in conjunction with PItoPI.bat. It is only ; required when a user wishes to collect data from multiple source ; servers with a single copy of the interface. ; ; the headings read [FT-PItoPI-x.
Chapter 9. UniInt Failover Configuration Introduction To minimize data loss during a single point of failure within a system, UniInt provides two failover schemas: (1) synchronization through the data source and (2) synchronization through a shared file. Synchronization through the data source is Phase 1, and synchronization through a shared file is Phase 2.
UniInt Failover Configuration Quick Overview The Quick Overview below may be used to configure this Interface for failover. The failover configuration requires the two copies of the interface participating in failover be installed on different nodes. Users should verify non-failover interface operation as discussed in the Installation Checklist section of this manual prior to configuring the interface for failover operations.
Synchronization through a Shared File (Phase 2) Data register 0 . . . Data register n DataSource DCS/PLC/Data Server Process Network IF-Node1 PI-Interface.exe /host=PrimaryPI /UFO_ID=1 /UFO_OTHERID=2 /UFO_TYPE=HOT /UFO_SYNC=\\FileSvr\UFO\Intf_PS_1.dat FileSvr .\UFO\Intf_PS_1.dat IF-Node2 PI-Interface.exe /host=SecondaryPI /UFO_ID=2 /UFO_OTHERID=1 /UFO_TYPE=HOT /UFO_SYNC=\\FileSvr\UFO\Intf_PS_1.
UniInt Failover Configuration Configuring Synchronization through a Shared File (Phase 2) Step Description 1. Verify non-failover interface operation as described in the Installation Checklist section of this manual 2. Configure the Shared File Choose a location for the shared file. The file can reside on one of the interface nodes but Rockwell Automation strongly recommends that you put the file on a dedicated file server that has no other role in data collection.
Step 5. Description Test the configuration. After configuring the shared file and the interface and Historian tags, the interface should be ready to run. See Troubleshooting UniInt Failover for help resolving Failover issues. 1. Start the primary interface interactively without buffering. 2. Verify a successful interface start by reviewing the pipc.log file. The log file will contain messages that indicate the failover state of the interface.
UniInt Failover Configuration Step Description defined by the /UFO_ID startup command-line parameter. 13. 14. 15. 16. The Heartbeat control tags for both copies of the interface on the Historian Server must be changing values at a rate specified by the /UFO_Interval startup command-line parameter or the scan class which the points have been built against. Test Failover by stopping the primary interface. Verify the backup interface has assumed the role of primary by searching the pipc.
Configuring UniInt Failover through a Shared File (Phase 2) Start-Up Parameters Note: The /stopstat parameter is disabled If the interface is running in a UniInt failover configuration. Therefore, the digital state, digstate, will not be written to each Historian Point when the interface is stopped. This prevents the digital state being written to Historian Points while a redundant system is also writing data to the same Historian Points.
UniInt Failover Configuration Parameter Required/ Optional Description Value/Default exist, the first interface to start attempts to create the file. Note: If using the optional filename, do not supply a terminating slash or backslash character. If there are any spaces in the path or filename, the entire path and filename must be enclosed in quotes. Note: If you use the backslash and path separators and enclose the path in double quotes, the final backslash must be a double backslash (\\).
Parameter /Host=server Required/ Optional Required Description Value/Default Host Historian Server for Exceptions and Historian tag updates The value of the /Host startup parameter depends on the Historian Server configuration. If the Historian Server is not part of a collective, the value of /Host must be identical on both interface computers.
UniInt Failover Configuration Historian Tags The following tables list the required UniInt Failover Control Historian tags, the values they will receive, and descriptions. Active_ID Tag Configuration Attributes ActiveID Tag _ActiveID ExDesc [UFO2_ActiveID] Location1 Match # in /id=# Location5 Optional, Time in minutes to wait for backup to collect data before failing over.
The following table describes the extended descriptor for the above Historian tags in more detail. Historian Tag ExDesc Required / Optional Description Value [UFO2_ACTIVEID] Required Active ID tag The ExDesc must start with the case sensitive string: [UFO2_ACTIVEID]. The PointSource must match the interfaces‟ point source. Location1 must match the ID for the interfaces. Location5 is the COLD failover retry interval in minutes.
UniInt Failover Configuration 86 Historian Tag ExDesc Required / Optional Description Value [UFO2_DEVICESTAT :#] (IF-Node1) Required Device Status 1 Tag The ExDesc must start with the case sensitive string: [UFO2_HEARTBEAT:#] The value following the colon (:) must be the Failover ID for the interface running on IF-Node1 The PointSource must match the interfaces‟ point source. Location1 must match the ID for the interfaces.
Historian Tag ExDesc Required / Optional Description Value interface is running but cannot communicate with the data source. 2 = Backup No Historian Connection: The interface is running and connected to the data source but has lost its communication to the Historian Server. 3 = Backup: The interface is running and collecting data normally and is ready to take over as primary if the primary interface shuts down or experiences problems.
UniInt Failover Configuration Detailed Explanation of Synchronization through a Shared File (Phase 2) 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 Historian tags to control failover operation, and all failover communication between primary and backup interfaces passes through a shared data file.
points, then it cannot read any other data. There is no need for a backup communications path between the control data and the interface. When synchronizing through a shared file, however, we cannot assume that loss of control information from the shared file implies that the primary interface is down. We 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.
UniInt Failover Configuration is interrupted. The updates to the Historian Server will be buffered by Bufserv or PIBufss in this case. In a hot failover configuration, each interface participating in the failover solution will queue three failover intervals worth of data to prevent any data loss. When a failover occurs, there may be a period of overlapping data for up to 3 intervals. The exact amount of overlap is determined by the timing and the cause of the failover and may be different every time.
Failover Configuration Using ICU The use of the ICU is the recommended and safest method for configuring the interface for UniInt failover. With the exception of the notes described in this section, the interface shall be configured with the ICU as described in the Configuring the interface with ICU section of this manual.
UniInt Failover Configuration Configuring the UniInt Failover Startup Parameters with ICU There are three interface startup parameters that control UniInt failover: /UFO_ID, /UFO_OtherID, and /UFO_Interval. The UFO stands for UniInt Failover. The /UFO_ID and /UFO_OtherID parameters are required for the interface to operate in a failover configuration, but the /UFO_Interval is optional.
Using the ICU Utility to create Digital State Set To use the UniInt Failover page to create the UFO_State digital state set right-click on any of the failover tags in the tag list and then select the Create UFO_State Digital Set on Server XXXXXX…, where XXXXXX is the Historian Server where the points will be or are create on. This choice will be grayed out if the UFO_State digital state set is already created on the XXXXXX Historian Server.
UniInt Failover Configuration Figure 7: SMT application configured to import a digital state set file. The Historian Servers window shows the “localhost” Historian Server selected along with the System Management Plug-Ins window showing the Digital States Plug-In as being selected. The digital state set file can now be imported by selecting the Import from File option for the localhost. 5. Navigate to and select the UniInt_Failover_DigitalSet_UFO_State.
Figure 9: The SMT application showing the UFO_State digital set created on the “localhost” Historian Server.
UniInt Failover Configuration Creating the UniInt Failover Control and Failover State Tags (Phase 2) The ICU can be used to create the UniInt Failover Control and State Tags. To use the ICU Failover page to create these tags simply right-click any of the failover tags in the tag list and select the Create all points (UFO Phase 2) menu item. If this menu choice is grayed out it is because the UFO_State digital state set has not been created on the Server yet.
Chapter 10. Interface node Clock Make sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check the Automatically adjust clock for daylight saving changes box. For example, In addition, make sure that the TZ environment variable is not defined.
Chapter 11. Security The Historian Firewall Database and the Historian Proxy Database must be configured so that the interface is allowed to write data to the Historian Server. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the Historian Server manuals. Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to Historian version 3.3.
Security Security Configuring using Trust Editor The Trust Editor plug-in for System Management Tools 3.x may also be used to edit the Trust table. See the System Management chapter in the Historian Server manual for more details on security configuration. Historian Server v3.2 For Historian Server v3.
Source System Manager 1. The file PISysDat:PIServer.dat will be used to provide overall security for the FactoryTalk Historian database. In this file, the receiving node must be given at least read-login access. 2. Create and maintain a security file for each FactoryTalk Historian to Historian interface that will read data from the source system. This file is PISYSDAT:PITOPITEST.SEC, where TEST is the file name specified on the receiving node PIToPI command line. 3.
Security E! 102
Chapter 12. Starting / 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 ICU, the Services control panel or with the command: PItoPI.exe -start To start the interface service with ICU, use the button on the ICU toolbar.
Chapter 13. Buffering Buffering refers to an interface node‟s ability to temporarily store the data that interfaces collect and to forward these data to the appropriate Historian Servers. Rockwell Automation strongly recommends that you enable buffering on your interface nodes. Otherwise, if the interface node stops communicating with the Historian Server, you lose the data that your interfaces collect.
Buffering How Buffering Works A complete technical description of PIBufss and Bufserv is beyond the scope of this document. However, the following paragraphs provide some insights on how buffering works. When an interface node has buffering enabled, the buffering application (PIBufss or Bufserv) connects to the Historian Server. It also creates shared memory storage.
However, if the Historian Server contains an interface-specific Trust entry that allows a particular interface program to write data, you must have a Trust entry specific to buffering. The following are the appropriate entries for the Application Name field of a Trust entry: Buffering Application Application Name field for Trust Buffer Subsystem PIBufss.
Buffering Buffering Settings There are a number of settings that affect the operation of PIBufss and Bufserv. The Buffering Settings page allows you to set these parameters. If you do not enter values for these parameters, PIBufss and Bufserv use default values. PIBufss For PIBufss, the paragraphs below describe the settings that may require user intervention. Please contact Rockwell Automation Technical Support for assistance in further optimizing these and all remaining settings.
Send rate (milliseconds) Send rate is the time in milliseconds that PIBufss waits between sending up to the Maximum transfer objects (described below) to the Historian Server. The default value is 100. The valid range is 0 to 2,000,000. Maximum transfer objects Maximum transfer objects is the maximum number of events that PIBufss sends between each Send rate pause. The default value is 500. The valid range is 1 to 2,000,000. Event Queue File Size (Mbytes) This is the size of the event queue files.
Buffering Maximum buffer file size (KB) This is the maximum size of the buffer file ([PIHOME]\DAT\APIBUF.DAT). When Bufserv cannot communicate with the Historian Server, it writes and appends data to this file. When the buffer file reaches this maximum size, Bufserv discards data. The default value is 2,000,000 KB, which is about 2 GB. The range is from 1 to 2,000,000. Primary and Secondary Memory Buffer Size (Bytes) This is a key parameter for buffering performance.
The following screen shows that PIBufss is configured to write data to a Historian Collective named admiral. By default, PIBufss replicates data to all collective members. That is, it provides n-way buffering. You can override this option by not checking the Replicate data to all collective member nodes check box. Then, uncheck (or check) the Historian Server collective members as desired.
Buffering Bufserv Bufserv buffers data to a standalone Historian Server, or to multiple standalone Historian Servers. (If you want to buffer to multiple Historian Servers that are part of a Historian Collective, you should use PIBufss.) If the Historian Server to which you want Bufserv to buffer data is not in the Server list, enter its name in the Add a server box and click the Add Server button.
Installing Buffering as a Service Both the PIBufss and Bufserv applications run as a Service. Buffer Subsystem Service Use the Buffer Subsystem Service page to configure PIBufss as a Service. This page also allows you to start and stop the PIBufss service. PIBufss does not require the logon rights of the local administrator account. It is sufficient to use the LocalSystem account instead. Although the screen below shows asterisks for the LocalSystem password, this account does not have a password.
Buffering API Buffer Server Service Use the API Buffer Server Service page to configure Bufserv as a Service. This page also allows you to start and stop the Bufserv Service Bufserv version 1.6 and later does not require the logon rights of the local administrator account. It is sufficient to use the LocalSystem account instead. Although the screen below shows asterisks for the LocalSystem password, this account does not have a password.
FactoryTalk Historian To Historian Interface User Guide 115
Chapter 14. Interface Diagnostics Configuration The Interface Point Configuration chapter provides information on building Historian Points for collecting data from the device. This chapter describes the configuration of points related to interface diagnostics. Note: The procedure for configuring interface diagnostics is not specific to this Interface. Thus, for simplicity, the instructions and screenshots that follow refer to an interface named ModbusE.
Interface Diagnostics Configuration You configure one Scan Class Performance Point for each Scan Class in this Interface. From the ICU, select this Interface from the Interface drop-down list and click UniInt-Performance Points in the parameter category pane: Right-click the row for a particular Scan Class # to bring up the context menu: You need not restart the interface for it to write values to the Scan Class Performance Points.
Correct / Correct All If the “Status” of a point is marked “Incorrect”, the point configuration can be automatically corrected by ICU by right-clicking on the line belonging to the tag to be corrected, and selecting Correct. The Performance Points are created with the following Historian attribute values. If ICU detects that a Performance Point is not defined with the following, it will be marked Incorrect: To correct all points click the Correct All menu item.
Interface Diagnostics Configuration Snapshot The Snapshot column holds the snapshot value of each Performance Point that exists in Historian. The Snapshot column is updated when the Performance Points/Counters tab is clicked, and when the interface is first loaded. You may have to scroll to the right to see the snapshots. Performance Counters Points When running as a Service or interactively, this Interface exposes performance data via Windows Performance Counters.
Click Create to create the Performance Counters Point for that particular row. Click Create All to create all the Performance Counters Points listed which have a status of Not Created. To see the current values (snapshots) of the created Performance Counters Points, right-click on any row and select Refresh Snapshots. Note: The Historian Performance Monitor Interface - and not this Interface - is responsible for updating the values for the Performance Counters Points in Historian.
Interface Diagnostics Configuration The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for example, “sy.perf.etamp390.E1(Scan Class 1).point_count” refers to Scan Class 1, “(Scan Class 2)” refers to Scan Class 2, and so on. The tag containing “(_Total)” refers to the sum of all Scan Classes. “Scheduled Scans: % Missed” (.sched_scans_%missed) A .
foreign device connections to the interface. This value will always be less than or equal to the Expected Connections. “Device Expected Connections” (.Device_Expected_Connections) The .Device_Expected_Connections Performance Counters Point stores the total number of foreign device connections for the interface. This is the expected number of foreign device connections configured that should be working properly at runtime.
Interface Diagnostics Configuration “Historian Status” (PI_Status) The .PI_Status Performance Counters Point stores communication information about the interface and the connection to the Historian Server. If the interface is properly communicating with the Historian Server then the value of the counter is „0‟. If the communication to the Historian Server goes down for any reason then the value of the counter will be „1‟.
received a new value within the Stale Period then the point will move from the Good count to the Stale count. Only points that are Good can become Stale. If the point is in the In Error count then it will remain in the In Error count until the error clears. As stated above, the total count of Points Good, Points In Error and Points Stale will match the Point Count for the interface. “Points Stale 30(min)” (.Points_Stale_30min) The .
Interface Diagnostics Configuration Interface Health Monitoring Points Interface Health Monitoring Points provide information about the health of this Interface. To use the ICU to configure these points, select this Interface from the Interface drop-down list and click Health Points from the parameter category pane: Right-click the row for a particular Health Point to display the context menu: Click Create to create the Health Point for that particular row.
For some of the Health Points described subsequently, the interface updates their values at each performance summary interval (typically, 8 hours). [UI_HEARTBEAT] The [UI_HEARTBEAT] Health Point indicates whether the interface is currently running. The value of this point is an integer that increments continuously from 1 to 15. After reaching 15, the value resets to 1.
Interface Diagnostics Configuration [UI_SCINFO] The [UI_SCINFO] Health Point provides scan class information. The value of this point is a string that indicates the number of scan classes; the update frequency of the [UI_HEARTBEAT] Health Point; and the scan class frequencies An example value for the [UI_SCINFO] Health Point is: 3 | 5 | 5 | 60 | 120 The Interface updates the value of this point at startup and at each performance summary interval.
The Interface updates this point at the same frequency as the [UI_HEARTBEAT] point. The Interface resets the value of this point to zero at each performance summary interval. [UI_OUTPUTBVRATE] The [UI_OUTPUTBVRATE] Health Point tracks the number of System Digital State values that the interface writes to output tags that have a SourceTag. If there are no output tags for this Interface, it writes the System Digital State No Result to this Health Point.
Interface Diagnostics Configuration A particular Scan Class‟s [UI_SCBVRATE] point indicates the number System Digital State values that the interface has collected. The Interface updates the value of a [UI_SCBVRATE] point after the completion of the associated scan. Although the ICU allows you to create the point with the suffix “.sc0”, this point is not applicable to this Interface. [UI_SCSCANCOUNT] You can create a [UI_SCSCANCOUNT] Health Point for each Scan Class in this Interface.
[UI_SCINSCANTIME] You can create a [UI_SCINSCANTIME] Health Point for each Scan Class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Scan Time.sc1) refers to Scan Class 1, “.sc2” refers to Scan Class 2, and so on.
Interface Diagnostics Configuration As the preceding picture shows, the ICU suggests an Event Counter number and a Tagname for the I/O Rate Point. Click the Save button to save the settings and create the I/O Rate point. Click the Apply button to apply the changes to this copy of the interface. You need to restart the interface in order for it to write a value to the newly created I/O Rate point.
Event Counter The Event Counter correlates a tag specified in the iorates.dat file with this copy of the interface. The command-line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file. Tagname The tag name listed under the Tagname column is the name of the I/O Rate tag. Tag Status The Tag Status column indicates whether the I/O Rate tag exists in Historian.
Interface Diagnostics Configuration Search Allow the user to search the Historian Server for a previously defined I/O Rate tag. Interface Status Point The Historian Interface Status Utility (ISU) alerts you when an interface is not currently writing data to the Historian Server.
Click Create to create the ISU tag. Use the Tag Search button to select a Watchdog Tag. (Recall that the Watchdog Tag is one of the points for which this Interface collects data.) Select a Scan frequency from the drop-down list box. This Scan frequency is the interval at which the ISU monitors the Watchdog Tag. For optimal performance, choose a Scan frequency that is less frequent than the majority of the scan rates for this Interface‟s points.
Appendix A. Error and Informational Messages A string NameID is pre-pended to error messages written to the message log. Name is a nonconfigurable 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. See the UniInt Interface User Manual for more information.
Error and Informational Messages Scan Summary After a scan class has finished history recovery, the interface logs messages indicating the number of tags in error for the scan class. PItoPI- 1> Scan class 1: History recovery completed successfully. PItoPI- 1> Scan class 1: 0 of 385 points in error. The messages above indicate the number of points successfully registered with the update manager on the source node and the number of errors encountered in the given scan class.
UniInt Failover Specific Error Messages Informational Message 16-May-06 10:38:00 PItoPI 1> UniInt failover: Interface in the “Backup” state. Meaning Upon system startup, the initial transition is made to this state. While in this state the interface monitors the status of the other interface participating in failover. When configured for Hot failover, data received from the data source is queued and not sent to the Historian Server while in this state.
Error and Informational Messages 140 Message 16-May-06 17:38:06 PItoPI 1> One of the required Failover Synchronization points was not loaded. Error = 0: The Heartbeat point for this copy of the interface was not loaded. The input Historian tag was not loaded Cause The Heartbeat tag is not configured properly. Resolution Check validity of point attributes. For example, make sure Location1 attribute is valid for the interface. All failover tags must have the same PointSource and Location1 attributes.
Errors (Phase 2) Unable to open synchronization file Message 27-Jun-08 17:27:17 Historian Eight Track 1 1> Error 5: Unable to create file „\\georgiaking\GeorgiaKingStorage\UnIntFailover\\PIEightT rack_eight_1.dat‟ Verify that interface has read/write/create access on file server machine. Intializing uniint library failed Stopping Interface Cause This message will be seen when the interface is unable to create a new failover synchronization file at startup.
Appendix B. PI SDK Options To access the PI SDK settings for this Interface, select this Interface from the Interface dropdown list and click UniInt - PI SDK in the parameter category pane. Disable PI SDK Select Disable PI SDK to tell the interface not to use the PI SDK. If you want to run the interface in Disconnected Startup mode, you must choose this option. The command line equivalent for this option is /pisdk=0.
Appendix C. Terminology To understand this interface manual, you should be familiar with the terminology used in this document. Buffering Buffering refers to an interface node‟s ability to store temporarily the data that interfaces collect and to forward these data to the appropriate Historian Servers. N-Way Buffering If you have Historian Servers that are part of a Historian Collective, PIBufss supports n-way buffering.
Terminology Historian Collective A Historian Collective is two or more replicated Historian Servers that collect data concurrently. Collectives are part of the High Availability environment. When the primary Historian Server in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your Historian clients. PIHOME PIHOME refers to the directory that is the common location for Historian 32-bit client applications.
SMT SMT refers to System Management Tools. SMT is the program that you use for configuring Historian Servers. A single copy of SMT manages multiple Historian Servers. SMT runs on either a Historian Server Node or an interface node. pipc.log The pipc.log file is the file to which OSIsoft applications write informational and error messages. When a Historian interface runs, it writes to the pipc.log file. The ICU allows easy access to the pipc.log.
Appendix D. Technical Support and Resources Rockwell provides dedicated technical support internationally, 24 hours a day, 7 days a week. You can read complete information about technical support options, and access all of the following resources at the Rockwell Automation Support Web site (http://www.rockwellautomation.com/support/). Technical Support Please visit Rockwell Automation Customer Support Center (http://www.rockwellautomation.
Technical Support and Resources If you are not located in North America and want to contact Rockwell Automation Support, use the Worldwide Locator (http://www.rockwellautomation.com/locations/) for worldwide contact information. Consulting Services If you are not located in North America and want to contact Rockwell Automation Support, use the Worldwide Locator (http://www.rockwellautomation.com/locations/) for worldwide contact information.
