FactoryTalk

Historian to Historian
Interface User Guide

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

Supersedes Publication H2H-UM001A-EN-E-July 2012

User Manual Original Instructions

FactoryTalk Historian to Historian Interface Users Guide

Important User Information

Read this document and the documents listed in the additional resources section about installation, configuration, and
operation of this equipment before you install, configure, operate, or maintain this product. Users are required to familiarize
themselves with installation and wiring instructions in addition to requirements of all applicable codes, laws, and standards.
Activities including installation, adjustments, putting into service, use, assembly, disassembly, and maintenance are required to
be carried out by suitably trained personnel in accordance with applicable code of practice.
If this equipment is used in a manner not specified by the manufacturer, the protection provided by the equipment may be
impaired.
In no event will Rockwell Automation, Inc. be responsible or liable for indirect or consequential damages resulting from the use
or application of this equipment.
The examples and diagrams in this manual are included solely for illustrative purposes. Because of the many variables and
requirements associated with any particular installation, Rockwell Automation, Inc. cannot assume responsibility or liability for
actual use based on the examples and diagrams.
No patent liability is assumed by Rockwell Automation, Inc. with respect to use of information, circuits, equipment, or software
described in this manual.
Reproduction of the contents of this manual, in whole or in part, without written permission of Rockwell Automation, Inc., is
prohibited.
Throughout this manual, when necessary, we use notes to make you aware of safety considerations.
WARNING: Identifies information about practices or circumstances that can cause an explosion in a hazardous environment, which may lead to
personal injury or death, property damage, or economic loss.

ATTENTION: Identifies information about practices or circumstances that can lead to personal injury or death, property damage, or economic loss.
Attentions help you identify a hazard, avoid a hazard, and recognize the consequence.

IMPORTANT Identifies information that is critical for successful application and understanding of the product.

Labels may also be on or inside the equipment to provide specific precautions.

SHOCK HAZARD: Labels may be on or inside the equipment, for example, a drive or motor, to alert people that dangerous voltage may be present.

BURN HAZARD: Labels may be on or inside the equipment, for example, a drive or motor, to alert people that surfaces may reach dangerous
temperatures.

ARC FLASH HAZARD: Labels may be on or inside the equipment, for example, a motor control center, to alert people to potential Arc Flash. Arc Flash will
cause severe injury or death. Wear proper Personal Protective Equipment (PPE). Follow ALL Regulatory requirements for safe work practices and for
Personal Protective Equipment (PPE).

2 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Table of Contents

Chapter 1
Introduction to the Historian to Reference manuals ..................................................................................... 8
Historian Interface Supported features ..................................................................................... 8
Diagram of hardware connection ............................................................ 12

Chapter 2
Principles of operation Interface startup ........................................................................................ 15
How the Historian to Historian Interface finds source points .............. 15
History recovery ......................................................................................... 17
Real-time data collection ........................................................................... 18
Performance considerations ..................................................................... 19
Data timestamps ....................................................................................... 20
Data type conversion................................................................................. 20
Interface status events .............................................................................. 20
Error handling ............................................................................................ 21
Source Historian Data Archive level failover for Historian to Historian
..................................................................................................................... 22
Tracking interface status .......................................................................... 25
UniInt interface failover support ............................................................. 25
Loss of connectivity to Data Archive ........................................................ 26

Chapter 3
Installation checklist Read-only and read-write interfaces ....................................................... 27
Disable read-write interface updates to the data source ................. 27
Data collection steps ................................................................................. 28
Interface diagnostics (optional) ............................................................... 29
Advanced interface features (optional) ................................................... 29

Chapter 4
Installation instructions Name conventions and requirements...................................................... 31
Interface directories ..................................................................................32
PIHOME directory tree........................................................................32
PIHOME64 directory tree ....................................................................32
Interface installation directory ........................................................... 33
Interface installation procedure ............................................................... 33
Silent installation procedure ............................................................... 33
Historian trust for interface authentication ............................................ 33
Install interface as Windows service ........................................................ 33
Install interface service with Interface Configuration Utility (ICU)...... 34
Install interface service manually .............................................................36

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 3

Table of Contents

Chapter 5
Historian Point configuration Point attributes ..........................................................................................39
Tag (Historian Point name) ................................................................39
PointSource (point source)................................................................. 40
PointType (data type) .......................................................................... 40
Location1 (interface instance) ............................................................ 40
Location2 (time stamp adjustment) ................................................... 41
Location3 (status events, snapshot data, digital states, and point
logging) ................................................................................................. 41
Location4.............................................................................................. 42
Location5............................................................................................... 43
InstrumentTag .....................................................................................44
ExDesc...................................................................................................45
SourceTag ............................................................................................ 46
Scan .......................................................................................................47
Shutdown..............................................................................................47
Bufserv and PIBufss .............................................................................47
DataSecurity ........................................................................................ 48
PtSecurity ............................................................................................ 48
ExcMax ExcMin and ExcDev (exception processing) ...................... 48
Interface status digital point configuration ........................................... 48

Chapter 6
Startup command file Configure the interface with ICU ............................................................. 51
Historian to Historian Interface .............................................................. 53
Historian to Historian General: scan classes, host information and
interface installation path ................................................................... 53
Required tab ......................................................................................... 53
History Recovery tab ............................................................................54
Debug tab .............................................................................................. 57
Location tab .......................................................................................... 57
Optional tab ..........................................................................................59
Opt Cont tab ......................................................................................... 61
Source PI Server Failover tab ............................................................. 62

Chapter 7
Command line parameters General interface operation parameters..................................................65
History recovery and archive data collection parameters ..................... 68
Point attribute override parameters ........................................................ 70
Source Historian Data Archive-level failover parameters...................... 70
Sample PItoPI.bat file ................................................................................ 71
Sample PItoPI configuration file ............................................................. 72

4 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Table of Contents

Specific considerations for Chapter 8

Historian to Historian Interface Push/pull configuration ............................................................................ 75

Error and informational Chapter 9

messages from the Historian to Message logs ............................................................................................... 77
Historian Interface
Chapter 10
PI SDK options B - H............................................................................................................. 81
Glossary I - N ............................................................................................................. 82
P .................................................................................................................. 83
S - T ............................................................................................................. 85
Legal Notices Legal Notices ............................................................................................. 87

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 5

 Chapter 1

Introduction to the Historian to Historian

Interface

The Historian to Historian Interface copies point data from one Data Archive
to another. Data is moved in one direction only, from the source to the target
Data Archive. Typical applications for the interface include the following:
• Isolate users from the source Data Archive to increase security,
improve load distribution, or resolve remote access issues.
• Maintain a copy of archive data on a secondary Data Archive, perhaps
as a backup.
• Create a test copy of a production Data Archive.
• Aggregate data from many Data Archives in a single Data Archive.
Note: You can also use the Historian to Historian interface for data replication in Historian
collectives, as an alternative to fanning data using buffering. Only use Historian to Historian
for data replication in a Historian collective if it is required for your system configuration or
security needs. For details about high-availability strategies, refer to the High Availability
Administration Guide.

Interface Historian Points are created on the target Data Archive. Each
interface point is configured to receive either exception (snapshot) or archive
data for a unique source point. Historian Points receive archive or exception
data from the source point. Exception data is data that has not yet been
subjected to compression. By default, all points in scan class 1 receive
exception data. Historian Points assigned to any other scan class receive
archive data.
The interface supports history recovery, which recovers data for time periods
when the interface was not running or was unable to collect data. The history
recovery period is configurable, and the default is eight hours.
Both source Data Archive-level failover and UniInt phase 2 interface-level
failover are supported. When running in source Data Archive-level failover
mode, the interface obtains data from one of two available source Data
Archives. To ensure that the interface obtains the same data regardless of
which source server is active, the source Data Archives must have identical
point definitions and data streams for all interface source points. In UniInt
failover mode, two copies of the interface are connected to the source Data
Archive at the same time. If the primary interface stops collecting data, the
backup interface assumes the primary role and continues data collection.
Failover maximizes interface data availability on the target Data Archive(s).
Source Data Archive-level failover and UniInt Phase 2 interface level failover
modes can be run simultaneously.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 7

Chapter 1 Introduction to the Historian to Historian Interface
• Note: The value of [PIHOME] variable for the 32-bit interface will depend on whether the interface
is being installed on a 32-bit operating system (C:\Program Files\PIPC) or a 64-bit operating
system (C:\Program Files (x86)\RockwellSoftware\FactoryTak Historian\PIPC).
The value of [PIHOME64] variable for a 64-bit interface will be C:\Program Files\Rockwell
Software\FactoryTalk Historian\PIPC on the 64-bit operating system.
In this documentation, [PIHOME] will be used to represent the value for either [PIHOME] or
[PIHOME64]. The value of [PIHOME] is the directory which is the common location for client
applications.
• This interface has been built against a UniInt version (4.5.0.59 and later) which now writes all its
messages to the local PI Message log.
Please see the document UniInt Interface Message Logging for UniInt 4.5.0.x and later Interfaces
in the %PIHOME%\Interfaces\UniInt directory for more details on how to access these
messages.

Reference manuals For more information, refer to the following manuals.

Content Source Location

PI Data Archive documentation See PI Data Archive in PI-Server-2018-SP3-

The Common
Patch-1-Installation-and-Upgrade-Guide-
EN.pdf. Files\Rockwell\Hel
PI API Installation Instructions API_install.doc p\FactoryTalk
PI Universal Interface (UniInt) PI-Universal-interface-(UniInt)-4.7.1-User- Historian to
Framework User Guide Guide-EN.pdf Historian
How to Read New UniInt Interface Knowledgebase Document ID: QA61077 - Interface 3.10.01
Message Logs How to read new UniInt Interface message
directory in the
logs?
Program Files (32-
PI Interface Configuration Utility (ICU) PI-Interface-Configuration-
User Guide Utility_1.4.16.79.pdf bit operating
system) or
Program Files
(x86) (64-bit
operating system)
folder.

Supported features
Feature Support
Interface Part Number PI-IN-OS-PI-NTI
Auto Creates Historian Points * APS Connector
Point Builder Utility No
ICU Control Yes
Historian Point Types All data types are supported
Sub-second Timestamps Yes
Sub-second Scan Classes Yes
Automatically Incorporates Historian Point Attribute Yes
Changes
Exception Reporting Yes
Inputs to Historian Data Archive Scan-based only
Outputs to source Historian Data Archive No

8 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 1 Introduction to the Historian to Historian Interface

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 Data Archive
History Recovery * Yes
UniInt-based * Yes
Disconnected Startup * Yes
SetDeviceStatus * Yes
Failover * Source Historian Data Archive-Level; UniInt Phase 2
Interface Level (Warm Only)
Vendor Software Required on Interface Node / No
PINet Node
Vendor Software Required on Data Source Device No
Vendor Hardware Required No
Additional PI Software Included with interface No
Device Point Types float16, float32, float64, int16,
int32, digital, timestamp, string, and
blobs
Serial-Based interface No

* See paragraphs below for further explanation.

APS Connector
AutoPointSync is a product that synchronizes the point configuration of
Historian Data Archives. The Historian to Historian APS Connector is
required to use APS with this interface.
Note: The Historian to Historian APS Connector contains a separate implementation of the procedure
to identify the source point for an interface point. If an interface instance is registered with APS,
consult the Historian to Historian APS Connector manual to confirm that the Historian to Historian
APS Connector version implements the same procedure as the interface, which is required to ensure
that the Historian to Historian APS Connector synchronizes with the same source point as the
interface. For a detailed explanation of how the interface identifies source points, refer to How the
Historian to Historian Interface finds source points on page 15.

Supports questionable bit

The interface copies questionable bit data for a given source point from one
Historian Data Archive to another.

Uses PI SDK
The PI SDK and the PI API are bundled together and must be installed on each
PI Interface node. This interface does not require the PI SDK.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 9

Chapter 1 Introduction to the Historian to Historian Interface

Maximum point count

The interface does not enforce a hard-coded maximum for the number of
points it can maintain, but it is a single-threaded process and its performance
is affected by hardware, network conditions, and workload. For
recommendations about optimizing interface performance, see Performance
considerations on page 19. For details about monitoring interface
performance, refer to the PI Universal Interface (UniInt) User Guide in the
Common Files\Rockwell\Help\FactoryTalk Historian to Historian Interface
3.10.01 directory in the Program Files (32-bit operating system) or Program
Files (x86) (64-bit operating system) folder.

Source of time stamps

The source Historian Data Archive provides a time stamp for each data event.
The interface can also adjust time stamps for clock drift, which is the time
offset between Historian Data Archives after accounting for time zone
differences. An offset of 30 minutes or less is considered clock drift. Adjusting
for clock drift means the time offset is added to the source time stamp,
adjusting it to target Historian Data Archive time. Time stamp adjustment for
individual points is configured using the Location2 point attribute. Interface
nodes and the source and target Historian Data Archives must have the
correct system time for their time zone.

History recovery
History recovery enables you to recover archive data for time periods when
the interface was not running or otherwise unable to collect data. History
recovery is performed on startup, after restoring a lost Historian Data Archive
connection and after a disruption in exception data collection. In addition,
when a new point is added to the interface, history recovery is performed on
that point. The history recovery period is configurable. The default is to
recover data for the previous 8 hours. To disable history recovery, set the time
Maximum hours of history to recover /RH command line parameter equal to
0. You can also recover data for a specified time period. If you specify a start
and end time, the interface recovers data for the specified period, then exits.

UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file;
it is a Rockwell Automation-developed template used by developers and is
integrated into many interfaces, including this interface. The purpose of
UniInt is to keep a consistent feature set and behavior across as many of
Rockwell Automation's interfaces as possible. It also allows for the very rapid

