This document and any accompanying Rockwell Software products are copyrighted by Rockwell Automation,
Inc. Any reproduction and/or distribution without prior written consent from Rockwell Automation, Inc. is
strictly prohibited. Please refer to the license agreement for details.
FactoryTalk, FactoryTalk Historian Machine Edition (ME), FactoryTalk Historian Site Edition (SE), FactoryTalk
Live Data, FactoryTalk Services Platform, FactoryTalk VantagePoint, FactoryTalk View, FactoryTalk ViewStudio,
Rockwell, Rockwell Automation, Rockwell Software, RSView, RSView Machine Edition, RSView ME Station,
RSView Studio, and RSLinx Enterprise are trademarks of Rockwell Automation, Inc.
Any Rockwell Automation logo, software or hardware not mentioned herein is also a trademark, registered or
otherwise, of Rockwell Automation, Inc.
For a complete list of products and their respective trademarks, go to
ActiveX, Microsoft, Microsoft Access, SQL Server, Visual Basic, Visual C++, Visual SourceSafe, Windows,
Windows ME, Windows NT, Windows 2000, Windows Server-, Windows XP, Windows 7, and Vista are either
registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Adobe, Acrobat, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in
the United States and/or other countries.
ControlNet is a registered trademark of ControlNet International.
DeviceNet is a trademark of the Open DeviceNet Vendor Association, Inc. (ODVA)
OLE for Process Control (OPC) is a registered trademark of the OPC Foundation.
Warranty
Oracle, SQL*Net, and SQL*Plus are registered trademarks of Oracle Corporation.
All other trademarks are the property of their respective holders and are hereby acknowledged.
This product is warranted in accordance with the product license. The product’s performance may be affected
by system configuration, the application being performed, operator control, maintenance, and other related
factors. Rockwell Automation is not responsible for these intervening factors. The instructions in this
document do not cover all the details or variations in the equipment, procedure, or process described, nor do
they provide directions for meeting every possible contingency during installation, operation, or
maintenance. This product’s implementation may vary among users.
This document is current as of the time of release of the product; however, the accompanying software may
have changed since the release. Rockwell Automation, Inc. reserves the right to change any information
contained in this document or the software at any time without prior notice. It is your responsibility to obtain
the most current information available from Rockwell when installing or using this product.
Chapter 1
Table of Contents
Introduction
Principles of Operation
Configuring FactoryTalk
Historian Live Data Interface
The FactoryTalk Historian system uses the PI system as a back end
to store tag data. The FactoryTalk Historian Live Data Interface
(FTLD) allows FactoryTalk Historian to connect with Rockwell
data sources. The FTLD interface provides buffering capability
before the data is permanently stored in the Historian archive.
Installation
The FTLD Interface is integrated with the FactoryTalk Live Data
service provided by FactoryTalk Services Platform. It is a
FactoryTalk Live Data client that relies on FactoryTalk Live Data
service to talk to FactoryTalk data servers such as FactoryTalk View
SE, RSLinx Enterprise, and OPC servers that are part of a
FactoryTalk application.
NOTE
The FactoryTalk Historian documentation uses the terms tag and point
to mean the same thing. An example of a tag name is:
FTLDEnt:rc:RSLinxC.secondArray000.
The FTLD Interface is configured using the FactoryTalk
Administration Console or Interface Configuration Utility. See
"Configuring FactoryTalk Historian Live Data Interface (page 15)"
for more information.
The steps to install the FactoryTalk Historian Live Data Interface
are explained in the FactoryTalk Historian SE Installation and
Configuration Guide, available from Start > All Programs > Rockwell
Software > FactoryTalk Historian SE > Help.
The complete user documentation on FactoryTalk Historian SE is
available in the Common Files\Rockwell\Help folder in your Program Files directory, and in the Redist\Docs folder on your
FactoryTalk Historian SE installation DVD.
Chapter 1 Introduction
Features
The features of the FTLD Interface include:
Item Description
PI SDK The PI SDK and the PI API are bundled together and must be
installed on each PI Interface node. The FTLD Interface does not
specifically make PI SDK calls. It uses the PI API calls to support
longer instrument tag fields and multiple-character point sources.
The PI SDK cannot be used if the interface will be set up to use
Disconnected Startup because it is based on API calls only.
Source of Time
Stamps
UniInt-based UniInt stands for Universal Interface. UniInt is not a separate
Platforms The FTLD Interface is designed to run on the Microsoft Windows
The FTLD Interface can accept time stamps from the FactoryTalk
Live Data server, or it can provide time stamps from the FactoryTalk
Historian server. This is controlled by a command-line parameter.
See "Startup Command File (page 39)" for more information on
using the command line to control time stamps.
product or file; it is an OSIsoft-developed framework used by
developers, and it is integrated into many interfaces, including this
interface. The purpose of UniInt is to keep a consistent feature set
and behavior across as many Rockwell interfaces as possible. It also
allows for a rapid development of new interfaces. In any
UniInt-based interface, the interface uses some of the
UniInt-supplied configuration parameters and some
interface-specific parameters.
operating systems.
Due to its dependency on FactoryTalk Services Platform, the
FactoryTalk Historian Live Data Interface is not supported on
non-Windows platforms. To see a list of operating systems
supported, refer to the FactoryTalk Historian SE Release Notes.
Related Documentation
The following documentation provides additional information
related to the FTLD Interface:
• FactoryTalk Historian SE Installation and Configuration
The FactoryTalk Live Data (FTLD) Interface is a FactoryTalk Live
Data client that enables process data to be passed between a
FactoryTalk Live Data server (for example, RSLinx Enterprise) and
a FactoryTalk Historian server. Each instance of the FTLD Interface
can provide data to a single FactoryTalk Historian SE server or
collective. Multiple instances of the interface may be configured, if
required, if API buffering is used.
The figure below shows the basic workflow of the FactoryTalk
Historian Live Data Interface.
At startup, the FTLD Interface tries to establish a connection to
both the FactoryTalk Live Data server and the FactoryTalk
Historian server.
Once the startup is complete, the Interface enters the processing
loop, which includes:
• Servicing scheduled input points. Each Scan Class is processed
in turn.
• Servicing output points as events arrive.
• Servicing triggered input points as events arrive.
The Historian Point Database is checked every 2 minutes for points
that are added, edited, and deleted. When point updates are
detected, the points are loaded (or reloaded) by the Interface as
appropriate. The 2-minute update interval can be adjusted with the
/updateinterval command-line parameter discussed in the UniInt
Interface User Manual.
The manual is located in the UniInt folder (c:\Program
Files\Rockwell Software\FactoryTalk
Historian\Server\PIPC\Interfaces\UniInt).
The Interface processes a maximum of 25 point updates at a time. If
more than 25 points are added, edited, or deleted at one time, the
Interface will process the first 25 points, wait 30 seconds (or the
length of time specified by the /updateinterval parameter, whichever
is lower), process the next 25 points, and so on. After all points have
been processed, the Interface will resume checking for updates every
2 minutes (or the length of time specified by the /updateinterval
parameter).
All tag edits are performed in the following way: old versions of
edited tags are deleted from the interface, new versions are added.
Therefore, it is more efficient to stop and then start the interface if a
large number of tags are edited.
FactoryTalk Diagnostics
The FTLD Interface sends messages about its operation to
FactoryTalk Diagnostics.
FactoryTalk Diagnostics provides the following information about
the FTLD Interface:
• Informational messages on the interface startup and
shutdown.
• The scan rate of each scan class.
• The count of points loaded by the interface.
• Error messages for points rejected by the interface because they
were configured incorrectly.
• Error messages for points rejected by the FTLD server, or error
messages sent from the FTLD server.
Because the FTLD Interface is based on the PI-UniInt framework, a
few messages are sent to the PIPC log by the PI-UniInt. These error
messages are produced by the standard OSIsoft interface routines or
by the PI API.
NOTE
The FactoryTalk Diagnostics Setup and Viewer are available from the
Tools menu of FactoryTalk Administration Console.
To learn more about viewing error messages and accessing the log
file, refer to the help files for FactoryTalk Diagnostics Setup and
FactoryTalk Diagnostics Viewer.
• If you are configuring the buffer subsystem on an FTLD
Interface.
For more information, refer to "Enable Buffering" in the
FactoryTalk Historian SE Installation and Configuration
Guide.
NOTE
Enabling the buffer subsystem is a recommended step during
the installation of the FactoryTalk Historian Live Data Interface.
To take advantage of this feature, you must install the FTLD
Interface on a separate machine than the FactoryTalk Historian
SE.
• If you are configuring the Disconnected Startup option.
For more information, refer to "(Unint) Disconnected
Startup" in the Interface Configuration Utility Help.
Chapter 3 Configuring FactoryTalk Historian Live Data Interface
NOTE
NOTE
To open the Interface Configuration Utility (ICU) online help, go
to Start > All Programs > Rockwell Software > FactoryTalk
Historian SE > Interface Configuration Utility, and select Help >
Contents and Index from the main menu.
If you create an FTLD Interface using the Interface Configuration
Utility, it will not appear in the list of interfaces in the
FactoryTalk Administration Console. As a result, you will not be
able to configure the interface from the FactoryTalk
Administration Console.
Configuring the FTLD
Interface Using the
FactoryTalk Administration
Console
Configuring the FTLD
Interface Using the Interface
Configuration Utility (ICU)
Refer to "Configuring FactoryTalk Historian Live Data Interface" in
the FactoryTalk Historian SE Installation and Configuration Guide
for information on configuring an FTLD Interface using the
FactoryTalk Administration Console. This section also includes
steps on how to enable buffering on the remote interface.
You can configure the FTLD Interface on your local computer (the
computer on which the FactoryTalk Historian SE server is
installed); however, we recommend that you always install the
FTLD Interface on the computer that has the data server installed.
Refer to "Verifying the FactoryTalk Historian Live Data Local
Interface" in the FactoryTalk Historian SE Installation and
Configuration Guide for more information.
NOTE
For more information on the Interface Configuration Utility, refer to the
FT Historian SE Interface Configuration Utility guide available in the
Common Files > Rockwell > Help folder in your Program Files directory.
If you configure an interface in the ICU, the batch file of the
interface (FTLDInt.bat) will be maintained by the ICU, and all
Chapter 3 Configuring FactoryTalk Historian Live Data Interface
7. If necessary, edit the Scan Frequency and Scan Class values.
Item Description
Scan Frequency Indicates the frequency at which the interface reads values
Scan Class #
8. Click Apply.
Note that in this example the API Hostname is localhost, which
means that the interface will be configured to communicate with the
local FactoryTalk Historian SE server.
If you want the interface to communicate with a remote
FactoryTalk Historian server, you need to:
from the FactoryTalk Live Data server.
Associated with the Scan Frequency value. If there is no
interface defined, the Scan Class # will be displayed without
a time period.
1. Add the remote server to the Connection Manager (page 19).
2. Define the remote server as the API host (page 19).
NOTE
This step is required to ensure connection to the correct remote
server.
Once you have added the server to the Connection Manager and
defined it as the API host, you can select the server from the API Hostname list on the General page in the ICU.
There are additional parameters available for configuring the
interface:
• /MultiCOM
• /uiDll
• /FTDirectory
• /FTContext
To view them, click FTLDInt in the left pane of the dialog box.
The FactoryTalk Historian Live Data Interface uses FTLD as a
point source. A point source is a unique, single- or multi-character
string that is used to identify a Historian point as a point that
belongs to a particular interface.
PI 3 Server Node: Reserved
Point Sources
For example, the string Boiler1 may be used to identify points that
belong to the MyInt Interface. To implement this, the Point Source
attribute would be set to Boiler1 for every Historian Point that is
configured for the MyInt interface. Then, if /ps=Boiler1 is used on
the start-up command line of the MyInt interface, the interface will
search the Historian Point Database upon startup for every
Historian point that is configured with a Point Source of Boiler1.
Before an interface loads a point, it also examines additional
Historian point attributes to determine whether a particular point is
valid for the interface. For additional information, see
"Command-line Parameters (page 39)".
Several subsystems and applications that are shipped with the PI
System are associated with default Point Source characters:
Subsystem Point Source character
Totalizer T
Alarm G and @
Random R
RampSoak 9
Performance Equations C
Do not use these Point Source characters or change the default Point
Source characters for these applications.
If a Point Source character is not explicitly defined when creating a
PI point, the point is assigned a default Point Source character of
Lab (PI 3). Therefore, do not use Lab as a Point Source character for
an interface to avoid confusion.
IMPORTANT
Do not use a Point Source character that is already associated with
another interface program. However, it is acceptable to use the same
Point Source for multiple instances of an interface.
A FactoryTalk Historian point is the basic building block for
controlling data flow to and from the FactoryTalk Historian SE
server. A single point is configured for each measurement value that
needs to be archived.
Point Attributes
Historian points (tags) have approximately 50 attributes. These
attributes define how data is to be collected and stored for the point.
The proper configuration of these attributes is the key to optimizing
the FactoryTalk Historian server for both data storage efficiency and
quick retrieval. Each FactoryTalk Historian interface handles
specific point attributes differently.
A tag is a label or name for a Historian point.
NOTE
The FactoryTalk Historian documentation uses the terms tag and point
to mean the same thing. An example of a tag name is:
FTLDEnt:rc:RSLinxC.secondArray000
The information presented in this chapter is necessary to define
FactoryTalk Live Data (FTLD) points for use with a FactoryTalk
Live Data server. Failing to correctly configure FactoryTalk
Historian data points will result in poor or no communication
between the interface and the FactoryTalk Live Data server. See
"Error and Informational Messages (page 51)" for more information
on errors that may occur.
The Tag field allows a maximum of 1023 characters.
Chapter 5 Point Configuration
Point Source
Point Type
PI 3 Server Nodes
The Point Source is a unique single or multiple character string that
is used to identify the PI point as a point that belongs to a particular
interface. The Point Source for FactoryTalk Historian Live Data
Interface is FTLD. For additional information, see the /ps
command-line parameter description in "Command-line Parameters
(page 39)".
Typically, device point types do not need to correspond to Historian
point types. For example, integer values from a device can be sent to
floating-point or digital Historian tags. Similarly, a floating-point
value from the device can be sent to integer or digital Historian tags,
although the values will be truncated.
The following point types are supported on PI 3 Servers:
• float16
Location1
• float32
• float 64
• int16
• int32
• digital
• string
NOTE
For more information on the individual point types, refer to the
FT Historian SE Server Reference Guide, available in the Common
Files > Rockwell > Help folder in your Program Files
directory.
Location1 indicates to which copy of the interface the point belongs.
The value of this attribute must match the /id startup parameter.
The default value for the FTLD Local Interface is 1.
Location3 is used to define a data collection mode:
Item Description
0 - Polled or Event Data is collected based on the scan rate and saved in the buffer.
When the Historian server requests data, the data stored in the
buffer is sent to the server. In this method, the values being sent to
the Historian server are from a buffer, so they may not represent
the exact (current) values in the controllers.
1 - Advise (Default) Data is collected only when a value changes in the controller. It is
not based on the scan rate. It is the default data collection method,
and is the most efficient because data is sent to the Historian server
only when the value changes.
2 - Output Data is written back to the Live Data server such as RSLinx
Enterprise, HMI server such as FactoryTalk View, or OPC server such
as RSLinx Classic. Use this method when you want to write data
points back to the data servers.
Location4 defines the scan class for the Historian point. The scan
class determines the frequency at which input points are scanned for
new values. For more information, see the description of the /f
parameter in "Command-line Parameters (page 39)".
The updates from the FactoryTalk Live Data server come in groups:
at startup, the interface defines a group on the Live Data server and
adds all points within the given scan class to the group. The
FactoryTalk Live Data server is queried for all points within a group
at the same time; therefore, some consideration should be given to
the creation of scan classes. Having more than one scan class with
the same scan period is allowed, and using different offsets on those
scan classes may improve performance.
Advise tags and Polled tags use Location4 to specify the requested
update rate for the group.
Location4 is ignored for Output tags.
NOTE
Advise, Polled, and Output data collection methods are explained in
"Location3 (page 25)".
If Location5=1 and Location3=0, it will force an asynchronous read
from the data server. It should only be used for event-triggered
points due to performance concerns.
The InstrumentTag contains the ItemID of the tag. The format of
this field depends on the FactoryTalk Live Data server:
Type of the tag InstrumentTag syntax
Length
Device tags <application name>/<area name>:<data server
name>:[<shortcut name>]<tag name>
HMI tags <application name>/<area name>:<HMI server Name>:<folder
name>\<tag name>
The field must match the point defined on the FactoryTalk Live
Data server, including punctuation, spaces, and case.
The InstrumentTag field allows a maximum of 1023 characters.
The FTLD interface gets the $Global scope from the /FTDirectory
parameter and / from the /FTContext parameter. For additional
information on these parameters, see "Command-line Parameters
The ExDesc (Extended Descriptor) is a string attribute. Typically,
this attribute is used to implement Trigger Input points.
For example: If a PI point has the ExDesc attribute "EVENT='Tag1' Anychange," it means trigger on any change as long as the Tag1 value
of the current event is different from the value of the previous event.
The ExDesc field allows a maximum of 1023 characters.
An output point is associated with a trigger point by setting the
SourceTag attribute of the output point equal to the tag name of the
trigger point.
For more information, see "Output Points (page 29)".
For each data point, you can set the following attributes to configure
its compression testing specification:
Specifies in engineering units how much a value may differ from
the previous value before it is considered to be a significant value.
As a rule of thumb, set CompDev to the precision of the data source
or hardware (instrument). Set it a little “loose” to err on the side of
collecting, rather than losing data. After collecting data for a while,
go back and check the data for your most important tags, and then
adjust CompDev, if necessary.
Note: Setting the CompDev attribute value too low causes too little
data compression, and wastes space in the archive.
Setting the value too high causes loss of useful data. For most
flows, pressures, and levels, use a deviation specification of 1% or
2% of span. For temperatures, the deviation should usually be 1 or
2 degrees.
Chapter 5 Point Configuration
Exception Reporting
Item Description
Compression
Minimum
(CompMin)
A point is archived if the elapsed time since the previous time the
point was saved is greater than or equal to the minimum time, and
the value has changed by more than the deviation. For data points
associated with interfaces that send exception reports, set
CompMin to 0.
Compression
Maximum
(CompMax)
A point is archived if the elapsed time since the previous time the
point was saved is greater than the maximum time. The
recommended maximum time specification is one work shift (for
example, 8 hours). Duplicate values will be archived if the elapsed
time exceeds CompMax. You typically set CompMax to the same
value for all points in the system.
NOTE
For information on compression testing, refer to "Exception Reporting
and Compression Testing" in the FactoryTalk Historian SE Server Reference Guide, available in the Common Files\Rockwell\Help folder
in your Program Files directory.
For each data point, you can set the following three attributes to
configure its exception reporting specification:
Specifies in engineering units how much a point's value must
change before the interface considers it a significant value, and
sends it to the server. As a general rule, you should set the
exception slightly smaller than the precision of the instrument
system.
Specifies a limit on how frequently the interface can report values
to the server. For example, if you want the interface to wait full ten
minutes before reporting a new value to the server, then you would
set the ExcMin attribute to ten minutes. ExcMin is typically set to
zero.
Specifies a limit on how long the interface can go without reporting
a value to the Historian server. After the ExcMax time period, the
interface sends the next new value to the server, regardless of
whether the new value is different from the last reported value.
Point Configuration Chapter 5
NOTE
For information on exception reporting, refer to "Exception Reporting
and Compression Testing" in the FactoryTalk Historian SE Server
Reference Guide, available from Start > Programs > Rockwell Software >
FactoryTalk Historian SE > Help.
Output Points
Trigger Method 1
(Recommended)
Output points control the flow of data from the Historian server to
any destination that is external to the server, such as the FTLD
server. The FTLD Interface uses Location3=2 to indicate an output
point.
Outputs are triggered for UniInt-based interfaces. That is, outputs
are not scheduled to occur on a periodic basis. There are two
mechanisms for triggering an output, as described in the sections
that follow.
For Trigger Method 1, a separate trigger point must be configured.
The output point must have the same point source as the interface.
The trigger point can be associated with any point source, including
the point source of the interface. Also, the point type of the trigger
point does not need to be the same as the point type of the output
point.
The output point is associated with the trigger point by setting the
SourceTag attribute of the output point equal to the tag name of the
trigger point. An output is triggered when a new value is sent to the
Snapshot of the trigger point. The new value does not need to be
different than the previous value that was sent to the Snapshot to
trigger an output, but the time stamp of the new value must be more
recent than the previous value.
If no error is indicated, then the value that was sent to the trigger
point is also written to the output point. If the output is
unsuccessful, then an appropriate digital state that is indicative of
the failure is usually written to the output point. If an error is not
indicated, the output still may not have succeeded because the
interface may not be able to tell with certainty that an output has
failed.
Trigger Method 2
Sample Tag Configurations
For Trigger Method 2, a separate trigger point is not configured. To
trigger an output, write a new value to the Snapshot of the output
point itself. The new value does not need to be different than the
previous value to trigger an output, but the time stamp of the new
value must be more recent than the previous value.
Trigger Method 2 may be easier to configure than Trigger Method
1, but Trigger Method 2 has a significant disadvantage. If the output
is unsuccessful, there is no tag to receive a digital state that is
indicative of the failure, which is very important for
troubleshooting.
See the following sample tag configurations:
• Scan Classes (page 30)
• Polled Tags (page 31)
• Advise Tags (page 31)
• Event Tags (page 31)
Scan Classes
Scan classes are defined in the startup file. Each /F= parameter
defines a scan class, which is numbered in order.
For example, if the .bat file reads
/F=2 /F=1:00 /F=1:30:00 /F=00:00:05,00:00:01
then these scan classes have been defined:
• Scan Class 1 has a scan period of 2 seconds.
• Scan Class 2 has a scan period of 60 seconds.
• Scan Class 3 has a scan period of 5400 seconds (90 minutes).
For Advise tags, the interface asks the FTLD server to send data
when it changes, and how often it should read the device to see if
there is a new value.
Event tags are read when the triggering event occurs. An event
happens when the FactoryTalk Historian snapshot receives a value
for the trigger tag. It may have the same time stamp and quality and
value as the last event so the snapshot value for that trigger may seem
the same, but the act of receiving a value for the trigger tag causes the
interface to receive a notification that the trigger has been updated.
To configure triggered input tags, specify the name of the trigger tag
in the ExDesc field using the following format:
triggertagname is enclosed in single quotes and, if specified,
event_condition immediately follows the triggertagname. If
event_condition is not specified then it defaults to Anychange.
The update rate for event item groups is also related to the scan class,
so the server will be asked to update its cache once every scan period
for every event tag defined. This is probably faster or slower than
necessary. You must set the Loc4 attribute to make event tags work
well. The Location 5 attribute should have the value 1 for Event
tags.
Typical example:
Tag ExDesc Instrument Tag Loc1 Loc2 Loc3 Loc4 Loc5
In this case, PM1_Trigger are tags that are updated by this interface,
by another interface, or by manual entry. When a PM1_Trigger gets
a new event in the PI snapshot, the interface will send data for both
PM1_Temp.PV and PM1_Rate.PV to the PI server.
An I/O Rates tag measures the throughput of an FTLD Interface. In
particular, the value of an I/O Rate point represents a 10-minute
average of the total number of values per minute that the FTLD
Interface sends to the FactoryTalk Historian server. Because values
are averaged over a 10-minute interval, the first calculated value is
not written to the Historian server earlier than 10 minutes after the
interface has started. You can configure one I/O Rates tag for each
copy of the FTLD Interface that is in use.
Monitoring I/O Rates Tag on
the Interface Node
Configuring I/O Rates Tag
with ICU
NOTE
The Historian system documentation often uses the terms Event Counter
Tag and I/O Rate Point synonymously.
For Windows nodes, the 10-minute rate averages (in
events/minutes) can be monitored with a client application such as
PI ProcessBook.
The Interface Configuration Utility (ICU) provides a user interface
for creating and managing the I/O Rates tag.
To access the I/O Rates tag data in ICU, select IO Rate from the
left pane of the ICU dialog box.
ICU currently allows for one I/O Rates tag to be configured for each
copy of the interface that is in use. Some interfaces allow for
multiple I/O Rates tags.
The Input IORates Tag section contains the following elements:
Item Description
Enable IORates for
this interface
Select the check box to enable I/O Rates for the selected interface.
Clear the check box to disable I/O Rates for the selected interface.
Create Click it to create the suggested I/O Rates tag with the tag name
indicated in the Tagname text box.
Delete
Reset
Rename
Click it to delete the I/O Rates tag listed in the Tagname text box.
Click it to reset the I/O Rates Event Counter and Tag settings.
Click it to change the name of the I/O Rates tag using the Rename
IORates Tag dialog box.
Add to File Click it to add the tag to the IORates.dat file with the event counter
listed in the Event Counter text box.
Event Counter The Event Counter correlates a tag specified in the iorates.dat file
with this copy of the interface. The command-line equivalent is
/ec=x, where x is the same number that is assigned to a tag name
in the iorates.dat file.
Suggest
• In the ICU dialog box, click it if you want the system to suggest
the next available Event Counter. The button is active if the
Event Counter text box is empty or contains an illegal value.
• In the Rename IORates Tag dialog box, click it if you want the
system to suggest a tag name.
Tagname
Type the name of the I/O Rates tag, or click the TagSearch icon to
find the tag using the Tag Search dialog box.
TagSearch. Click it to find the I/O Rates tag for the interface using
Performance Point tags document how long it takes to complete a
scan. Due to the architecture of this interface, the performance point
tags are not valid - the server's response is asynchronous, so the time
to scan bears no relation to the amount of time it may take to get the
data from the server.
In Windows, command file names have a .bat extension. The
Windows continuation character (^) allows for the use of multiple
lines for the startup command. The maximum length of each line is
1024 characters (1 kilobyte). The number of parameters is
unlimited, and the maximum length of each parameter is 1024
characters.
Command-line Parameters
Command-line parameters should begin with a “/” character. For
example, /ps=M.
The Interface Configuration Utility (ICU) provides a tool for
configuring the FTLD Interface startup command file.
The table below lists command-line parameters and their
descriptions.
IMPORTANT
We recommend that you always use the Interface Configuration Utility
to modify the startup file. If you manually change the startup file and
then open it using the Interface Configuration Utility, the utility will
rewrite all the startup parameters in the file.
/ps=Source The /ps parameter specifies the point source for the interface. The Source value is not case
sensitive. The length of the Source value is limited to 100 characters by the PI-UniInt. The
value can contain any character except ‘*’ and ‘?’.
The point source that is assigned with the /ps parameter corresponds to the Point Source
attribute of the individual Historian point. The interface will attempt to load only those
Historian points that have the appropriate point source.
Strategies for assigning a point source character vary depending on the interpretation of
the /id parameter by a particular interface. See the /id parameter description for more
information.
/id=x Example: /id=1
The /id parameter specifies the interface identifier.
The interface identifier is a string that is no longer than 9 characters. FTLD Interfaces also
use the /id parameter to identify a particular interface copy number which corresponds to
an integer value that is assigned to one of the Location code point attributes, most
frequently Location1. For these interfaces, you should use only numeric characters in the
identifier.
/host=host:port The /host parameter specifies the PI Home node. Host is the IP address of the PI Server
node or the domain name of the PI Server node. Port is the port number for TCP/IP
communication.
The port is always 5450.
"
/FTDirectory=$Global The /FTDirectory parameter specifies the FactoryTalk directory. It can only be set to
/FTContext="/" This parameter is reserved. Set to “/”.
The /uiDLL parameter is used to specify the DLL file name of the FTLD interface. The DLL file
is usually installed in the \Windows\System32\ or Windows\SysWOW64\ directory. If the
DLL file is located elsewhere, the full path to the DLL must be provided in the /uiDLL
parameter.
/f=SS
or
/f=SS,SS
or
/f=HH:MM:SS
or
/f=HH:MM:SS,hh:mm:ss
Required for reading scan-based inputs.
The /f parameter defines the time period between scans in terms of hours (HH), minutes
(MM), and seconds (SS). The scans can be scheduled to occur at discrete moments in time
with an optional time offset specified in terms of hours (hh), minutes (mm), and seconds
(ss). If HH and MM are omitted, then the time period that is specified is assumed to be in
seconds.
Each instance of the /f parameter on the command-line defines a scan class for the
interface. 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 point
attribute. For example, all 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 with no offset.
When no offset is specified, the scan class will be scheduled for immediate execution. That
is, the interface will not wait for a well-defined moment in time before scanning when no
offset is specified.
One can also specify sub-second scan classes on the command line such as:
/f=0.5 /f=0.1
Optional parameters:
Parameter Description
/PISDK=# Default = 0.
The /pisdk parameter can be used to enable or disable the PI SDK.
• Use /pisdk=1 to enable the PI SDK.
• Use /pisdk=0 to disable the PI SDK.
/maxstoptime=stoptime Default = 120 seconds.
When an interface receives a signal from the operating system to shut down, it must
perform a number of cleanup functions. If for some reason the execution of these functions
takes longer than the stop time, the interface will shut down without finishing these
functions.
interfaces, such as the FTLD, that support outputs. If the /sio parameter is not specified, the
outputs will not be written when the FTLD Interface starts or when an output tag is edited.
Parameter Description
/sio Default = send initial outputs.
The /sio parameter stands for suppress initial outputs. The parameter applies only to
FTLD Interface will behave in the following manner: when the FTLD Interface is started, it
determines the current Snapshot value of each output tag. Next, the FTLD interface writes
this value to each output tag. In addition, whenever an individual output tag is edited
while the FTLD Interface is running, it will write the current Snapshot value to the edited
output tag.
This behavior is suppressed if the /sio parameter is specified on the command line. That is,
In other words, when the /sio parameter is specified, outputs will only be written when
they are explicitly triggered.
/perf=interval Default = 8 hours
When the percentage of scans that a UniInt-based interface performs on time drops below
95%, UniInt will write the performance summaries for each scan class into the PIPC.log file.
For example, if /perf=0.025, UniInt will write performance summaries every 90 seconds if
the percentage of on-time scans is below 95%. The minimum time between summaries is
60 seconds. Setting /perf=0 disables summaries.
If the /perf parameter is omitted, then by default, every 8 hours, UniInt checks whether
summaries are needed.
If the inputs for the interface are unsolicited, then performance summaries should be
disabled by setting /perf=0, because performance summaries are meaningless for
unsolicited input points.
/q Default = no queuing.
When the /q parameter is present, Snapshots and exceptions are queued before they are
sent to the PI Server node. The maximum queue size is close to 4000 bytes. The queue is
flushed between scans if it is not filled. For an interface collecting unsolicited data, the
queue is flushed four times a second if it is not filled.
/TSofPIorFT The /TSofPIorFT parameter specifies which time stamp will be used to determine when to
send data to the Historian server:
• /TSofPIorFT=0 means using server time stamp
• /TSofPIorFT=1 means using FTLD server time stamp
Notes: By default, there is no /TSofPIorFT parameter in the .bat file. In this case, the
Historian server time stamp will be used.
An unsolicited point will always use FTLD Server time stamps.
/MultiCom Use the /MultiCom parameter if you want the PI-UniInt executable to select the
Multithreaded Threading model (COINIT_MULTITHREADED) for the call to CoInitializeEx().
Otherwise, the PI-UniInt will use the Apartment Threaded model
(COINIT_APARTMENTTHREADED).
For more flexibility, the FTLD interface can use an INI format file
to configure interface information. This format file does not install
with the FTLD interface, but you can create the file manually. It
should be named FTLDInt.ini and it must be created in the same
path as the FTLDInt.exe file and the FTLDIntCtl.dll file.
OnceMaxUnsolEvents The OnceMaxUnsolEvents key specifies the maximum
number of unsolicited events that the FTLD Interface can
process in each loop for each Advised Tag. The default value
for OnceMaxUnsolEvents key is 4. That is, the interface can
process 4 events for each advised tag when the interface
collects data.
ScanClassToUpdateRate For polled points, the FTLD interface calculates the update
rate from its scan time. The update rate is used while
adding an item to the FTLD server.
The algorithm is "Update Rate = Scan Time /
ScanClassToUpdateRate"
For example, if a point has a 1-second scan period and the
ScanClassToUpdateRate is 2, the FTLD Interface will use 500
ms as the update rate.
PIOrFTLDTimestamp The PIOrFTLDTimestamp key specifies which time stamp
will be used to determine when to send data to the
FactoryTalk Historian server. PIOrFTLDTimestamp=0 means
the FactoryTalk Historian server time stamp is used, and 1
means the FTLD server time stamp is used. This setting is
similar to the /TSofPIorFT command-line parameter. See
"Command-line Parameters (page 39)" for more
information.
FTLDResponseInterval The FTLDResponseInterval key specifies the time interval
during which the FTLD interface checks for data points that
were marked ‘bad_quality’ by the FTLD service. The FTLD
service will mark a data point ‘bad_quality’ if the data point
links to an incorrect item (data point) in the FactoryTalk
Diagnostics, or if the FTLD service was not able to receive a
data point from the FTLD interface because several other
data points were being added to the FactoryTalk Historian
server at that time. The period can be set in milliseconds
(ms). The default is 5000 ms.
Make sure that the time and time zone settings on the computer are
correct. Check the settings in the Date and Time program of
Control Panel. If the locale where the interface node resides observes
Daylight Saving Time, check Automatically adjust clock for Daylight Saving Time in Time Zone Settings.
Make sure that the TZ environment variable is not defined on the
computer. To check it, type
set in the Command Prompt window.
All the environment variables currently defined in Windows will be
listed. If the TZ environment variable is defined, remove it using the
System item of Control Panel.
NOTE
IMPORTANT
It is possible for computer nodes to boot up with different clock times
before synchronizing to the server time. If synchronization is left to the
Microsoft defaults, it can take several minutes for the system to
synchronize all node clocks in the network. To minimize clock
synchronization time, you can modify the registry on the computer
nodes in the FactoryTalk Historian SE system to adjust local clocks to the
server time. To do this, set the MaxAllowedPhaseOffset entry to 1 on
every node in the FactoryTalk Historian SE system. The entry resides in
the following subkey:
My
Computer\HKEY-_LOCAL_MACHINE\System\ControlSet001\services\W32
Time\Config.
We recommend that only advanced users modify the registry. Refer to
the system documentation for more information on the Windows
registry.
The trust database must be configured so that the FTLD Interface is
allowed to write data to the FactoryTalk Historian server.
If the FTLD Interface cannot write data to the FactoryTalk
Historian server because it has insufficient privileges, a 10401 error
will be reported in the pipc.log file. The file is located in
<HistorianInstallationDirectory>\Server\PIPC\DAT.
NOTE
For more details on trust configuration, please refer to the FactoryTalk
Historian SE server manuals, available in the Common Files\Rockwell\Help folder in your Program Files directory.
Once you have installed the FTLD interface as a service, you can
start and stop it in two ways:
• Using the Interface Configuration Utility (ICU) (page 49).
• Using the Administrative Tools program of Control Panel
(page 50).
The FTLD interface service may terminate immediately after the
startup for a variety of reasons. One of typical reasons is that the
service is not able to find the command-line parameters in the
associated .bat file. To avoid it, make sure that the root name of the
.bat file and the .exe file are the same, and that the files are located in
the same directory. Usually, they are stored in C:\Program
Further troubleshooting of the service may require consulting the
pipc.log file, Windows Event Viewer, or other sources of log
messages. See "Error and Informational Messages (page 51)" for
additional information.
Using the Interface
To start the FTLD interface:
Configuration Utility
1.Click Start > All Program > Rockwell Software > FactoryTalk
Historian SE > Interface Configuration Utility. The Interface
Configuration Utility dialog box appears.
2. From the Interface list, select the interface you want to start.
The FTLD Interface is based on the PI-UniInt framework,
therefore a few error messages are sent to the PIPC log by PI-UniInt.
Other error messages are sent to the FactoryTalk Diagnostics
system. When troubleshooting, we recommend that you check both
FactoryTalk Diagnostics and the PIPC log.
The following is the list of error messages sent to FactoryTalk
Diagnostics.
Severity Message text
Error Failed to disconnect from FactoryTalk.
Error Failed to initialize COM library.
Error Failed to initialize COM security.
Error Missing or invalid interface ID parameter.
Error Failed to initialize FactoryTalk Diagnostics.
Error Failed to launch FTLD interface due to the lack of the parameter
/FTDirectory.
Error Failed to launch FTLD interface due to the lack of the parameter
/FTContext.
Error Failed to connect to FactoryTalk Directory scope %s.
Error System error: Insufficient memory.
Warning Failed to remove FactoryTalk Live Data item <%s>.
Warning PI point <%s> is refused because of failure to add FactoryTalk Live
Data item <%s>.
Warning PI point <%s> is refused because of the invalid attribute of
Location [3].
Warning PI point <%s> is refused because of the invalid attribute of
InstrumentTag.
Warning PI point <%s> is refused because of the invalid attribute of
Location [4].
Warning The value quality of PI point <%s (PointID: %d)> with FactoryTalk
Warning Failed to convert PIEvent to FTLD variant type of data.
Warning Failed to write value to FactoryTalk Live Data item <%s>.
Warning Monitor disconnected from FactoryTalk service.
Warning Monitor reconnected to FactoryTalk service successfully.
Warning The value quality of PI point <%s (PointID: %d)> with FactoryTalk
Live Data item <%s> is bad because the FTLD service does not
respond in %d ms.
Information PI point <%s> has been removed from the FTLD interface
(InterfaceID: %d).
Information PI point <%s> is edited in the FTLD interface (InterfaceID: %d).
Information PI point <%s> has been added to the FTLD interface (InterfaceID:
%d).
Information Connected to FactoryTalk Directory scope %s successfully.
Information FTLD interface(ID:%d) has Scan Class %d = %s.
Information Disconnected from FactoryTalk Directory %s successfully.
System Errors and PI Errors
Error Descriptions
System errors are associated with positive error numbers. Errors
related to PI are associated with negative error numbers.
The descriptions of system and PI errors can be obtained with the
pidiag utility. It is a command-line utility (pidiag.exe) located in the
Rockwell provides dedicated technical support internationally, 24
hours a day, 7 days a week.
You can read complete information about technical support
options, and access all of the following resources at the Rockwell
Automation Support Web site
(http://www.rockwellautomation.com/support/).
Before You Call or Write for
Help
Find the Version and Build
Numbers
When you contact Rockwell Automation Technical Support, please
provide:
• Product name, version, and/or build numbers.
• Computer platform (CPU type, operating system, and version
number).
• The time that the difficulty started.
• The message log(s) at that time. Consult your product
documentation on the location of the message log files.
To find version and build numbers for each Historian Server
subsystem (which vary depending on installed upgrades, updates, or
patches), use either of the following methods:
To check the numbers with System Management Tools (SMT):
1. Go to Start > All Programs > Rockwell Software > FactoryTalk
Historian SE > System Management Tools. The System
Management Tools dialog box appears.
2. Under Collectives and Servers, select the name of the server
you want to check.
3. Under System Management Tools, select Operation > PI
Version.
The Version in Memory and Version on Disk columns
display information on versions of all the server subsystems.
If you do not have System Management Tools installed, open a
command prompt, change to the pi\adm directory, and type
piversion -v. To see individual version numbers for each subsystem,
change to the pi\bin directory and type the subsystem name
followed by the option -v (for example, piarchss.exe -v).
View Computer Platform
Information
To view platform specifications, right-click My Computer and
select Properties. For more detailed information, choose Start >
Please contact your local Rockwell Automation representative for the return procedure.
Rockwell Automation Support
Rockwell Automation provides technical information on the Web to assist you in using its products. At
http://www.rockwellautomation.com/support/, you can find technical manuals, a knowledge base of FAQs,
technical and application notes, sample code and links to software service packs, and a MySupport feature that
you can customize to make the best use of these tools.
For an additional level of technical phone support for installation, configuration, and troubleshooting, we offer
TechConnect support programs. For more information, contact your local distributor or Rockwell Automation
representative, or visit http://www.rockwellautomation.com/support/.
Installation Assistance
If you experience a problem within the first 24 hours of installation, review the information that is contained in
this manual. You can contact Customer Support for initial help in getting your product up and running.
Outside United States or
Canada
Use the Worldwide Locator at http://www.rockwellautomation.com/support/americas/phone_en.html, or contact your
local Rockwell Automation representative.
New Product Satisfaction Return
Rockwell Automation tests all of its products to ensure that they are fully operational when shipped from the
manufacturing facility. However, if your product is not functioning and needs to be returned, follow these
procedures.
United States Contact your distributor. You must provide a Customer Support case number (call the phone number above to obtain
one) to your distributor to complete the return process.
Documentation Feedback
Your comments will help us serve your documentation needs better. If you have any suggestions on how to
improve this document, complete this form, publication RA-DU002, available at
http://www.rockwellautomation.com/literature/.