10 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 1 Introduction to the Historian to Historian Interface
development of new interfaces. In any UniInt-based interface, the interface
uses some of the UniInt-supplied configuration parameters and some
interface-specific parameters. UniInt is constantly being upgraded with new
options and features.

Disconnected Start-Up
The Historian to Historian interface is built with a version of UniInt that
supports disconnected start-up. Disconnected start-up is the ability to start
the interface without a connection to the Historian Data Archive. This
functionality is enabled by adding /cachemode to the list of start-up
parameters or by enabling disconnected startup using the ICU. Refer to the PI
Universal Interface (UniInt) User Guide for more details on UniInt disconnected
startup.
Enabling disconnected start-up not only creates cache files for the target
server, but also for the source server with the following format:
exename_hostname_id_dgcache.dat and exename_hostname_id_ptcache.dat
Note: If you are running multiple instances of the Historian to Historian interfaces, Rockwell
Automation recommends that you use individual folders to create cache files for each instance to
enable the various instances to access the cache files exclusively without any access violations.

SetDeviceStatus
The health point with the point attribute ExDesc = [UI_DEVSTAT] represents
the status of the source device. The following events can be written into this
point:
• 1 | Starting: The interface is starting.
• Good: The interface is properly communicating and reading data from
the server. The following events indicate a failure to communicate with
the server:
• 3 | 1 device(s) in error | Network communication error to source PI
server
• 3 | 1 device(s) in error | Unable to get archive data from source PI
server
• 3 | 1 device(s) in error | Unable to obtain snapshot events from source
PI server
• 3 | 1 device(s) in error | Unable to register for snapshot updates on
source PI server
• 4 | Intf Shutdown: The interface is stopped.
Refer to the PI Universal Interface (UniInt) User Guide for more information
about how to configure health points.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 11

Chapter 1 Introduction to the Historian to Historian Interface

Failover
• Source Historian Data Archive-level Failover Support
Source Historian Data Archive-level failover maximizes interface data
availability on the target Data Archive(s). It enables the interface to
obtain data from one of two source Historian Data Archives. Each
source server must have identical point definitions and data streams
for interface source points. The interface initiates failover if the active
source data becomes stale or is not available due to network issues.
• UniInt Failover Support
UniInt Phase 2 failover provides support for cold, warm, or hot failover
configurations. The Historian to Historian Interface only supports
warm failover. In warm failover configurations, you can expect a small
period of data loss during a single point of failure transition. This
failover solution requires that two copies of the interface be installed
on different interface nodes with the primary collecting data and the
backup interface available on failure. Phase 2 failover requires each
interface have access to a shared data file. Failover operation is
automatic and operates with no user interaction. Each interface
participating in failover can monitor and determine liveliness and
failover status. To assist in administering system operations, the
ability to manually trigger failover to a desired interface is also
supported by the failover scheme. The failover scheme is described in
detail in the PI Universal Interface (UniInt) User Guide, which is a
supplement to this manual. Details for configuring this interface to
use failover are described in the *** section of this manual.
Diagram of hardware Rockwell Automation recommends that you install the interface on the same
computer as the source Historian Data Archive and push data to the pi buffer
connection
subsystem (which sends data to the Historian Data Archive) to reduce or
eliminate arising from a network outage.

Place the Historian to Historian interface as close to the source Data

Archive as possible
The source and target Historian Data Archives are established in the
interface's startup batch file. Whether the interface pushes or pulls data
depends on where the interface is installed. From a performance standpoint,
Rockwell Automation recommends that the Historian to Historian Interface
push data to the destination server and be installed on the same computer as
the source Historian Data Archive. The PI Buffer Subsystem should be
enabled on the interface machine to push data to the destination Historian
Data Archive, thus reducing network outage issues. If it is not possible for the
Historian to Historian Interface to be on the same computer as the source
Historian Data Archive, then it is preferable to place it as close as possible to

12 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 1 Introduction to the Historian to Historian Interface
the source Historian Data Archive. If the interface is installed on the same
computer as the destination Historian Data Archive and pulls data then there
is a greater chance for loss of connection issues.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 13

Chapter 1 Introduction to the Historian to Historian Interface

14 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 2

Principles of operation

You can configure the interface to copy exception (snapshot) data or archive
data. For best performance, configure a separate instance of the interface for
each source Historian Data Archive. If you intend to copy both archive and
exception data, configure separate instances of the interface for each type of
data. Data throughput (events per second) can be limited by network quality
or system resources.

Interface startup On startup, the interface reads site-specific operating parameters such as
source and target Historian Data Archive, data update rates, and history
recovery settings, from its configuration file. Next, the interface connects to
the source and target Historian Data Archives. Each connection to a Historian
Data Archive is associated with a specific PI user. On the source server, this
user must have permission to read Historian Point attributes and data. On the
target server, the user must have read access for point attributes and read and
write data access for its points.
Next, the interface builds a list of target Historian Points, grouping points
internally by scan class. Each target point must have a source point. If an
invalid point configuration is detected, the point is either rejected or added to
the point list and marked as erroneous, and the interface logs the error.
After the interface builds its point lists, it calculates the time offset between
Historian Data Archives. Each participating node must be configured with the
correct system time for its time zone. During operation, the offset is checked
every two minutes. The offset is used for data time stamp adjustments (if
enabled) and to time stamp interface status events.
Finally, the server performs history recovery and begins real-time data
collection.

How the Historian to When the FactoryTalk Historian to Historian Interface loads a point, the
interface must identify the source point from which data will be collected. In
Historian Interface finds other parts of this manual, this process is referred to as mapping the interface
source points point to a source point.
The interface uses four receiving point attributes as possible links to the
source point: InstrumentTag, ExDesc, UserInt1, and Tag. However, the
Historian to Historian Interface /tn, /tnex , and /ptid parameters exclude one
or more of these attributes from mapping to the source point. For most
interface instances, none of these parameters are used. The following table

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 15

Chapter 2 Principles of operation
summarizes the effect of these parameters on the search for either source
point tag name or point ID. The actual implementation of the search is
described below the table.
Interface command line parameters Search order for attribute containing source point
/tn /tnex /ptid tag name or ID

No No No 1. Non-empty InstrumentTag attribute is source point

tag name.
2. ExDesc attribute that contains STAG= specifies
source point tag.
3. UserInt1 attribute greater than 0 contains source
point ID. (Point rejected if source Historian Data
Archive- level failover configured.)
4. Tag of the interface point is also source point tag
name.
No No Yes UserInt1 attribute contains source point ID. (Illegal
configuration if source Historian Data Archive-level
failover is configured.)
No Yes No • 1. ExDesc attribute that contains STAG= specifies
source point tag.
• 2. Tag of the interface point is also source point tag
name.
No Yes Yes Tag of the interface point is also source point tag name.
Yes No No

The interface performs the following steps to find the source point:
1. If the /tn, /tnex, and /ptid command line parameters are not specified,
and the InstrumentTag attribute is not a zero-length string, the
InstrumentTag value contains the source tag name and the search
ends. Otherwise, proceed to step 2.
2. If the /tn and /ptid command line parameters are not specified and the
ExDesc attribute begins with case-insensitive “STAG” followed by zero
or more spaces followed by “=”, the source tag name is extracted from
the remainder of the ExDesc value (as described in the following
paragraph) and the search ends. Otherwise, proceed to step 3.
To extract the source tag name, the interface ignores any spaces
following the “=”. If the next character is not a double quotation mark
("), it is the first character of the source tag name which extends to the
first comma or to the end of the ExDesc attribute. If the first non-
space following the “=” is a double quotation mark, the source tag
name begins with the following character and extends to the first
double quotation mark or to the end of the ExDesc attribute. The
interface extracts the source tag name from ExDesc and the search
ends.
3. If no /tn parameter and no /tnex command line parameter and either
the UserInt1 attribute is greater than zero or the /ptid parameter is
present, the UserInt1 attribute is the source point ID and the search
ends. Otherwise, proceed to the step 4. If the search ends in this step

16 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 2 Principles of operation
and either the UserInt1 attribute is not greater than zero or the
interface is configured for source Historian Data Archive-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. If the source tag name or point ID does not exist, the interface puts
the point into an error state and logs a message.

History recovery History recovery enables you to recover archive data for time periods when
the interface was not running or otherwise unable to collect data. During
history recovery, the interface updates target Historian Points with values
from the source archive, according to the settings you configure. The interface
performs history recovery after the following events:
• During interface startup (before starting real-time data collection)
• After restoring a lost Historian Data Archive connection
• During queue overflow error recovery
• Whenever a new target point is added to the interface
You can specify the recovery period, time increments within the total recovery
period, a pause time between increments, and the maximum number of
archive events that are returned per data request. These parameters enable
you to manage the performance impact on the source and target Historian
Data Archives by throttling the data collection rate.
Time-range history recovery is configured in the interface startup
configuration file, which you edit using ICU. When time-range recovery is
enabled, the interface starts up, recovers archive data for the specified start
and end time then exits. Specify the recovery start and end times in the time
zone where the interface runs, even if the source Historian Data Archive is in
a different time zone than the machine where the interface runs. Ensure that
the target archive has enough space for the data to be recovered.
The starting point for history recovery is determined on a point-by-point
basis. If the current value for a point is more recent than the starting point of
the recovery period, history recovery begins at the point’s current value, to
prevent data overlap, streamline data retrieval, and prevent out-of-order data.
For points that collect future data and newly-created points with no archive
data, the interface performs history recovery for the total recovery period.
History recovery is performed independently for each scan class. Source data
is written to the target archive in one of three modes: append, replace or no
replace. This setting is configured on a point-by-point basis. The interface logs
the progress of recovery.
By default, during history recovery, the interface also collects real-time
exception data every five seconds. To configure this time interval using ICU,
go to the Optional tab and select the check box Set time interval between
clearing exception queue during history recovery. As it nears the end of its

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 17

Chapter 2 Principles of operation
point list, more points are in the update list and the time to collect exception
updates increases. This extra overhead can significantly increase the time
required to complete history recovery.
By default, history recovery bypasses compression testing on the target server
when its version is Historian Data Archive 3.3 or later. Target Historian Data
Archives that are pre-3.3 always apply the compression-test to incoming data.

Real-time data collection During real-time data collection, the interface reads events from the source
Historian Data Archive and sends them to the target server. There are two
options for determining where the source data comes from:
• Archive data
This data has passed exception testing by whatever interface accepted
the data and has passed compression testing on the source server.
However, reading data from the Historian Data Archive increases the
workload on the source server, because the data is read from disk.
• Exception data
This data has passed exception testing by the interface that accepted it
but has not passed compression testing by the source server. Reading
exception data imposes less workload on the source server because the
data resides in memory. To ensure the closest correspondence between
values on the source and target servers, you should configure identical
compression settings on the source and target servers. To configure a
Historian Point for exception data collection, you should assign it to
scan class 1. Because the snapshot value is not applicable to future tags,
future tags cannot be placed in the first scan class.
The source Historian Data Archive provides a time stamp for each data event.
The interface might adjust time stamps to account for time zone differences
and clock drift between Historian Data Archives. Each Historian Data Archive
must be configured with the correct time for its time zone. For individual
points, you can configure time stamp adjustment by setting the Location2
point attribute.
Target point definitions can be modified while the interface is running. The
interface checks with the target Historian Data Archive for point
configuration updates, every two minutes by default. These updates include
adding, editing, and removing points. Processing point updates is a low
priority for the interface. To prevent update processing from delaying data
collection, the interface processes a maximum of 25 point updates at a time. If
there are more than 25 point updates, the interface checks every 30 seconds
until all updates have been processed. If a large number of point edits are
made, consider stopping and restarting the interface, to force it to process all
edits by rebuilding its point list.

18 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 2 Principles of operation

Performance Minimize network latency

considerations To minimize the effect of network latency on data throughput, run the
Historian to Historian Interface on the source Historian Data Archive
computer with buffering enabled.

Maximize archive cache reads

Historian Data Archives version 3.4 and higher cache a small amount of recent
archive data in memory (by default, four events). The size of this server cache
is configurable, and you can adjust the frequency of scan classes so that scans
occur frequently enough to maximize the reading of archive data from the
cache rather than from disk.

Reading archive data versus exception data

You can configure the interface to collect data from the source server’s archive
or from its snapshots (exception data). Reading snapshots is faster, because
data is read from memory rather than disk. However, exception data has not
been compressed. To read a point’s snapshot (exception data), assign the
point to scan class 1.

Managing memory consumption

The Historian Data Archive maintains update manager queues that store
events in memory for client applications such as Historian Interfaces. The
server creates separate queues for each client application that requests
updates. The queues grow between scans as exceptions accumulate on the
source Historian Data Archive. To control the amount of server memory
consumed by update queues, you can configure a maximum size for
individual queues and a maximum for the total amount of memory consumed
by all update queues. If a queue reaches its maximum size, the server stops
queuing updates for the interface, which causes the interface to delete its
point list, log errors, and enter history recovery to reinitialize data collection.
To configure these limits, set MaxUpdateQueue and TotalUpdateQueue using
System Management Tools or the piconfig utility. Default maximums for
queue size are as follows (specified as exception events per client application):
• Historian Data Archive 3.4.375.38 (PR1) and later: 50000
• Historian Data Archive 3.3 to Historian Data Archive 3.4.370: 4096
• Historian Data Archive 3.2: 2000
To calculate the minimum queue size required, use the following formula:

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 19

Chapter 2 Principles of operation
Minimum Limit = Interface Point Count * Scan Rate (Sec)

For example, if the interface is maintaining 10,000 target points with a scan
rate of 10 seconds, set the pending update limit and global update limit to at
least 100,000. You can also manage the workload by careful configuration of
scan rates for target points. Choose a small initial scan rate (for example 10
seconds), then use a performance point to determine the average time
required to complete the exception data scan and adjust the scan rate
accordingly.

Data timestamps The source Historian Server provides a timestamp for each data event. These
timestamps may be adjusted to account for time zone differences and clock
drift between Historian Servers. It is required that each Historian Server have
the correct system time for the configured time zone.
Timestamps are automatically adjusted for time zone differences when both
source and receiving servers are PI3. PI3 timestamps are based on the number
of seconds that have elapsed since Jan.1, 1970 UTC (Universal Coordinated
Time). Each UTC time stamp contains a time offset from Greenwich Mean
Time that represents the local time zone setting.
PI3 data includes time zone information that allows for automatic adjustment
to local time.
The interface can also adjust for clock drift between Historian Servers. Clock
drift is the time offset between Historian Servers after accounting for time
zone differences. An offset of 30 minutes or less is considered clock drift.
When the appropriate timestamp adjustment is configured, the time offset is
added to the timestamp provided by the source Historian Server adjusting it
to receiving Historian Server time. Timestamp adjustment is configured on a
tag-by-tag basis using the Location2 tag attribute.
Note: All computers (interface node, source and receiving Historian Server) must have the correct
system time for the configured time zone.

Data type conversion If the data types of the source and target Historian Points differ, the interface
can convert source data to compatible target data types as follows:
Source point data type Compatible target point data type
Float 16/32/64 Int16/32, Digital
Int16/32 Float, Digital
Digital Int16/32
String Digital

Interface status events The 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. Three specific status
events can be generated by the interface:

20 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 2 Principles of operation
• IO Timeout status events are triggered when the interface loses a
FactoryTalk Historian Server connection. This information informs
users that current data is not being collected. An event is written to
indicate the time of disconnection and another event is written to
indicate the time of reconnection.
Note: When UniInt interface failover is configured, the interface will suppress writing IO
Timeout to its Historian Points. If the interface did write IO Timeout then when the backup
interface transitions to primary, it won't be able to send data older than the IO Timeout event.
• Access Denied status events are written whenever the interface is
denied access to a tag’s data or attribute information.
• Intf Shut status events are enabled through /stopstat startup
parameter. When enabled an event is written when the interface is
stopped and again on startup. These events tell users that no data is
being collected because the interface is not running. See a more
detailed description in the section General interface operation
parameters on page 65.
To prevent a data mismatch between Historian Servers these status events
should be disabled. If enabled, these events create a data gap that will not be
filled through history recovery.
Each tag receives an IO Timeout event at the time of Historian Server
disconnection and a second event at reconnection. Likewise, when the
interface is stopped and started a 'Shutdown' event is written to each tag.
History recovery begins either at the start of the recovery period or a tag's
current value, whichever is more recent. The status events are updated prior
to performing history recovery, making them the starting point of the
recovery period for each tag. This results in a gap in data for a time period that
might otherwise be recovered.
Interface status events are configured on a tag-by-tag basis through the
Location3 tag attribute. Interface shutdown events are enabled through the
interface startup script. By default shutdown events are not written by the
interface.
Note: Refer to the topic Command line parameters on page 65 for additional information about the
potential for data mismatches. In particular read the /sn parameter description; and see
Knowledgebase Document ID: QA61544 - SE to SE Interface - Considerations for best data match in
source and target servers.

Error handling When the interface encounters an error, it writes a message to the log file. If
an error is not Historian Point-specific, the interface determines whether it is
still connected to the Historian Data Archive. If the error is Historian Point-
specific, the point is then marked by the interface as erroneous and is
removed from the update list. The interface attempts to read erroneous points
every ten minutes. If an attempt succeeds, the point is restored to active data
collection.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 21

Chapter 2 Principles of operation

Source Historian Data Source Historian Data Archive-level failover maximizes interface data
availability on the receiving Historian Data Archive. Source Historian Data
Archive level failover for Archive-level failover requires that two source Historian Data Archives having
Historian to Historian identical tag definitions and data streams for interface points are available.
This requirement ensures that the interface will obtain the same data
regardless of which source server is active.
Failover is enabled by specifying a primary and secondary source server in the
interface startup file. On startup, the interface attempts to establish a
connection to each source server then loads and initializes its tag list. Data
collection begins from the primary source server, making it the active node
while the secondary source server assumes the standby role.
However, if one of the source servers is unavailable on startup, the other
server is designated the active source regardless of whether it is configured to
be primary or secondary. Historian to Historian server-level failover can
happen in two scenarios:

Loss of connectivity to the source Data Archive

The first failover condition occurs when the interface loses communication
with the active Historian source server. This may be the result of a temporary
network outage, shutdown of the active source server, hardware failure, and
so on. The interface does not have a way of identifying the cause of the
disconnection. A disconnection means that the interface did not receive a
response from the active source within the timeout period. The interface may
initiate a short wait then attempt to reconnect to the active source before
attempting to failover. The timeout period, pause between reconnection, and
number of reconnection attempts are all user configurable parameters.
Note: The default network timeout period is 60 seconds; however, it is not an interface configuration
parameter. The network timeout period is configured through the API configuration file, pilogin.ini.
Please refer to the API Users Manual for information on adjusting the default timeout period.

Stale data on the source Data Archive

For stale data to be detected and failover to occur, the Historian to Historian
server-level failover requires the use of two status points on the source
FactoryTalk Historian servers, one point on the primary and one point on
secondary. These status points are referred to in the FactoryTalk Historian to
Historian User Guide and appear in the Interface Configuration Utility (ICU)
as the "Source Server Interface Status Utility Tag" and the "Secondary Source
Interface Status Utility Tag". The status points can be created and configured
in one of two ways – via Performance Equations or via the Interface Status
Utility.

22 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 2 Principles of operation
Note: We strongly discourage using the ISU for the status points for the Historian to Historian
Interface. Instead, you can simply create points that impersonate the ISU points used by the
Historian to Historian failover and employ a mechanism to update those points continuously with the
"Receiving Data" digital state. This can be done using Performance Equation points. The Historian to
Historian interface expects the points to be updated on some regular frequency (e.g. every minute) to
ensure that server-level failover works correctly.

To use Performance Equations (PE), create a single PE point (yes, a single

point) with a data type of "Digital" on the primary collective member. This
point will be replicated to the secondary member. Name the point so it is
easily identifiable, for example “pitopi1_server_level_failover_point”. In the
Historian to Historian ICU configuration for server level failover, for the
primary FactoryTalk Historian source server, choose the primary PE point as
the ISU point. Then choose the secondary source server and choose the
secondary PE point as the ISU point; in this case, it will be the same point for
both.
Note: Implementing a PE scenario might be configured to limit the Historian to Historian failover to
instances where communication is lost to the source server. If your PE is not using a source
interface watchdog point as input, then that would be the case; for example, a PE that simply
updates itself on some frequency. It might not make sense to use a watchdog point from a single
interface in the PE if you have multiple interfaces running on the interface computer. One interface
might be down intentionally, which would cause source failover thrashing.

When PEs are used to emulate ISU points, make sure digital PEs are used. The
local PE schedulers on each Historian Data Archive collective node must be
used and the PE data should not be buffered between members of the
collective. The PE should have a value of “0” which represents the
“RECEIVING DATA” state and the PE can either be triggered by a source
watchdog Historian Point or not:
• An example PE with source watchdog point, scheduled to update at
some frequency that is less than 60 seconds, but no more than the
watchdog point frequency:
IF ('*' - prevevent('Watch dog point','*')) < 60 THEN 0 ELSE 1
• An example PE that acts as a simple heartbeat without using a
watchdog point: simply set the PE to a constant of "0", which
represents the "RECEIVING DATA" digital state. Schedule it to update
on some frequency, e.g., every minute.
Historian to Historian source level failover causes the Historian to Historian
Interface to read the snapshot value of the status point on the server serving
up the data. The interface reads the status point at a hard-coded frequency
that is not configurable. The interface does not connect to nor read the
snapshot on the backup source server until failover occurs.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 23

Chapter 2 Principles of operation

Receiving Server Failover Status Point (Optional)

An optional Receiving Server failover status point can be set up on the target
Historian Server. This is a digital point that contains the status of the server
level failover. Create the following digital states for the point:
RETRYING CONNECTION=0,
• PRIMARY,
• FAILOVER,
• SECONDARY,
• INTF STARTUP,
• RECOVERING HISTORY,
• INTF SCANNING,
• INTF SHUTTING DOWN,
• ACCESS DENIED,
• SRC SRV CNXT BAD,
• RCV SRV CNXT BAD

UFO Failover Considerations

In a Historian to Historian Server level failover configuration, if redundant
HistoriantoHistorian UFO instances are configured, each
HistoriantoHistorian failover instance should use a unique member of the
collective as its primary source Data Archive when configuring the server
failover.

Debugging
Set /db=7 to enable the interface to print the value it receives from the call to
get the ISU digital state.
Note: Setting this parameter may result in extraneous logging.

Failover status logging (/FST Point)

If you enable this setting, you must configure the failover status point on the
target Historian Server. This point must be manually created by the user. The
required point attributes are the following:
Attribute Value
PointSource L
PointType Digital
Compressing 0
ExcDev 0
DigitalStateSet Arbitrary, see below.

24 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 2 Principles of operation
The digital set states are:
Digital State String
0 RECONNECTING
1 PRIMARY
2 FAILOVER
3 SECONDARY
4 INTF STARTUP
5 RECOVERING HISTORY
6 INTF SCANNING
7 INTF SHUTTING DOWN
8 ACCESSRC SRV CNXT BADS DENIED
9 SRC SRV CNXT BAD
10 RCV SRV CNXT BAD

Note:
• Source tag mapping by point ID is not compatible with Historian Data Archive-level failover. This is
because there is no guarantee of a point ID match between two source Historian Data Archives
unless they are part of a FactoryTalk Historian collective.
• Historian Data Archive-level failover cannot be configured when time range history recovery (/
HRONLY) is used, since the interface does not run continuously in that mode.

For more information on configuring Source Historian Data Archive-level

failover, refer to the section Source Historian Data Archive-level failover
parameters on page 70 in this document.

Tracking interface status To track interface status, create the following digital Historian Points on the
target Data Archive:
• Internal state Historian Point
Indicates whether the interface is in startup, performing history
recovery, scanning for data, experiencing network communication
errors, denied data or point access (security permissions) or
performing shutdown operations. To enable this point using ICU, go
to the PItoPI > Debug tab, check Interface Status Tag on Receiving PI
Server, and specify the name of the Historian Point.
• Failover status Historian Point
If you enable source Historian Data Archive-level failover, you can
configure a Historian Point that tracks failover status. To configure the
point using ICU, go to the PItoPI > Source PI Server Failover tab,
check Enable failover status logging, and specify the name of the
Historian Point.
UniInt interface failover UniInt Phase 2 Failover provides support for cold, warm, or hot failover
configurations. The Historian to Historian interface only supports the warm
support
configuration. In the warm configuration, you can expect a small period of
data loss during a single point of failure transition. This failover solution
requires two copies of the interface to be installed on different interface nodes
collecting data simultaneously from a single data source. Phase 2 Failover

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 25

Chapter 2 Principles of operation
requires each interface to have access to a shared data file. Failover operation
is automatic and operates with no user interaction. Each interface
participating in failover can monitor and determine liveliness and failover
status. To assist in administering system operations, the ability to manually
trigger failover to a desired interface is also supported by Phase 2 Failover.

Loss of connectivity to Data If the interface loses its connection to the Historian Server, it logs errors and
continues running normally, attempting to restore the connection to the
Archive server. Without connection to the Historian Data Archive, the interface will
continue operating without issue. Data sent will either be lost or buffered if
buffering is being used. If the interface restarts, without disconnected startup
configured the interface will not be able to load Historian Points nor collect
data until the connection to the Data Archive is restored.

26 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 3

Installation checklist

If you are familiar with running PI data collection interface programs, this
checklist helps you get the interface running. If you are not familiar with PI
interfaces, return to this section after reading the rest of the manual in detail.
This 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. For example, you only have to configure one instance of
buffering for every interface node regardless of how many interfaces run on
that node.

Read-only and read-write Rockwell Automation provides both read-only and read-write options of
many interfaces. Due to the inherent security risks associated with writing to
interfaces the data source, Rockwell Automation recommends using the read- only
option when possible.
If you do not need to write to the data source, select the read-only version of
the interface. For more information about the read-only version of the
interface, or if you are migrating from a read-write version to a read-only
version and want to view the migration procedure, refer to the Read-Only-
Read-Write-Interfaces-FAQ.pdf in the Common
Files\Rockwell\Help\FactoryTalk Historian to Historian Interface 3.10.01
directory in the Program Files (32-bit operating system) or Program Files
(x86) (64-bit operating system) folder.
• If a read-only version is not available, disable interface updates to the
data source. For more information, refer to the section "Disable read-
write interface updates to the data source" in this document.
• If you need to write to the data source, select the read-write version of
the interface and secure your points in the following ways:
• Create an output point file that is secured so that only authorized
users can change it. For more information, refer to the PI Universal
Interface (UniInt) Framework User Guide.
• Isolate output points using a separate interface instance from the
input point interface instance.
Disable read-write Rockwell Automation recommends using the read-only option of the
interface whenever possible. If a read-only option is not available, perform the
interface updates to the
following steps to disable outputs using ICU to secure the data source.
data source

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 27

Chapter 3 Installation checklist

To disable read-write interface updates to the data source

1. Open ICU and select the interface instance.
2. On the UniInt tab, select Disable all outputs from PI.
3. Click Apply. ICU saves the configuration.

Data collection steps The data collection steps below are required.

To collect Data
1. Confirm that you can use SMT to configure Historian Data Archive.
You do not need to run SMT on the same computer on which you run
this interface.
2. If you are running the interface on an interface computer, edit the
Historian Data Archive’s Trust table to allow the interface to read
attributes and point data. If a buffering application is not running on
the interface computer, the PI trust must allow the interface to write
data.
3. Run the installation kit for the Interface Configuration Utility (ICU) on
the interface computer if the ICU will be used to configure the
interface. This kit runs the PI SDK installation kit, which installs both
the PI API and the PI SDK.
4. Run the installation kit for this interface. The kit also runs the PI SDK
installation kit which installs both the PI API and the PI SDK if
necessary.
5. If you are running the interface on an interface computer, check the
computer’s time zone properties. An improper time zone
configuration can cause the Historian Data Archive to reject the data
that this interface writes.
6. Run the ICU and configure a new instance of this interface. Essential
startup parameters for this interface are:
• Point Source (/PS=x)
• Interface ID (/ID=#)
• Historian Data Archive (/Host=host:port)
• Scan Class (/F=##:##:##,offset)
7. Use a data source-specific connection tool to confirm connection
between the interface computer and the device.
8. If you will use digital points, define the appropriate digital state sets.
9. Add the X, Y, and Z states to the system digital state set.
10. Build input tags for this interface.
PtSecurity must permit read access for the PI identity, group, or user
configured in the PI trust that is used by the interface. DataSecurity
must permit read access (buffering enabled) or read/write access

28 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 3 Installation checklist
(unbuffered) for the PI identity, group, or user configured in the PI
trust that is used by the interface.
Note: When buffering is configured, the DataSecurity attribute must permit write access for
the buffering application’s PI trust or mapping. DataSecurity write permission for the
interface’s PI trust is required only when buffering is not configured.
11. Start the interface interactively and confirm its successful connection
to the Data Archive without buffering. (The DataSecurity attribute for
interface points must permit write access for the interface’s PI trust.)
12. Confirm that the interface collects data successfully.
13. Stop the interface and configure a buffering application (either
Bufserv or PIBufss).
14. Start the buffering application and the interface. Confirm that the
interface works together with the buffering application by physically
removing the connection between the interface computer and the
Historian Data Archive computer.
Note: The DataSecurity attribute for interface points must permit write access for the
buffering application’s PI trust or mapping. The interface’s PI trust does not require
DataSecurity write permission.
15. Configure the interface to run as a Windows service. Confirm that the
interface runs properly as a service.
16. Restart the interface computer and confirm that the interface and the
buffering application restart.

Interface diagnostics Perform the following interface diagnostic procedures to implement data
gathering mechanisms on your interface.
(optional)

To implement data gathering mechanisms

1. Configure Scan Class Performance points.
2. Install the interface for Performance Monitor on the interface
computer.
3. Configure performance counter points.
4. Configure UniInt Health Monitoring points.
5. Configure the I/O Rate point.
6. Install and configure the Interface Status Utility on the Historian Data
Archive computer.
7. Configure the Interface Status point.
Advanced interface For additional information, refer to the "UniInt failover configuration
features (optional) overview" section of the PI Universal Interface (UniInt) User Guide.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 29

 Chapter 4

Installation instructions

Rockwell Automation recommends that interfaces be installed on interface

computers instead of directly on the Historian Data Archive computer. An
interface computer is any computer other than the Historian Data Archive
computer where the PI Application Programming Interface (PI API) is
installed (see the PI API manual). With this approach, the Historian Data
Archive need not compete with interfaces for the machine's resources. The
primary function of the Historian Data Archive is to archive data and to
service clients that request data.
After the interface has been installed and tested, buffering should be enabled
on the interface computer. Buffering refers to either PI API Buffer Server
(Bufserv) or the PI Buffer Subsystem (PIBufss).
In most cases, interfaces on interface computer should be installed as
automatic services. Services keep running after the user logs off. Automatic
services automatically restart when the computer is restarted, which is useful
in the event of a power failure.
The guidelines are different if an interface is installed on the Historian Data
Archive computer. In this case, the typical procedure is to install the
Historian Data Archive as an automatic service and install the interface as an
automatic service that depends on the PI Update Manager and PI Network
Manager services.
Note:
• By default, buffering is not enabled on the Historian Data Archive computer. Bufserv or PIBufss
can be enabled on the Historian Data Archive computer so that interfaces on the Historian Data
Archive computer do not need to be started and stopped in conjunction with the Historian Data
Archive.

Name conventions and In the installation procedure below, it is assumed that the name of the
interface executable is
requirements
<interface name>.exe and that the startup command file is called <interface
name>.bat (where you replace <interfacename> with the name of your actual
interface).

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 31

Chapter 4 Installation instructions

Configure the interface manually

It is customary for the user to rename the executable and the startup
command file when multiple copies of the interface are run. For example,
<interfacename>1.exe and <interfacename1>1.bat would typically be used for
instance 1, <interfacename>2.exe and <interfacename>2.BAT for instance 2,
and so on (where you replace <interfacename> with the name of your actual
interface). When an interface is run as a service, the executable and the
command file must have the same root name because the service looks for its
command-line parameters in a file that has the same root name.

Interface directories All PI interface installations use a standardized directory structure as

described below:

PIHOME directory tree

32-bit Interfaces
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\PIPC

For 64-bit operating systems, a typical pipc.ini file contains the following
lines:
[PIPC]
PIHOME=C:\Program Files(X86)\Rockwell Software\FactoryTalk
Historian\PIPC

The above lines define the root of the PIHOME directory on the C: drive. The
PIHOME directory does not need to be on the C: drive. Rockwell Automation
recommends using the paths shown above as the root PIHOME directory
name.
Note: Restrict the Windows accounts that can create or write files in the %PIHOME% folder and
subfolders.

PIHOME64 directory tree

64-bit interfaces
The [PIHOME64] directory tree is defined by a System Environmental
Variable called PIHOME64.

32 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 4 Installation instructions
A typical value for this environmental variable is C:\Program Files\PIPC\.
The above lines define the \Program Files\PIPC directory as the root of the
PIHOME64 directory tree on the C: drive. Rockwell Automation recommends
using \Program Files\PIPC as the root directory name. The PIHOME64
directory does not need to be on the C: drive.
Note: Restrict the Windows accounts that can create or write files in the %PIHOME% folder and
subfolders.

Interface installation The installation kit for the read/write version will automatically install the
interface to: PIHOME\Interfaces\<interfacename> (where <interfacename> is
directory the name of your actual interface).
Note: PIHOME is defined in the pipc.ini file.

Interface installation The interface setup program uses the services of the Microsoft Windows
Installer. Windows Installer is a standard part of Windows operating
procedure systems. To install, run the appropriate installation kit.
• Interface: <interfacename>_#.#.#.#_.exe

Silent installation To launch a silent installation, type: Setup.exe -f silent.ini.

procedure The silent.ini file is included in the interface installation kit. You can make
site-specific alterations to the file as needed. Refer to the silent.ini file for
further information and descriptions of available arguments.
Note: Please note all other modules in the interface installation kit are configured to be
installed by default.

Historian trust for interface A Historian Interface usually runs on an interface computer as a Windows
service, which is a non- interactive environment. In order for an interface to
authentication authenticate itself to a Historian Data Archive and obtain the access
permissions for proper operation, the Historian Data Archive must have a
trust that matches the connection credentials of the interface. For more
information on interface security and trusts, refer to the PI Universal Interface
(UniInt) User Guide in the installation media.

Install interface as The interface service can be created, preferably, with the Interface
Configuration Utility, or can be created manually.
Windows service
Note: For improved security, Rockwell Automation recommends running the interface service under a
non- administrative account, such as a Windows built-in service virtual account, the built-in Network
Service account, or a non-administrative account that you create.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 33

Chapter 4 Installation instructions

Install interface service Service configuration

with Interface The Interface Configuration Utility (ICU) provides a user interface for
Configuration Utility (ICU) creating, editing, and deleting the interface service. The following are
descriptions of fields in the ICU tool.
• 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.
• Display name
The Display name text box shows the current Display Name of the
interface service. If there is currently no service for the selected
interface, the default Display Name is the service name with a "PI-"
prefix. Users may specify a different Display Name. It is suggested that
the prefix "PI-" be appended to the beginning of the interface name to
indicate that the service is part of the Rockwell Automation suite of
products.
• Log on as
The Log on as box shows the current "Log on as" Windows account of
the interface service. If the service is configured to use the NT Service
account, the Log on as will have selected "NT Service." Users may
specify a different Windows account for the service to use.
Note: As a security best practice, Rockwell Automation recommends running this interface
service under a lest privileged account, such as a Windows service virtual account, the build-
in Network Service account, or a non-administrative account that you create.
ICU versions earlier than 1.4.14.x cannot create a service that runs as a
Windows built-in service virtual account or the built-in Network
Service or NT Service accounts. After ICU creates the interface service,
you can change the account with a Windows administrative tool, such
as Services on the Control Panel or the sc command-line utility.

34 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 4 Installation instructions

Note: In order to assure that PI buffering functions properly,

the user specified in the "Log on as" portion of the Service tab
must be a member of the "PI Buffering Administrators", or the
"PI Buffer Writers" user groups. A virtual service account can
be added to those local groups, just like with any local/domain
account. Failure to add a user to at least one of these user
groups could result in a failure to buffer data. For more
details, refer to the Buffering-User-Guide-EN.pdf in the Common
Files\Rockwell\Help\FactoryTalk Historian to Historian
Interface 3.10.01 directory in the Program Files (32-bit
operating system) or Program Files (x86) (64-bit operating
system) folder.

• 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.
• Confirm password
If a password is entered in the Password text box, then it must be
confirmed in the Confirm password text box.
• Dependencies
The Installed services list is a list of the services currently installed on
this machine. Services upon which this interface is dependent should
be moved into the Dependencies list using the button. For
example, if API Buffering is enabled, then Bufserv or PIBufss should be
selected from the list at the right and added to the list on the left. To
remove a service from the list of dependencies, use the button,
and the service name will be removed from the Dependencies list.
When the interface is started (as a service), the services listed in the
dependency list will be verified as running (or an attempt will be made
to start them). If the dependent service(s) cannot be started for any
reason, then the interface service will not run.
Note: Please see the Historian Log and Windows Event Logger for messages that may
indicate the cause for any service not running as expected.

Add button
To add a dependency from the list of Installed services, select the
dependency name, and click the Add button.
Remove button
To remove a selected dependency, select the service name in the
Dependencies list, and click the Remove button. The full name of the
service selected in the Installed services list is displayed below the
Installed services list box.
• Startup type

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 35

Chapter 4 Installation instructions
The Startup Type indicates whether the interface service will start
automatically or needs to be started manually on reboot.
• If the Auto option is selected, the service will be installed to start
automatically when the machine reboots.
• If the Manual option is selected, the interface service will not start
on reboot, but will require someone to manually start the service.
• If the Disabled option is selected, the service will not start at all.
Generally, interface services are set to start automatically.
• Create
The Create button adds the displayed service with the specified
Dependencies and with the specified Startup Type.
• Remove
The Remove button removes the displayed service. If the service is not
currently installed, or if the service is currently running, this button
will be grayed out.
• Start or stop service
The toolbar contains a Start button and a Stop button. If
this interface service is not currently installed, these buttons will
remain grayed out until the service is added. If this interface service is
running, the Stop button is available. If this service is not running, the
Start button is available.
The status of the interface service is indicated in the lower portion of
the ICU dialog.
• Ready - Status of the ICU
• Stopped - Status of the Interface Service
• <interfacename> - Installed - Service installed or uninstalled
Note: <interfacename> is the name of your actual interface.

Install interface service You can access help for installing the interface as a service at any time by
manually using the following command:
interfacename.exe /help

To install interface service manually

1. Open a Windows command prompt window and change the directory
to where the interfacename.exe executable is located. Consult the
following table to determine the appropriate service installation
command.
Note: In the following Windows service installation commands, you may use either a slash (/) or dash
(-) as the delimiter.

36 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 4 Installation instructions
Windows Service Installation Commands on an Interface computer or a Historian Data Archive
computer with Bufserv implemented
Manual service <interfacename>.exe /install /depend "tcpip bufserv"
Automatic service interfacename.exe /install /auto / depend "tcpip
bufserv"
Automatic service with service ID interfacename.exe /serviceid x / install /auto /depend
"tcpip bufserv"

Windows Service Installation Commands on an Interface computer or a Historian Data Archive

computer with Bufserv implemented
Manual service interfacename.exe /install /depend tcpip
Automatic service interfacename.exe /install /auto / depend tcpip

Automatic service with service ID interfacename.exe /serviceid X / install /auto /depend

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

2. Check the Services control panel to verify that the service was added
successfully.
The services control panel can be used at any time to change the
interface from an automatic service to a manual service or vice versa.
The service installation commands in this section create an interface
service that runs under a low-privilege built-in account.
On Windows 7 and Server 2012 and later, the service logs on as the
service virtual account. For earlier versions of Windows, the service
logs on as Network Service.
Note: For best security, run this interface service under an account with minimum privileges,
such as a Windows service virtual account, the built-in Network Service account, or a non-
administrative account that you create.
The services control panel can change the account that the interface
service runs under. Changing the account while the interface service is
running does not take effect until the interface service is restarted.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 37

 Chapter 5

Historian Point configuration

The Historian Point is the basic building block for controlling data flow to and
from the Historian Data Archive. A single point is configured for each
measurement value that needs to be archived.

Point attributes Point attributes are dependent upon the configuration of your interface. Use
the point attributes below to define the Historian Point configuration for the
interface, and to identify the data you wish to transfer.
UniInt provides exception reporting, while Historian Data Archive or PIBufss
provides data compression. Both are important aspects of data collection and
archiving.

Note: Refer to the PI Universal Interface (UniInt) Framework User Guide

in the installation media for information on configuring Historian
Data Archive processing for a Historian Point, as well as for detail
on point attributes that are significant to Historian Point data
collection and archiving. Additional information on Historian Point
attributes and classes is available in the PI-Data-Archive-2018-SP3-
Patch-1-System-Management-Guide-EN.pdf in the Common
Files\Rockwell\Help\FactoryTalk Historian to Historian Interface
3.10.01 directory in the Program Files (32-bit operating system) or
Program Files (x86) (64-bit operating system) folder, where you can
identify your server version and then view the topic Point classes
and attributes.

Tag (Historian Point name) The Tag attribute (or tag name) is the name for a point. There is a one-to-one
correspondence between the name of a point and the point itself. Because of
this relationship, Historian Data Archive documentation uses the terms "tag"
and "point" interchangeably.
Follow these rules for naming Historian Points:
• The name must be unique in the Historian Data Archive.
• The first character must be alphanumeric, the underscore (_), or the
percent sign (%).
• Control characters such as linefeeds or tabs are illegal.
• The following characters also are illegal: * ' ? ; { } [ ] | \ ` "

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 39

Chapter 5 Historian Point configuration

Tag length
Depending on the version of the PI API and the Historian Data Archive, this
interface supports Tag attributes whose length is at most 255 or 1023
characters. The following table indicates the maximum length of this attribute
for all the different combinations of PI API and Historian Data Archive
versions.
Supported tag length
PI API Historian Data Archive Maximum Length
1.6.0.2 or later 3.4.370.x or later 1023
1.6.0.2 or later Earlier than 3.4.370.x 255
Earlier than 1.6.0.2 3.4.370.x or later 255
Earlier than 1.6.0.2 Earlier than 3.4.370.x 255

PointSource (point source) PointSource is an identifier that associates a Historian Point with a PI
interface instance, enabling the interface to query the Historian Data Archive
for the points that it updates. This field is not case- sensitive. In the interface
(batch) startup file, the point source is specified using the /PS command-line
parameter.
The following point sources are reserved. Do not configure them for interface
instances.
Reserved point sources
Point Source Reserved By
T Totalizer Subsystem
G and @ Alarm subsystem
R Random interface
9 RampSoak interface
C Performance equations subsystem

PointType (data type) PointType specifies the data type of the point. Typically, item data types do
not need to match Historian Point data types exactly, but the data types must
be compatible. For example, integer values from a device can be sent to
floating-point or digital PI tags. Similarly, a floating-point value from the
device can be sent to integer or digital Historian Points, although the values
might be truncated.

Location1 (interface Location1 specifies the instance of the interface to which the Historian Point
belongs. The value of this attribute must match the ID configured for the
instance) interface instance. This setting plus PointSource identify the interface
instance that writes to a particular point. (/ID).

40 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 5 Historian Point configuration

Location2 (time stamp Location2 is used to specify how data time stamps are adjusted. The source
Historian Data Archive supplies a timestamp for each data event. Users have
adjustment) the option of adjusting these timestamps to account for time differences
between Historian Data Archives. It is required that each Historian Data
Archive have the correct system time for its configured time zone. See section
Data timestamps on page 20 for a complete discussion.
Valid settings are as follows:
Location2 Value Adjust for Clock Drift* Truncate Sub-second
Time stamps**
0 or 1 -- --
2 or 3 Yes --
4 or 5 -- Yes
6 or 7 Yes Yes

* Receiving Historian Data Archive is the time primary. Timestamps are

adjusted to receiving Historian Data Archive time. An offset of 30 minutes or
less is considered clock drift.
**Truncating sub-second time stamps can lead to data loss during history
recovery and archive data scanning if multiple events are stored within the
same second. Use with caution.

Location3 (status events, Location3 is used to configure how the interface handles interface status
events, snapshot data, point-level debugging, and the writing of unexpected
snapshot data, digital digital states received from the source Historian Point to the target Historian
states, and point logging) Point.
Interface status events include IO Timeout and Access Denied events. IO
Timeout status events result in a data gap for periods of Historian Data
Archive disconnection. Refer to the section Interface status events on page 20
for a complete discussion.
If a tag is configured for archive data collection, this attribute also specifies
whether or not the snapshot value is included with each scan update. Points
configured for exception collection will always include the snapshot.
For non-digital type Historian Points, if the source Historian Point contains a
SYSTEM digital state, this attribute specifies whether or not the target
Historian Point is updated with the unexpected SYSTEM digital state. For
digital type Historian Points, if the source Historian Point contains a SYSTEM
digital state or an unexpected digital state value instead of an expected value,
this attribute specifies whether or not the target Historian Point is updated
with the SYSTEM digital state or the unexpected digital state value.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 41

Chapter 5 Historian Point configuration
Location3 Write I/O Write Access Include Point-level Write SYSTEM or
Value Timeout Denied Snapshot Debugging Unexpected
(achive data Digital State
collection
points only)

0 Yes Yes Yes

1 Yes Yes
2 Yes Yes
3 Yes
4 Yes Yes Yes Yes
5 Yes Yes Yes
6 Yes Yes Yes
7 Yes Yes
8 Yes Yes Yes Yes
9 Yes Yes Yes
10 Yes Yes Yes
11 Yes Yes
12 Yes Yes Yes Yes Yes
13 Yes Yes Yes Yes
14 Yes Yes Yes Yes
15 Yes Yes Yes
16 Yes Yes
17 Yes
18 Yes
19
20 Yes Yes Yes
21 Yes Yes
22 Yes Yes
23 Yes
24 Yes Yes Yes
25 Yes Yes
26 Yes Yes
27 Yes
28 Yes Yes Yes Yes
29 Yes Yes Yes
30 Yes Yes Yes
31 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. In addition, points in the
first scan class will be configured for exception data collection. Points in all
other scan classes will be configured to collect archive data.

42 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 5 Historian Point configuration

Location5 Location5 attribute is used for setting the write mode for sending archive
data to the receiving Historian Data Archive. Data can be written to Historian
Data Archive in three modes:
1. ARCAPPEND
2. ARCREPLACE
3. ARCNOREPLACE
The following table lists and describes the supported write modes for PI3:
Location5 Write Mode Description
0 ARCAPPEND Add archive event regardless of existing
(Default) Archive and Snapshot events.
Data Default snapshot behavior is to append data if
event at timestamp exists.
1 or 3 ARCNOREPLACE Add archive event unless event(s) exist at same
Archive Events Only time.
Default snapshot behavior is to append data if
event at timestamp exists.
2 ARCREPLACE Add archive event, replace if event at same
time.
Default snapshot behavior is to append data if
event at timestamp exists.
4 ARCREPLACE Add archive or snapshot event, replace if event
Archive and Snapshot at same time.
Events
5 ARCREPLACE Add archive event, replace if event at same
Future Tags time.
Must be set for future tags.
WARNING:
• The PI Buffer Subsystem v3.4.375.38 only supports writing to the archive in ARCNOREPLACE
mode. ARCNOREPLACE mode prevents the Historian to Historian interface from honoring
Location5 archive write options and can lead to data loss. Rockwell Automation recommends
using a newer version of PI Buffer Subsystem to avoid this issue.
• By default (Location5 = 0) in-order data sent to the target server's snapshot will flow into the
archive in ARCAPPEND mode; however, Location5 can be set to override the default behavior
(Location5 = 2 or Location5 = 4) and replace data in the target Historian Data Archive. Using
the override behavior can lead to mismatches between data in the source and target Historian
Data Archives, since the default behavior on the source server is to append duplicate events.

The write order established by Location5 applies to both in-order and out-of-
order data received from the source Historian Data Archive. The write order
established by Location5 also applies to all three modes of source Historian
Data Archive data retrieval modes:
• Exception based source data retrieval for Historian Points configured
to scan class 1 (Location4 = 1).
• Archive based source data retrieval for Historian Points configured to
scan classes other than 1 (Location4 > 1).
• History recovery mode, specified using either the command line
parameter /HRONLY or by using the HISTONLY INI file setting.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 43

Chapter 5 Historian Point configuration

WARNING: In Historian to Historian, scan classes can be exception based or

archive based. If an interface point is configured with a source Historian Point
that has the potential to receive an out of order event for edit/replace/add, then
the interface point must be assigned to the exception scan class: scan class 1 for
the Historian to Historian interface. The interface point must not be assigned to
an archive based scan class. A typical example is a Historian to Historian
interface point whose source point receives laboratory data.
Note: Only one scan class in any interface copy can sign up for exceptions, the other
scan classes can obtain only archived data. By default, the scan class that signs up
for exceptions is the first scan class listed on the command line.

Exception based data retrieval mode

The exception scan class (scan class 1 for the Historian to Historian interface)
writes all source out-of-order data to the destination Historian Data Archive
using the write mode specified in Location5.

Archive based data retrieval mode

An archive based scan class (any scan class other than 1 for the Historian to
Historian interface) is not aware that source data may be out-of-order. It
simply reads data from the source archive after the data is archived. The order
in which that data arrived on the source server is irrelevant.
The Historian to Historian interface will honor Location5's ARCAPPEND and
ARCREPLACE modes on a PI3 server for duplicate events when interface
points are configured to use an archive based scan class. The Historian to
Historian interface will not honor the ARCNOREPLACE mode on a PI3 server
for interface points configured to use an archive based scan class.

History recovery mode

History recovery mode is specified using the /HRONLY command line
parameter or the Histonly INI file setting. In the history recovery mode of
operation, the interface performs Historian Data Archive reads on the source
server, typically for backfilling purposes on the target Historian Data Archive.
Scan classes are irrelevant when operating in this mode. History recovery
mode will honor all write modes (ARCAPPEND, ARCREPLACE, and
ARCNOREPLACE) for out-of-order data (relative to the target Historian Data
Archive Snapshot value) on a PI3 server.

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.

44 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 5 Historian Point configuration

Length
Depending on the version of the PI API and the Historian Data Archive, this
interface supports an InstrumentTag attribute whose length is at most 32 or
1023 characters. The following table indicates the maximum length of this
attribute for all the different combinations of PI API and Historian Data
Archive versions.
PI API Historian Data Archive Maximum Length
1.6.0.2 or later 3.4.370.x or later 1023
1.6.0.2 or later Earlier than 3.4.370.x 32
Earlier than 1.6.0.2 3.4.370.x or later 32
Earlier than 1.6.0.2 Earlier than 3.4.370.x 32

If the Historian Data Archive version is earlier than 3.4.370.x or the PI API
version is earlier than 1.6.0.2, and you want to use a maximum InstrumentTag
length of 1023, you need to enable the PI SDK. See ***PI SDK Options for
information.

Source tag name

Unless the /tn, /tnex, or /ptid interface parameter is used, the InstrumentTag
can be used to specify the name of the source tag. The ExDesc and Tag
attributes can also be used for source tag name definition (see below). The
UserInt1 attribute can be used to specify the source tag by point ID instead of
tag name. The section How the Historian to Historian Interface finds source
points on page 15 explains how the interface parameters affect which
receiving tag attributes are used for mapping to the source point and the
order that the attributes are searched for a mapping.
The interface checks the InstrumentTag attribute first. If the InstrumentTag
is empty, the extended descriptor is checked for STAG=< tagname > at the
beginning of the ExDesc value. That is, the ExDesc attribute must begin with
the 'STAG' keyword. If neither InstrumentTag nor ExDesc has a tag name, the
UserInt1 attribute is checked for the source tag point ID. Finally if none of
these three attributes identify a source point, the receiving tag name is used
for the source tag name.

ExDesc
Length
As an alternative to mapping Historian Point names, you can specify the
unique PointID of the source point in this attribute of the target point. The
advantage of this approach is that the mapping remains valid if the source
point is renamed. Due to a limitation of the PI API, if the source point name is
long than 80 characters, you must use this approach to mapping.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 45

Chapter 5 Historian Point configuration
PI API Historian Data Archive Maximum Length
1.6.0.2 or later 3.4.370.x or later 1023
1.6.0.2 or later Earlier than 3.4.370.x 80
Earlier than 1.6.0.2 3.4.370.x or later 80
Earlier than 1.6.0.2 Earlier than 3.4.370.x 80

If the Historian Data Archive version is earlier than 3.4.370.x or the PI API
version is earlier than 1.6.0.2, and you want to use a maximum ExDesc length
of 1023, you need to enable the PI SDK. Refer to PI SDK options on page 79 for
information.

Source tag name

Unless the /tn or /ptid interface parameter is used, the extended descriptor
may be used as an alternative source tag specification by using the keyword
STAG=< tag name >. Refer to the section How the Historian to Historian
Interface finds source points on page 15 in this manual for information on
how the interface parameters affect which receiving tag attributes are used
for mapping to the source point, and the order that the attributes are searched
for a mapping.
Note that the STAG keyword must be the first four characters of the Exdesc
attribute value. No spaces can precede the STAG keyword. The STAG keyword
is case insensitive. If additional information is included after the STAG
specification, the tag name must be followed with a comma or enclosed in
double quotation marks.
If the source tag name contains a comma within it, it must be enclosed in
double quotation marks. For example, STAG="batchreactor1,temp is a
legitimate way to define a source tag name.

Performance points
For UniInt-based interfaces, the extended descriptor is checked for the string
"PERFORMANCE_POINT". If this character string is found, UniInt treats this
point as a performance point.
Note: If event-based update tags are added to the interface and the interface is configured for
source Historian Server failover it may result in unexpected behavior. For example the interface may
get into a loop where it fails over after history recovery. It may print debug messages saying that
source PI status tag has value out of range (istat=0). Removing any event- based tags (ExDesc
attribute with Event=<tag>) from the interface will resolve this issue. Historian to Historian does not
support event-based updates.

SourceTag This interface does not support output tags (points that write data to the
point source).

46 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 5 Historian Point configuration

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
log and the point is not loaded by the interface. There is one exception to the
previous statement.
If any Historian Point is removed from the interface while the interface is
running (including setting the Scan attribute to 0), SCAN OFF will be written
to the Historian Point regardless of the value of the Scan attribute. Two
examples of actions that would remove a PI point from an interface are to
change the point source or set the Scan attribute to 0. If an interface-specific
attribute is changed that causes the point to be rejected by the interface,
SCAN OFF will be written to the Historian Point.

Shutdown The Shutdown attribute is 1 (true) by default. The default behavior of the PI
Shutdown Subsystem is to write the SHUTDOWN digital state to all
Historian Points when Historian is started. The timestamp that is used for the
SHUTDOWN events is retrieved from a file that is updated by the Snapshot
Subsystem. The timestamp is usually updated every 15 minutes, which means
that the timestamp for the SHUTDOWN events will be accurate to within 15
minutes in the event of a power failure. For additional information on
shutdown events, refer to Historian Data Archive manuals.
Note: The SHUTDOWN events that are written by the PI Shutdown Subsystem are independent of the
SHUTDOWN events that are written by the interface when the following command-line parameter is
specified:
/stopstat=Shutdown

SHUTDOWN events can be disabled from being written to Historian Points

when the Historian Data Archive is restarted by setting the Shutdown
attribute to 0 for each point. Alternatively, the default behavior of the PI
Shutdown Subsystem can be changed to write SHUTDOWN events only for
Historian points that have their Shutdown attribute set to 0. To change the
default behavior, edit the Shutdown.dat file, as discussed in the Historian
Data Archive manuals.

Bufserv and PIBufss It is undesirable to write shutdown events when buffering is being used.
Bufserv and PIBufss are utility programs that provide the capability to store
and forward events to a Historian Data Archive, allowing continuous data
collection when the Historian Data Archive is down for maintenance,
upgrades, backups and unexpected failures. That is, when the Historian Data
Archive is shutdown, Bufserv or PIBufss will continue to collect data for the
interface, making it undesirable to write SHUTDOWN events to the PI points
for this interface. Disabling Shutdown is recommended when sending data to
a Highly Available Historian Data Archive collective. Refer to the Bufserv or
PIBufss manuals for additional information.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 47

Chapter 5 Historian Point configuration

DataSecurity The PI identity in the PI trust that authenticates the interface must be
granted read access to the DataSecurity attribute of every Historian Point
that the interface services. If the interface is used without a buffering
application, write access also must be granted. (If the interface is used with a
buffering application, the buffering application requires write access but the
interface does not.)

PtSecurity The PI identity in the PI trust that authenticates the interface must be
granted read access to the PtSecurity attribute of every Historian Point that
the interface services.

ExcMax ExcMin and ExcDev Exception reporting enables you to capture the minimum amount of data
required to meaningfully represent a trend. The following parameters
(exception processing) configure exception reporting in the Historian interface.
• ExcMax: The maximum time period allowed between sending values
to the Historian Data Archive.
• ExcMin: The minimum time period between values sent to the
Historian Data Archive.
• ExcDev: The minimum change from the last value sent to the
Historian Data Archive required for the interface to send a new value.
Exception processing is not performed for queries that include Historian
annotations: all data retrieved by such queries is archived.
To further filter the amount of data that is captured, you can configure a tag's
compression settings so that only meaningful deviations are archived. For
more information about exception processing and compression, see the PI
Universal Interface (UniInt) Framework User Guide in the installation media.

Interface status digital The following procedure describes how to create and configure interface
status points. Create these status points on the receiving Historian server.
point configuration
First create digital state sets for the status points. The following tables display
the digital state set definitions:
• Digital states for the Internal Status point digital state set:
Digital State String
0 STARTUP
1 HISTORYRECOVERY
2 SCANNING
3 SHUTDOWN
4 ACCESSDENIED
5 SRCDISCONNECT
6 RCVDISCONNECT

• Digital states for the Failover Status point digital state set:
Digital State String Description of use by the interface

48 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 5 Historian Point configuration

0 RECONNECTING If the interface is not connected to the source

server and is configured to have at least one
source connect retry (command line parameter
/NT=x where x is at least 1), this status will be
written to the failover status point.
The interface will then attempt to reconnect to
the source server x times before it attempts
failover to the other source server.
1 PRIMARY Written after a successful failover to the primary
source server.
2 FAILOVER Written as one of the first things the interface
does before initializing a failover.
3 SECONDARY Written after a successful failover to the
secondary source server.

TPointSourcehen create a digital point on the receiving Historian server with

the following attributes:
Attribute Value
PointSource L
PointType Digital
Compressing 0
ExcDev 0
DigitalStateSet As defined in the receiving PI3 server digital
state database. In this case, use either the
name of the digital state set you created for
Internal status or for Failover status -
depending on which interface status point you
are creating.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 49

 Chapter 6

Startup command file

Command-line parameters can begin with a forward slash ( /)or with a dash ( -
). For example, the /ps=M and -ps=M command-line parameters are
equivalent.

Configure the interface with Note: ICU requires PI 3.3 or later.

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

To configure the interface with ICU

1. Go to Start > All Programs > Rockwell Software > FactoryTalk
Historian SE > Interface Configuration Utility. The Interface
Configuration Utility dialog box appears.
2. On the Interface menu, click New Windows Interface Instance from
EXE. The following window opens:

3. Browse to the FTPItoPI.exe executable file. Then, enter values for Host
PI Server/Collective, Point Source, and Interface ID#. Interface name
as displayed in the ICU (optional) will have PI- added as a prefix to this
name and it will be the display name in the services menu. The

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 51

Chapter 6 Startup command file
Interface ID # specifies the integer ID of the interface instance and
should match the Service ID, and be unique for each instance of the
interface installed on the local node.
4. Click Add. The following message displays:

Note: In this example the host PI Server is S10WIN2016DC. To configure the interface to
communicate with a remote PI Server, select Connections on the ICU Interface menu
and select the default server. If the remote node is not present in the list of servers, it
can be added.
5. Once the interface is added to ICU, near the top of the main ICU
window, the interface Type should be PItoPI. If not, use the drop-
down box to change the interface Type to PItoPI.
6. Click Apply to enable the ICU to manage this instance of the Historian
To Historian interface.

7. Make selections in the interface-specific page (that is, "PItoPI ") that
allows you to enter values for the startup parameters that are
particular to the Historian to Historian interface. Since the Historian
to Historian interface is a UniInt-based interface, in some cases you
will need to make appropriate selections in the UniInt page, which
configures UniInt features through the ICU.
To set up the interface as a Windows service, use the Service page. This
page allows configuration of the interface to run as a service as well as
starting and stopping of the interface service. The interface can also be
run interactively from the ICU. To do that, select Start Interactive on
the Interface menu.
For more detailed information on how to use the above-mentioned
and other ICU pages and selections, please refer to the Historian

52 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 6 Startup command file
Interface Configuration Utility user guide. The next section describes
the selections that are available from the PItoPI page. Once selections
have been made on the ICU window, press the Apply button in order
for ICU to make these changes to the interface's startup file.
Historian to Historian Since the startup file of the Historian to Historian interface is maintained
automatically by the ICU, use the PItoPI selection that appears below General
Interface
in the left hand pane of the ICU window to configure the startup parameters
and do not make changes in the file manually. The following topics describe
the Historian to Historian interface configuration parameters available in the
General and PItoPI portions of the ICU Control for the Historian to Historian
interface, along with the corresponding manual parameters.

Historian to Historian The Historian to Historian ICU Control for ICU has seven tabs. A yellow text
box indicates that an invalid value has been entered or that a required value
General: scan classes, host has not been entered.
information and interface
installation path

Click PItoPI below General in the left hand pane to begin configuring the
seven tabs of the ICU Control.

Required tab When All Scan Classes is selected in the Settings for list, the first tab will be
titled Required. This is because the information provided in this first tab is
required when selecting configuration for all scan classes, but not for each

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 53

Chapter 6 Startup command file
scan class. When a particular scan class is selected, the first tab will be titled
General.

Required Parameters - Source host

The Source host is the name of the source Historian Data Archive from which
this Historian to Historian interface is to get its data. (command line
parameter /SRC_HOST=hostname).

Required Parameters - Event counter

The Event counter can only be configured for a particular scan class, so the
Event counter box will remain disabled unless a scan class is selected in the
Settings for combo box. (command line parameter /EC=x).

Additional Parameters
This Additional Parameters box is provided for any additional parameters
that the current ICU Control does not support.

History Recovery tab

54 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 6 Startup command file

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. (command line parameter /RH= hours)
The Use Default button is used to reset the value to the default setting of 8 in
the Maximum hours of history to recover box.

Hours of history to recover per cycle

This is the number of hours of history to recover in each cycle through the
point list. If the number of hours specified in the Hours of history to recover
per cycle box is greater than or equal to the hours of history recovery
requested in the Maximum hours of history to recover box, history will be
recovered in one archive call from *- Hours of history to recover per cycle
hours to *. If then number in the Maximum hours of history to recover box is
greater than the number in the Hours of history to recover per cycle box, the
archive calls to retrieve history will be divided into N calls, where N =
Maximum hours of history to recover / Hours of history to recover per cycle +
1. The calls, which start from
*-Maximum hours of history to recover, will each span Hours of history to
recover per cycle hours. Each history increment is collected for all tags in the
given scan class before the next time increment is begun. If this field is set to
zero, the default 24 hours will be used. (command line parameter /RH_INC=
hours)

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 55

Chapter 6 Startup command file
The Use Default button is used to reset the value to the default setting of 24
hours for the number in the Hours of history to recover per cycle box.

Millisecond pause between history calls

The number of milliseconds to pause between history recovery calls.
(command line parameter /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. This box must be checked if you want to
enable the Time Range History Recovery controls and enter a History time
range. (command line parameter /HRONLY)

History time range (dd-mmm-yy:hh:mm:ss,dd-mmm-yy:hh:mm:ss)

If the Time Range History Recovery controls are enabled, you can specify a
range of history to recover. The interface will exit after history recovery
completes. The times must be specified using Historian time string formats
with a colon separating the date and the time. For example:
10-dec-98:10:00:00,10-dec-98:12:00:00

Note: These times are local to where the interface runs.

The example above will recover two hours of data from the source to receiving
system; put it into the receiving PI system snapshot for all points and then
exit. This switch will override the normal checking for the most recent
snapshot time in the receiving database, thus out of order data may result.
When time-range history recovery is enabled, the value specified by the /RH
parameter is overridden. (command line parameter /HRONLY=dd-mmm-
yy:hh:mm:ss,dd- mmm-yy:hh:mm:ss)

Start history recovery beginning with the first value prior to the start
time
If the Time Range History Recovery controls are enabled, you can check the
Start history recovery beginning with the first value prior to the start time box
to retrieve history for all the points starting from the value immediately prior

56 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 6 Startup command file
to the start time. The default is to begin with the first value after the start
time. (command line parameter /NS)

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. (command line
parameter /DB= #,#,#,# ... )

Interface Status Tag on Receiving Historian Server:

This is the name of an interface status tag configured on receiving server.
Click the Browse button to browse the point database for this interface status
tag using the Tag Search utility. (command line parameter /IST= tagname )

Location tab

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 57

Chapter 6 Startup command file
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. ( command line
parameter /C1)

Override Location 2
Ignore Location2 for each tag and set Location2 value to be this number for all
interface tags. (command line parameter /C2= x)

Override Location 3
Ignore Location3 for each tag and set Location3 value to be this number for all
interface tags. (command line parameter /C3= x)

Override Location 4
Ignore Location4 for each tag. The value used here should be 1, to have all
points for the interface sign up for exceptions, or 2, to have all points retrieve
history only. (command line parameter /C4= x)

58 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 6 Startup command file

Override Location 5
Ignore Location5 for each tag and set all points for the interface to the same
value of this parameter (i.e., 0, 1, 2, 3, 4, or 5). (command line parameter /C5=x)

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. (command line parameter /DC)

Source tag definition attribute.

Use TagName on both (Ignoring ExDesc and InstrumentTag point attributes).
Do not check the InstrumentTag, ExDesc, or UserInt1 attributes for source tag
definitions. Use TagName to identify the point on both source and receiving
Historian Data Archives. (command line parameter /TN)
Use ExDesc or TagName (ignoring the InstrumentTag point attribute). The
source tag definition will be found in the ExDesc or TagName attribute.
Ignore the InstrumentTag and UserInt1 attributes. (command line parameter
/TNEX)
Use UserInt1 (ignoring the ExDesc and InstrumentTag point attributes). The
source tag definition will be found in the UserInt1 attribute. Ignore the

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 59

Chapter 6 Startup command file
ExDesc, InstrumentTag, and Tag point attributes. (command line parameter
/PTID)
The section How the Historian to Historian Interface finds source points on
page 15 explains how the interface parameters affect which receiving tag
attributes are used for mapping to the source point and the order that the
attributes are searched for a mapping.

Specify maximum events to retrieve for a single point in each call to

get history.
This parameter is available for PI 3.3 or higher 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. (command line
parameter /MH= x, which has a default value of 1000 events)

Specify maximum number of exception events retrieved per data

request.
This parameter sets the maximum number of exceptions events retrieved per
data request. A large count reduces the number of calls required for acquiring
exception updates. A small count reduces the time to complete each request
(for troubleshooting network timeout issues). (command line parameter
/ME= x, which has a default value of 5000 exception events)

Set time interval between clearing exception queue during history

recovery.
This parameter sets the time interval between clearing the exception queue on
the source Historian Data Archive for exception data scan classes. By default
the interface will collect exceptions from the source Historian Data Archive
every 5 seconds during history recovery to prevent overflowing the queue.
Users may want to adjust this time interval to tune history recovery
performance. (command line parameter /RH_QCKECK= x, which has a
default value of 5 seconds)

60 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 6 Startup command file

Specify the frequency that the interface calculates time offset

between FactoryTalk Historian Servers.
This parameter sets the frequency in seconds at which the interface will
calculate time offsets between Historian Data Archives. By default the
interface will calculate time offsets every 30 seconds. (command line
parameter /OC= x, which has a default value of 30 seconds)

Opt Cont tab

Source Host reconnection delay.

This parameter sets the time delay for attempting to reconnect to source
Historian Data Archive 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. (command line parameter
/DELAYS= x, which has a default value of 0 seconds)

Receiving Host reconnection delay.

This parameter set the time delay for attempting to reconnect to receiving
Historian Data Archive 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. (command line parameter
/DELAYR= x, which has a default value of 0 seconds)

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 61

Chapter 6 Startup command file

Suppress writing I/O Timeout to tags upon reestablishment of a lost

connection to the source server
In case you have inadvertently set Location3 to write the I/O Timeout digital
state for tags used by the Historian to Historian interface, use this parameter
to suppress writing the I/O Timeout state upon reestablishment of a lost
connection to the source Historian Data Archive.

WARNING: If this parameter is not set, the I/O Timeout state written at reconnection will prevent
history from being recovered for the period of the disconnection. (command line parameter /TS)

Future Data Collection Period

When using future tags, use this parameter to set how far into the future the
interface will search for data each scan. If this parameter is not set, the
interface will only scan for data between the time of the last scan and the
current time. (command line parameter /FD, which has a default value of 0
seconds)

Source PI 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.

62 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 6 Startup command file

Source Server Interface Status Utility Tag

This is the name of the status tag configured on the source server defined in
the command line parameter /SRC_HOST=hostname. Click the Browse
button to invoke the Tag Search utility to browse for this tag. (/SSU1=
tagname)

Secondary Source Server Node Name

This is the name of the second source node from which to retrieve data. This
must be a PI 3.x Historian Data Archive node because the port number of 5450
will be appended to the end of this name when it is saved in the batch file.
(command line parameter /SEC_SRC=nodename:5450)

Secondary Source Int Status Utility Tag

This is the name of the status tag configured on the source server defined in
the command line parameter /SEC_SRC=hostname. Click the Browse button
to invoke the Tag Search utility to browse for this tag. (/SSU2= tagname)

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.
(command line parameter /NT=x)

Enable failover status logging

This check box is used to enable failover status logging. By checking this box,
the user is allowed to enter a Receiving Server Status Tag. This entered in this
text box is the failover status tag configured on receiving server. Click the
Browse button to invoke the Tag Search utility to browse for this tag.
(command line parameter /FST=tagname)

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 63

 Chapter 7

Command line parameters

The following table lists the interface-specific command line parameters used
in the interface startup batch file to configure settings. These parameters are
provided for debugging purposes to help you read the file. To ensure a
correctly-formatted file, use the Interface Configuration Utility to configure
the interface.
In addition to interface specific parameters, all UniInt interfaces support a
common set of parameters. For details, refer to the PI Universal Interface
(UniInt) User Guide.

General interface operation .BAT

/db=#
Description
/db=1 : Max debug
parameters Optional /db=2 : Startup processing
INI File Setting: DebugFlags /db=3 : Historian Data Archive connections
/db=4 : Historian Data Archive 2.x security validation
(obsolete)
/db=5 : Historian Point additions, edits, deletions
/db=6 : Data reads & writes
/db=7 : Failover
Example: /db=2,4,5
/delayr=# Millisecond time delay between reconnection attempts to
Optional the target Historian Data Archive. Units are in milliseconds.
Default: /delayr=0 Valid values are between 0 and 28800000ms (8 hours).
/delays=# Millisecond time delay between re-connection attempts to
Optional the source Historian Data Archive. Valid values are between
Default: /delays=0 0 and 28800000ms (8 hours).

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 65

Chapter 7 Command line parameters

/f=SS.## The /f parameter defines the time period between scans in

or terms of hours (HH), minutes (MM), seconds (SS) and sub-
/f=SS.##,ss.## seconds (##). The scans can be scheduled to occur at
or discrete moments in time with an optional time offset
/f=HH:MM:SS.## specified in terms of hours (hh), minutes (mm), seconds (ss),
and sub-seconds (##). If HH and MM are omitted, then the
or
time period that is specified is assumed to be in seconds.
/f=HH:MM:SS.##,
Each instance of the /f parameter on the command-line
hh:mm:ss.##
defines a scan class for the interface. There is no limit to
Required
the number of scan classes that can be defined. The first
occurrence of the /f parameter on the command-line
defines the first scan class of the interface; the second
occurrence defines the second scan class, and so on.
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.
Two scan classes are defined in the following example:
/f=00:01:00,00:00:05 /f=00:00:07
or, equivalently:
/f=60,5 /f=7
The first scan class has a scanning frequency of 1 minute
with an offset of 5 seconds, and the second scan class has a
scanning frequency of 7 seconds. When an offset is
specified, the scans occur at discrete moments in time
according to the formula:
scan times = (reference time) + n(frequency) + offset
where n is an integer, and the reference time is midnight on
the day that the interface was started. In the above example,
frequency is 60 seconds and offset is 5 seconds for the first
scan class. This means that if the interface were started at
05:06:06, the first scan would be at 05:07:05, the second
scan would be at 05:08:05, and so on. Since no offset is
specified for the second scan class, the absolute scan times
are undefined.
The definition of a scan class does not guarantee that the
associated points will be scanned at the given frequency. If
the interface is under a large load, then some scans may
occur late or be skipped entirely. See the section
"Performance Summaries" in the PI Universal Interface
(UniInt) User Guide for more information on skipped or
missed scans.
Sub-second Scan Classes
Sub-second scan classes can be defined on the command-
line, such as
/f=0.5 /f=00:00:00.1
where the scanning frequency associated with the first scan
class is
0.5 seconds and the scanning frequency associated with the
second scan class is 0.1 of a second.
Similarly, sub-second scan classes with sub-second offsets
can be defined, such as

66 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 7 Command line parameters

/f=0.5,0.2 /f=1,0
Wall Clock Scheduling
Scan classes that strictly adhere to wall clock scheduling are
now possible. This feature is available for interfaces that run
on Windows and/or UNIX. Previously, wall clock scheduling
was possible, but not across daylight saving time. For
example, /f=24:00:00,08:00:00 corresponds to 1 scan a day
starting at 8 AM. However, after a Daylight Saving Time
change, the scan would occur either at 7 AM or 9 AM,
depending upon the direction of the time shift. To schedule
a scan once a day at 8 AM (even across daylight saving time),
use / f=24:00:00,00:08:00, L. The, L at the end of the scan
class tells UniInt to use the new wall clock scheduling
algorithm.
/id=x The /id parameter is used to specify the interface identifier.
Required The interface identifier is a string that is no longer than 9
characters in length. UniInt concatenates this string to the
header that is used to identify error messages as belonging
to a particular interface. Refer to Error and informational
messages from the Historian to Historian Interface on page
77 for more information. The /id parameter corresponds to
the Location1 point attribute to determine tags loaded for an
interface instance.
/ist=tagname Name of interface status point.
Optional /ist=<tagname>
tagname is a digital point on the target Historian Data
Archive.
/oc=# Number of seconds between calculating time offset between
Optional Default: /oc=30 the interface and Historian Data Archive nodes.
/omf_clear Clears the entries in the Windows Credential Manager for the
corresponding service name and the Run-As account. To
activate it, perform the following actions:
1. Stop the interface.
2. Add the /omf_clear command line option through the
Additional Parameters input in ICU.
3. Start the interface.
4. Update the service-name.config file that is in the same
directory as the interface executable, providing the
desired username/password, or clientid/clientsecret,
and restart the interface.
Note: This parameter is only recognized when the interface
is started as a service. After it finishes clearing the entries
in the Windows Credential Manager, the interface service
stops.
/ps=x The /ps parameter specifies the point source for the
Required interface. X is not case sensitive and can be any single or
multiple character string. For example, /ps-P and ps=p are
equivalent.
/src_host=name:5450 Name or Historian address of source Historian Data Archive.
Required /src_host=node_name:tcpip_port
INI File Setting: SourceHost The port number is always 5450.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 67

Chapter 7 Command line parameters

/stopstat= digstate If /stopstat=digstate is present on the command line, then

or the digital state, digstate, will be written to each Historian
/stopstat Point when the interface is stopped. For a Historian Data
Archive 3.x server, digstate must be in the system digital
Optional state table. UniInt will use the first occurrence of digstate
found in the table.
Default: no digital state written at
shutdown. If the /stopstat parameter is present on the startup
command line without a digital state, then the digital state
Intf Shut will be written to each Historian point when the
interface is stopped.
If neither /stopstat nor /stopstat=digstate is specified on
the command line, then no digital state will be written when
the interface is shut down.
The /stopstat parameter is disabled if the interface is
running in a UniInt failover configuration. The digital state,
digstate, is not written to each Historian Point when the
interface is stopped, to prevent the digital state being
written to Historian Points while a redundant system is also
writing data to the same Historian Points. The /stopstat
parameter is disabled even if there is only one interface
active in the failover configuration.
Examples:
/stopstat=shutdown
/stopstat="Intf Shut"
The entire digstate value must be enclosed within double
quotes when there is a space in digstate.
/ts Suppress IO Timeout events when reconnecting to source
Optional Historian Data Archive. These events are configured through
the Location3 attribute.
If this switch is not set, the event written at reconnection
will prevent history from being recovered for the period of
the disconnection.

History recovery and Parameter

/dc
Description
Apply exception specifications to history recovery and
archive data collection Optional archive scan updates.

parameters /fd=#(Unit) Optional Default: For future tags, sets how far into the future the interface
/fd=0s should search for data. Available units are seconds (s),
minutes (m), hours (h), days (d), months (M), and years (y).
Only a single unit can be used. Units are case-sensitive.
For example, /fd=30d would mean that each scan, the
interface searches for values between the time of the last
scan and the current time + 30 days.
By default, the interface does not search into the future.
Note: 1M=30d and 1y=365d.

68 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 7 Command line parameters

/hronly [=<start,end>] Optional INI Specifies the time range to be recovered. The interface
File Setting: HistOnly recovers data for the specified period, then exits. To disable
exception data collection, omit time period.
Specify the times using Historian time string formats with a
colon or underscore separating the date and the time:
/hronly=dd-mmm-yy:hh:mm:ss,dd-mmm-yy:hh:mm:ss
or

/hronly=dd-mmm-yy_hh:mm:ss,dd-
mmm-yy_hh:mm:ss For example:
/hronly=10-dec-98:10:00,10-
dec-98:12:00
or
/hronly=10-dec-98_10:00,10-dec-98_12:00
Time stamps should use the interface node's local time.
Note: Historian Data Archive-level failover cannot be
configured when /hronly is used.
/hrpause=# Milliseconds to pause between points during history
Optional recovery. Used to throttle archive data retrieval during
INI File Setting: HistPause history recovery.
Default: /hrpause=0
/mh=x Supported for target Historian Data Archive version 3.3 or
Optional later.
Default: /mh=1000 Minimum: Sets the maximum number of archive events retrieved per
/mh=1 Maximum: /mh=10000 data request. If more than the maximum exist, the interface
makes multiple calls until all events are retrieved for the
time period. Increasing the maximum can increase data
throughput for archive data retrieval.
/ns Start history recovery beginning with the first value prior to
Optional the start time. By default, recovery begins with the first
value after the start time.
/rh=# Hours of history recovery to perform. No maximum is
Optional INI File Setting: enforced, but be sure you have sufficient disk space for the
HistRecovery archive files on the target server computer.
Default: /rh=8
/rh_inc=# Time increments within the total /rhrecovery period.
Optional For example, if /rh=48 and /rh_inc=24, the interface cycles
INI File Setting: MaxArcTimespan through the point list twice. On the first cycle, the first 24-
Default: /rh_inc=24 hour period is recovered. On the second cycle, the second
24- hour period is recovered.
/rh_qcheck=# For exception data scan classes, specify how often to clear
Optional the exception queue on the source Historian Data Archive
Default: /rh_qcheck=5 during history recovery.
To prevent queue overflow, the interface periodically
collects exceptions from the source Historian Data Archive
during history recovery. You can adjust this time interval to
tune history recovery performance.
/me=# Sets the maximum number of exception events retrieved
Optional per data request. A large count reduces the number of calls
Default: /me=5000 required to read exception updates. A small count reduces
the time to complete each request (for troubleshooting
network timeout issues).

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 69

Chapter 7 Command line parameters

/sn Disable exception filtering for data collected from the

Optional source Historian Data Archive. This data has already passed
exception for the source tag. Additional data filtering can
lead to data mismatches between Historian Data Archives.

Point attribute override Parameter

/c1
Description
Location1 point attribute override.
parameters Optional Load all points configured for the specified point
source regardless of Location1 and interface ID values.
/c2=# Location2 point attribute override.
Optional Ignore Location2 for each point and use the specified
value. Valid values are 0-7.
/c3=# Location3 point attribute override.
Optional Ignore Location3 for each point and use the specified
value. Valid values are 0-31.
/c4=# Location4 point attribute override.
Optional Ignore Location4 for each point and use the specified
value. Valid values are 1 (exception data collection) or 2
(archive data collection).
/c5=# Location5 point attribute override.
Optional Ignore Location5 for each point and use the specified
value. Valid values are 0-5.
/ptid Point ID of source Historian Point is specified in
Optional UserInt1 attribute. Ignore InstrumentTag, ExDesc, and
Tag (Historian Point name) attributes.
Note: This switch is not compatible with source
Historian Data Archive failover because point IDs will
not necessarily match between source Historian Data
Archives. If the source Historian Data Archives are part
of a Historian collective use /tn instead.
/tn Source point name is same as interface point name.
Optional Ignore InstrumentTag, ExDesc, and UserInt1 attributes.
/tnex Source point name is located in the ExDesc or Tag
Optional attribute and the InstrumentTag and UserInt1
attributes are ignored for identifying source point.

Source Historian Data Parameter

/fst=tagname
Description
Name of failover status point.
Archive-level failover Optional /fst=<tagname>
where tagname is a digital point on the target Historian Data
parameters Archive.
/nt=# Optional Default: /nt=1 Number of re-connection attempts to source Historian Data
Archive before initiating a failover. Valid values are 0 and
greater.
Prevents failover flip-flop when experiencing intermittent
network updates.
/sec_src=node:5450 Name or Historian address of the secondary source Historian
Required Data Archive.
/sec_src=node_name:5450.
The port number is 5450 for Historian Data Archive 3.x.

70 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 7 Command line parameters

/ssu1=tagname Name of status tag for the /src_host source Historian Data
Required Archive.
/ssu1=<tagname>
Required for monitoring source data quality (current or stale
data).
/ssu2=tagname Name of status tag for the / sec_src source Historian Data
Required Archive.
/ssu2= <tagname>
Required for monitoring source data quality (current or stale
data).

Sample PItoPI.bat file The following is an example file:

REM===========================================================
====
REM
REM PItoPI.bat
REM
REM Sample startup file for the Historian to Historian Interface
REM
REM===========================================================
====
REM
REM Rockwell Automation strongly recommends using ICU to modify startup
files.
REM
REM Sample command line
REM
.\PItoPI.exe ^
/host=XXXXXX:5450 ^
/src_host=XXXXXX:5450 ^
/ps=PItoPI ^
/id=1 ^
/f=10
REM End of PItoPI.bat File

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 71

Chapter 7 Command line parameters

Sample PItoPI configuration

;---------------------------------------------------------
---------
file ; Purpose:
; This file is used in conjunction with PItoPI.bat. It
is only
; required to collect data from multiple source
; servers using a single copy of the interface.
;
; the headings read [PItoPI-x.y] where;
; x = interface id
; y = scan class (if specified)
;---------------------------------------------------------
---------
;
[PItoPI-1]
;EventCounter=1
;MaxArcTimespan=24
;
[PItoPI-1.1]
;SourceHost=XXXXXX:5450
;HistRecovery=48
;
[PItoPI-1.2]
;SourceHost=XXXXXX:5450
;HistRecovery=72
;
;---------------------------------------------------------
----------
; List of possible parameters
;
;SourceHost=XXXXXX:5450 Name of source Historian Data
Archive,
; port=5450 for Historian Data Archive 3.x
;ReceivingHost=XXXXXX:5450 Name of the target Historian
Data Archive,
; port=5450 for Historian Data Archive 3.x
;EventCounter=# Number of event counter defined in
; \dat\iorates.dat file
;HistRecovery=# total hours of history recovery,
default=8hrs

72 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Chapter 7 Command line parameters
;MaxArcTimespan=# history recovery increment, divided into
total
; hours of history recovery (HistRecovery),
; default=24hrs
;HistPause=# pause between history recovery
increments in
; milliseconds
;HistOnly=# flag to disable exception data collection
; (0=off, 1=on)
;DebugFlags=#,#,#,#... Generates additional messages for
troubleshooting
; comma separated list: 1,2,3,4,5,6,7

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 73

 Chapter 8

Specific considerations for Historian to

Historian Interface

Push/pull configuration Refer to Knowledgebase Document ID: QA61545 - SE to SE Interface - is it

better to push or pull the data? for recommendations for Push vs Pull
configuration, the best configurations from performance and security
standpoints.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 75

 Chapter 9

Error and informational messages from the

Historian to Historian Interface

A string Name id is added as a prefix to error messages written to the message

log. Name is a non-configurable identifier that is no longer than nine
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.
For more information about logs for interfaces running on Windows, see REF
UniIntMessageLogging \* MERGEFORMAT UniInt Interface Message
Logging for UniInt 4.5.0.x and later Interfaces.
Messages are written to the log file at the following times:
• When the interface starts, many informational messages are written to
the log. These messages include the version of the interface, the
version of UniInt, the command-line parameters used, and the
number of points.
• As the interface loads points, messages are sent to the log if there are
any problems with the configuration of the points.
• If the UniInt /dbUniInt parameter is found in the command-line, then
various informational messages are written to the log file.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 77

 Chapter 10

PI SDK options

To access the PI SDK settings for this interface, select this interface from the
Interface list and click UniInt - PI SDK in the Parameter Category pane.

Option Description
Disable PI SDK Select this option to set the interface not to use the
PI SDK. The command line equivalent for this option
is /PISDK=0.
Use the Interface's default This option does not determine whether the
setting interface uses the PI SDK.
Enable PI SDK Select this option to set the interface to use the PI
SDK. Choose this option if the Historian Data
Archive version is earlier than 3.4.370.x or the PI API
is earlier than 1.6.0.2, and you want to use extended
lengths for the Tag, Descriptor, ExDesc,
InstrumentTag, or PointSource point attributes.

The maximum lengths for these attributes are:

Attribute Enable the Interface to Historian Data Archive earlier
use the PI SDK than
3.4.370.x or PI API earlier
than 1.6.0.2, without the use
of the PI SDK

Tag 1023 255

Descriptor 1023 26
ExDesc 1023 80
InstrumentTag 1023 32
PointSource 1023 1

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 79

 Glossary
This glossary defines technical terms related to PI interfaces and related
products.
B - H on page 81
I - N on page 82

P on page 83
S - T on page 85

B-H
-B-

Buffering
n. In the Historian System, buffering is implemented as a service that stores
and forwards events to a Historian Data Archive server or collective. When the
server or collective is unavailable for any reason, the buffering service
temporarily stores the data from Historian System applications running on
the buffered computer. When the connection with Historian Data Archive is
restored, the buffering service sends all the stored data from the buffer to
Historian Data Archive in chronological order.

-H-

Historian Data Archive

n. The Rockwell Automation product that stores time-series data from
distributed data sources and serves this data to client applications in real-
time. A major component of Historian Server along with FactoryTalk
Historian Asset Framework (AF).

Historian Data Archive collective

n. A configuration of multiple servers that act as a logical Historian Data
Archive server in your Historian System to provide high availability (HA),
disaster recovery, load distribution, and increased scalability. Each server in a
collective is called a member of the collective.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 81

Glossary

Historian Data Archive computer

n. A computer hosting Historian Data Archive software.

Historian Point
n. A single data stream stored by Historian Data Archive. For example, a
Historian Point might store the flow rate from a meter, a controller's mode of
operation, the batch number of a product, text comments from an operator,
or the results of a calculation.

Historian Point attribute

n. A collection of characteristics or parameters for a Historian Point that
provides information to specify how an interface and Historian Data Archive
collect and process data values.

I-N
-I-

ICU
The acronym for Interface Configuration Utility.

ICU Control
n. A plug-in to the Interface Configuration Utility. Whereas the ICU handles
functionality common to all interfaces, an ICU Control implements interface-
specific behavior. Most Historian interfaces have an associated ICU Control.

Interface Configuration Utility

n. A Rockwell Automation application that is generally installed on a PI
interface node to manage interfaces and their configuration files. Also known
by the acronym ICU.

82 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Glossary

-M-

Message log
n. A log file that contains messages that PI Message Subsystem records. Use to
troubleshoot components that write to PI Message Subsystem, such as
Historian Data Archive, client applications, or interfaces. View the log file
with Historian SMT, the pigetmsg utility, or the PI SDK utility.

-N-

N-way buffering
n. A configuration used when buffering data to a Historian Data Archive
collective. With n-way buffering, the buffering service sends the same data to
each collective member. Of the two buffering services, Rockwell Automation
recommends PI Buffer Subsystem (pibufss) for most buffering scenarios,
including n-way buffering. PI Buffer Subsystem automatically handles n-way
buffering. API Buffer Server (bufserv) requires manual configuration
whenever a collective changes, and buffered data is compressed at Historian
Data Archive, so archives at different collective members could contain
different records.

P
-P-

Pigetmsg utility
n. A command-line utility to view messages stored by PI Message Subsystem.
The utility can retrieve messages based on characteristics like time stamp, a
search string, or the program name that generated the message.

PIHOME
n. PIHOME refers to the folder defined by the PIHOME environment variable
and is the directory in which most 32-bit client applications are installed. By
default, PIHOME is C:\Program Files(x86)\Rockwell
Software\FactoryTalk\PIPC on 64-bit machines and C:\Program Files\pipc
on 32-bit machines. Pipc does not need to be in the name, but it is in the name
by default.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 83

Glossary

PIHOME64
n. PIHOME64 refers to the folder defined by the PIHOME64 environment
variable and is the directory in which most 64-bit client applications are
installed. By default, PIHOME64 is C:\Program Files\Rockwell
Software\FactoryTalk Historian\PIPC. on 64-bit machines. Pipc does not
need to be in the name, but it is in the name by default.

Pipc.log file
The pipc.log file is a message file for Rockwell Automation interfaces based on
UniInt versions earlier than 4.5.0.x. When these interfaces run, they write
informational and error messages to the pipc.log file. View this log file with
Historian Interface Configuration Utility.

Point
n. See Historian Point.
Note: Rockwell Automation often uses the terms point and tag interchangeably. Point is
recommended unless it refers directly to the Historian tag attribute.

PI API
n. A C-based application programming interface (API) library of functions
that enable programs to access a local or remote Historian Data Archive server
across a network.

PI Message Subsystem
n. The core Historian Data Archive component that records informational and
error messages from various Historian Data Archive components in a series of
log files. PI Message Subsystem can also serve these messages to various client
applications.

PI SDK
n. The COM-based software development kit for Historian System
applications. The PI SDK is a set of programming libraries for development of
Microsoft Windows client programs or interfaces that can communicate with
most Historian Data Archive versions (PI Server 3.2.357 and up) on any
supported operating system.

84 Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

 Glossary

S-T -S-

SMT
n. See System Management Tools (SMT).

System Management Tools

n. A set of client-based programs to complete a wide variety of common
administrative tasks on a Historian Data Archive. Also known by the acronym
SMT.

-T-

Tag attribute
n. The Historian Point attribute that assigns a name to uniquely identify a
point.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 85

 Legal Notices

Legal Notices Rockwell Automation publishes legal notices, such as privacy policies, license
agreements, trademark disclosures, and other terms and conditions on the
Legal Notices page of the Rockwell Automation website.

End User License Agreement (EULA)

You can view the Rockwell Automation End User License Agreement (EULA)
by opening the license.rtf file located in your product's install folder on your
hard drive.
The default location of this file is:
• For 32-bit operating system:
C:\Program Files\Common Files\Rockwell\license.rtf.
• For 64-bit operating system:
C:\Program Files (x86)\Common Files\Rockwell\license.rtf.

Open Source Software Licenses

The software included in this product contains copyrighted software that is
licensed under one or more open source licenses.
You can view a full list of all open source software used in this product and
their corresponding licenses by opening the release notes.chm file located on
your hard drive.
The default location of this file is:
• For 32-bit operating system:
C:\Program Files\Common Files\Rockwell\Help\FactoryTalk Historian
to Historian Interface 3.10.01\FTH2HRN.chm
• For 64-bit operating system:
C:\Program Files (x86)\Common Files\Rockwell\Help\FactoryTalk
Historian to Historian Interface 3.10.01\FTH2HRN.chm
You may obtain Corresponding Source code for open source packages
included in this product from their respective project web site(s).
Alternatively, you may obtain complete Corresponding Source code by
contacting Rockwell Automation via the Contact form on the Rockwell
Automation website: http://www.rockwellautomation.com/global/about-
us/contact/contact.page. Please include "Open Source" as part of the request
text.

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021 87

Rockwell Automation support
Use these resources to access support information.
Technical Support Center Find help with how-to videos, FAQs, chat, user forums, and product notification rok.auto/support
updates.
Knowledgebase Access Knowledgebase articles. rok.auto/knowledgebase
Local Technical Support Phone Numbers Locate the telephone number for your country. rok.auto/phonesupport

Literature Library Find installation instructions, manuals, brochures, and technical data publications. rok.auto/literature
Product Compatibility and Download Center Get help determining how products interact, check features and capabilities, and rok.auto/pcdc
(PCDC) find associated firmware.

Documentation feedback
Your comments help us serve your documentation needs better. If you have any suggestions on how to improve our content, complete the form at
rok.auto/docfeedback.

Waste Electrical and Electronic Equipment (WEEE)

At the end of life, this equipment should be collected separately from any unsorted municipal waste.

Rockwell Automation maintains current product environmental information on its website at rok.auto/pec.

Allen-Bradley, expanding human possibility, Logix, Rockwell Automation, and Rockwell Software are trademarks of Rockwell Automation, Inc.

EtherNet/IP is a trademark of ODVA, Inc.

Trademarks not belonging to Rockwell Automation are property of their respective companies.

Rockwell Otomayson Ticaret A.Ş. Kar Plaza İş Merkezi E Blok Kat:6 34752, İçerenkÖy, İstanbul, Tel: +90 (216) 5698400 EEE YÖnetmeliğine Uygundur

Rockwell Automation Publication H2H-UM001B-EN-E-May 2021

Supersedes Publication H2H-UM001A-EN-E-July 2012 Copyright © 2021 Rockwell Automation Technologies, Inc. All Rights Reserved. Printed in the U.S.A.