PI IntFix 2.2.0.0

Intellution Fix DMACS (FIX32) /
Dynamics (iFIX)
Interface to the PI System
Version 2.2.0.0
OSIsoft, Inc.
Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual
iii
How to Contact Us
OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA 94577 USA
or PO Box 272
San Leandro, CA 94577 USA
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
support@osisoft.com
OSI Software, Ltd

Level 5 / 393 Khyber Pass Rd.
Newmarket
Auckland 1003 New Zealand
or PO Box 8256
Symonds Street
Auckland 1035 New Zealand
OSIsoft Canada ULC

8150, Metropolitain Blvd. East, Suite 200
Anjou (QC) H1K 1A1 Canada
OSI Software Asia, Pte Ltd.

152 Beach Road
#09-06 Gateway East
Singapore 189721
(01) 514-493-0663
(01) 514-493-0980 (fax)
(64) 9-522-5900
(64) 9-522-5901 (fax)
(65) 391-1811
(65) 295-2488 (fax)
European Joint Venture

OSI Software GmbH
Hauptstrasse 30
D 63674 Altenstadt, Germany
(49) 6047-2770
(49) 6047-6687 (fax)
For additional information, please see our Web site:

http://www.osisoft.com
327515112.doc
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI-ProcessBook, Sequencia,
Sigmafine, gRecipe, and sRecipe. All terms mentioned in this book that are known to be trademarks or service marks have been
appropriately capitalized. Any trademark which appears in this book that is not owned by OSIsoft, Inc. is the property of its
owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party's products or any
affiliation with such party of any kind.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights
in Technical Data and Computer Software clause at DFARS 252.227-7013
Table of Contents
Introduction.................................................................................................................... 1
Reference Manuals......................................................................................................1
Supported Features......................................................................................................1
Diagram of Hardware Connection................................................................................3
Principles of Operation..................................................................................................3
Data Updates............................................................................................................... 4
Alarm/Event Message Data Collection.........................................................................4
Point for Point Alarm/Event Message Data...............................................................4
All Alarm/Event Message Data to a Single PI String Tag..........................................4
Data Redundancy.........................................................................................................5
SCADA Node Failover..............................................................................................5
Interface Cluster Failover..........................................................................................5
Installation Checklist......................................................................................................7
Interface Installation......................................................................................................9
Naming Conventions and Requirements......................................................................9
Microsoft DLLs.............................................................................................................. 9
Interface Directories...................................................................................................10
The PIHOME Directory Tree...................................................................................10
Interface Installation Directory................................................................................10
Interface Installation Procedure..................................................................................10
Installing the Interface as an NT Service................................................................10
Installing the Interface Service with PI-Interface Configuration Utility.....................11
Installing the Interface Service Manually................................................................12
Digital States................................................................................................................15
Point Source.................................................................................................................17
PI Point Configuration..................................................................................................19
Point Attributes...........................................................................................................19
Tag.......................................................................................................................... 19
PointSource............................................................................................................ 19
PointType................................................................................................................ 19
Location1................................................................................................................ 19
Location2................................................................................................................ 20
iii
Location3................................................................................................................ 21
Location4................................................................................................................ 21
Location5................................................................................................................ 21
InstrumentTag......................................................................................................... 22
SourceTag...............................................................................................................22
ExDesc................................................................................................................... 23
Scan....................................................................................................................... 23
Shutdown................................................................................................................ 23
Performance Point Configuration...............................................................................25
Configuring Performance Points with PI-ICU.............................................................25
Configuring Performance Points Manually.................................................................26
I/O Rate Tag Configuration..........................................................................................27
Monitoring I/O Rates on the Interface Node...............................................................27
Configuring I/O Rate Tags with PI-ICU.......................................................................27
Configuring I/O Rate Tags Manually...........................................................................28
Configuring the PI Point on the PI Server...............................................................28
Configuration on the Interface Node.......................................................................29
Startup Command File................................................................................................31
Configuring Startup Parameters with PI-ICU Control..............................................31
Command Line Parameters....................................................................................35
Interface Node Clock...................................................................................................45
Security......................................................................................................................... 47
Starting / Stopping the Interface.................................................................................49
Starting Interface as a Service...................................................................................49
Stopping Interface Running as a Service...................................................................49
Buffering....................................................................................................................... 51
Configuring Buffering with PI-ICU...............................................................................51
Configuring Buffering Manually..................................................................................54
Example piclient.ini File..............................................................................................55
Appendix A: Error and Informational Messages........................................................57
Message Logs............................................................................................................57
System Errors and PI Errors.......................................................................................57
Interface-Specific Troubleshooting.............................................................................57
iv
Interface Startup and Point Loading Errors............................................................57

Data Collection Errors.............................................................................................58
Appendix B: FIXtoPI Configuration Transfer Utility...................................................61
Overview.................................................................................................................... 61
User Instructions.........................................................................................................62
Parameters.............................................................................................................62
Sample Command Lines........................................................................................63
Sample FixToPI.scr File..............................................................................................63
Sample Output........................................................................................................... 64
Appendix C: Cluster Failover......................................................................................67
Principles of Operation...............................................................................................67
Cluster Failover Configurations..................................................................................68
Configuring APIOnline............................................................................................68
Configuring the Interface........................................................................................69
Buffering Data on Cluster Nodes............................................................................75
Group and Resource Creation Using Cluster Administrator.......................................75
Cluster Group Configuration...................................................................................75
Installation of the Resources..................................................................................78
Testing Cluster Configuration.....................................................................................80
Appendix D: FIX Redundancy and PI-EDA.................................................................82
Principles of Operation...............................................................................................82
FIX32 Redundancy Setup..........................................................................................82
FIX32 View Node....................................................................................................82
FIX32 Primary SCADA Node..................................................................................83
FIX32 Backup SCADA Node...................................................................................83
FIX32 View Nodes Network Status Display............................................................84
FIX32 Node \winnt\system32\drivers\etc Host File.................................................84
PI Tag Configuration for FIX32 Tag.........................................................................84
iFIX Redundancy Setup.............................................................................................84
iFIX View Node.......................................................................................................84
iFIX Primary SCADA Node......................................................................................86
iFIX Backup SCADA Node......................................................................................86
iFIX Network Status Redundancy Display..............................................................87
iFIX Node \winnt\system32\drivers\etc Host File....................................................87
PI Tag Configuration for iFIX Tag............................................................................87
Table of Contents
vi
Introduction
The following interface moves data between Intellution FIX/iFIX software platforms and
PI. The interface program reads the PI point database to determine which points to read. It
then queries FIX/iFIX for current values and sends exception reports to the PI system. The
interface can also write values back to the FIX/iFIX database.
The interface runs on Windows NT platforms (NT 4.0 sp6a, Windows 2000 & XP). It
communicates using Intellutions EDA (Easy Data Access) library and can be run on either
a View or SCADA node if the eda.dll and fixtools.dll are installed
Reference Manuals
OSI
UniInt End User Document
PI Data Archive Manual
PI-API Installation Instructions
Intellution
Intellution Electronic Books
Supported Features
Feature
Support
Part Number
PI-IN-INT-FIXD-NTI
Platforms
NTI
PI Point Types
Float32 / Int32 / Float16 / Int16 /Digital / String
Sub-Second Timestamps
Yes
Sub-Second Scan Classes
Yes
Automatically Incorporates PI
Point Attribute Changes
Yes
Exception Reporting
Yes
Outputs from PI
Yes
Inputs to PI: Scan-Based /

Unsolicited / Event Tags
Scan-Based / Event Tags
Maximum Point Count
Unlimited
Uses PI-SDK
No
PINet to PI 3 String Support
N/A
* Source of Timestamps
PI server or PI-API node
History Recovery
No
Feature
Support
* Failover
Yes
* UniInt-Based
Yes
* Vendor Software Required on PIAPI / PINet Node
Yes
* Vendor Software Required on

Foreign Device
Yes
Vendor Hardware Required
No
* Additional PI Software Included

with Interface
Yes
* See paragraphs below for further explanation.
Source of Timestamps
Default behavior is for all data to receive the PI server system timestamp. The interface
can be configured to use the local system time for the timestamp of data by specifying the
/LS parameter in the interface startup file.
Failover
The interface supports failover through Microsoft cluster services. See Appendix C:
Cluster Failover for a complete discussion on how this works.
Its also possible to apply SCADA node redundancy through configuration of Intellution
View nodes. See Appendix D: FIX Redundancy and PI-EDA.
UniInt-Based
UniInt stands for Universal Interface, and it is an OSI-developed template used to create
many of our interfaces. UniInt is not a separate product or file, it is solely a template used
by our developers, and is integrated into the interface. The purpose of UniInt is to keep a
consistent feature set and behavior across as many of our interfaces as possible. It also
allows for the very rapid development of new interfaces. UniInt is constantly being
upgraded with new options and features. In any UniInt interface, UniInt uses some of the
supplied configuration parameters, and some parameters are interface-specific features of
the interface.
The UniInt End User Document is a supplement to this manual.
Vendor Software Required

The interface can be run on either a View or SCADA node if the eda.dll and
fixtools.dll are installed.
Its compatible with FIX 6.15 and greater, and iFIX 2.1 and greater. The following table
lists what we have tested internally:
**Intellution Software Compatibility Testing
FIX Dynamics 6.15
FIX Dynamics 7.0
iFIX 2.1
iFIX 2.21
**Intellution Software Compatibility Testing

iFIX 2.6
iFIX 3.0
** We will continue to test new releases of iFIX as they become
available.
Additional PI Software
This interface comes with the FixToPi Configuration Transfer Utility for extracting the
FIX database in a format ready for exporting to PI. A complete discussion of this utility
can be found in Appendix B: FIXtoPI Configuration Transfer Utility.
Supported Data Types

The interface can read analog, digital and string data types. Each Intellution tag has a
block type which is also associated with several fields. Each field represents kind of data
for that block. For example, Analog Input block types have a F_CV field for current value.
A complete listing of the different fields associated with each block can be viewed in the
Intellution Database Manger Online Help file, Block Field Reference section.
Diagram of Hardware Connection
NT Operating System
PI Home Node
(NT, Unix or
Open VMS)
(NT 4, Windows 2000 or XP)

PI-API
PI-FIX Interface
Remote PLC
Or
SCADA Node
Intellution
View/SCADA Node
Architecture of the Intellution FIX/iFIX Interface
Table of Contents
Principles of Operation
The interface uses Intellutionss EDA (Easy Data Access) library. The EDA library is
common to both FIX and iFix making this interface compatible with both platforms. The
interface must run on either a SCADA or VIEW node where eda.dll and
fixtools.dll are installed.
Data Updates
Point updates are either scan or event based. Scan based events are collected at a
frequency specified by the scan class (defined in the interface startup file). Event based
updates mean an update is requested when the specified source tag receives an update
(event-triggered updates). The interface reads the PI point database using the point source
and id to identify the interface points. It then processes the PI tag definition to identify
which Intellution point it references using the "node-tag-field" (NTF) identifier. The node
references the Intellution node name which reads data for the specified tag. Tag references
the tag name within the specified node, and field defines the type of data this tag
references. It then groups these points according to scan class, with one EDA group
defined for each scan class. In addition, if output tags are defined they will be placed in a
separate group.
To optimize performance, tags belonging to a particular node should be grouped into the
same scan classes for more efficient polling. By keeping all tags for individual nodes
within the same group, EDA does not have to poll multiple nodes in order to read values
for a single scan. Note that event-triggered tags take much longer to process since a
separate group is defined for each event tag, which is less efficient than scan based
updates.
Alarm/Event Message Data Collection

The interface also has the ability to access alarm/event message data. In order to enable
this functionality, either WUSERQ1.exe or WUSERQ2.exe must be added as a startup task
for the Intellution View or SCADA node. These tasks are responsible for making
alarm/event message data available to clients. We recommend running a separate copy of
the interface specifically for alarm/event message data collection to maximize
performance.
Point for Point Alarm/Event Message Data

If enabled, the interface uses scan class one to group all PI tags that will receive
alarm/event message data on a tag for tag basis. It is therefore critical that when
alarm/event message data collection is enabled, only tags intended for collection of
alarm/event data belong to scan class one. In this configuration the interface recieves a
alarm/event message string and checks the Intellution tag name. If a PI tag that belongs to
scan class 1 is configured for this point it attempts to extract the data value from the string
message and send it to PI. The interface startup file contains paramters for defining the
string position for the data within the alarm/event message (see Startup Command File for
details).
All Alarm/Event Message Data to a Single PI String Tag

The interface can also be configured to send all alarm/event messages to a single PI string
tag. The entire alarm/event message string for all events pulled from the WUSERQ are
sent to the PI string tag. The PI string tag is specified in the interface startup file.
Data Redundancy
There are two levels of data redundancy; SCADA node failover and interface cluster
failover.
SCADA Node Failover

Both FIX32 and iFIX support failover (starting from FIX32 version 6.15 and FIX
Dynamics version 2.0). The interface can take advantage of this functionality by running
on a View node. A View node can look at a pair of SCADA nodes that have the identical
databases (and are connected to the same PLC) and obtain data from the active node. More
information on Failover can be found in Intellutions documentation for FIX32 or iFIX.
Although FIX allows a backup SCADA configuration that involves two SCADA servers
and without the use of a View node the interface does not support this configuration. A
complete discussion of SCADA node failover, including configuration procedures can be
found in Appendix D: FIX Redundancy and PI-EDA.
Intellution View Node

NT Operating System
PI-API
Redundant SCADA Nodes

Active
SCADA Node
Backup
SCADA Node
PI Home Node
(NT, Unix or
Open VMS)
PI-FIX Interface
View Node
Software
Architecture of SCADA/View Node Redundancy
Interface Cluster Failover

Interface-level failover is supported through Microsoft clustering. A cluster is composed
of two or more nodes. Each member of the cluster has a copy of the interface installed and
running, with only one node sending data to PI at any given time. Microsoft provides a
Cluster Administrator program which is used for configuration and management of failover
resources. A system failure (hardware or software) on the active cluster node will cause the
Cluster Administrator to initiate a failover. On failover ownership of a cluster resource is
shifted from the node of failure to another available cluster node. In this way we ensure
that the only one cluster node owns the active interface at any given time.
Note that failover activity does not apply with respect to alarm/event message data
collection. If enabled, alarm/event data will be collected on each interface node
independent of cluster failover. However it is strongly recommended that you run a
Table of Contents
separate copy of the interface specifically for collecting this type of data to maximize
performance. A complete discussion of cluster failover operation and configuration can be
found in Appendix C: Cluster Failover.
Microsoft Cluster Sever

Cluster Node
1
Cluster Node 2
Server
PI Home Node
NT Operating System
NT Operating System
(NT, Unix or
Open VMS)
PI-API
PI-API
PI-FIX
Interface
PI-FIX
Interface
View Node
Software
View Node
Software
Remote View or
SCADA Node
Architecture of Interface Cluster Failover
Installation Checklist
This checklist should help you get the interface up and running. The steps should be
followed in the order outlined below.
This should have enough detail to get the interface running quickly by an experienced
installer.
The typical example below is followed by sections of the document that describe these
steps in more detail.
Install the interface (Follow the installation procedure below, including the section on
installing the interface as service).
1. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)
2. Verify that PI-API has been installed.
3. Install the interface.
4. Test the connection between the interface node and the foreign device.
5. Define digital states.
6. Choose a point source. If PI 2 home node, create the point source.
7. Configure PI points.
Location1 is the interface instance as specified in the startup file (/id=#).
Location2 is the I/O type (Input=0, Output=1).
Location3 is not used at this time.
Location4 is the scan class. Event based and output tags should have Location4=0.
Alarm/event-message tags must have Location4=1.
Location5 is not used at this time.
ExDesc is used to specify a trigger tag. Takes the format event=trigger tag.
InstrumentTag is used to specify the NTF address (Node-Tag-Field). For example:
LocalNode,TagX,F_CV
8. Configure performance points.

9. Configure I/O rate tag.
10. Edit startup command file with the ICU or manually.
11. Set interface node clock.
12. Setup security.
13. Start the interface.
14. Verify data.
15. Stop interface, start buffering, start interface.
Interface Installation
OSI recommends that interfaces be installed on API nodes instead of directly on the
PI Server node. An API node is any node other than the PI Server node where the
PI Application Programming Interface (PI-API) has been installed (see the
PI-API Installation Instructions manual). With this approach, the PI Server need not
compete with interfaces for CPU time. The primary function of the PI Server is to archive
data and to service clients that request data.
After the interface has been installed and tested, Bufserv should be enabled on the PIAPI node (once again, see the PI-API Installation Instructions manual). Bufserv is
distributed with the PI-API. It is a utility program that provides the capability to store and
forward events to a PI Server, allowing continuous data collection when communication to
the PI Server is lost. Communication will be lost when there are network problems or when
the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.
In most cases, interfaces on PI-API nodes 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 PI Server node. In this case,
the typical procedure is to install the PI Server as an automatic service and interfaces as
manual services that are launched by site-specific command files when the PI Server is
started. Interfaces that are started as manual services are also stopped in conjunction with
the PI Server by site-specific command files. This typical scenario assumes that Bufserv is
not enabled on the PI Server node. Bufserv can be enabled on the PI Server node so that
interfaces on the PI Server node do not need to be started and stopped in conjunction with
PI, but it is not standard practice to enable buffering on the PI Server node. See the UniInt
End User Document for special procedural information.
Naming Conventions and Requirements

In the installation procedure below, it is assumed that the name of the interface executable
is pi-eda.exe and that the startup command file is called pi-eda.bat.
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, one would typically use
pi-eda1.exe and pi-eda1.bat for interface number 1, pi-eda2.exe and
pi-eda2.bat for interface number 2, and so on. 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 arguments in a file that has the same root name.
Microsoft DLLs
The following Microsoft DLLs are distributed on the installation CD-ROM . The install kit
will copy these files to the winnt\system32 directory only if the files in the
winnt\system32 directory are older than the files on the CD-ROM.
MSVCIRT.DLL
MSVCRT.DLL
MSVCRT40.DLL
MSVCP50.DLL
MSVCP60.DLL
The following additional Microsoft DLLs are also distributed on the CD-ROM . These
DLLs are only used by a debug version of the interface. The install kit will copy these files
to the Winnt\system32 directory only if the files in the winnt\system32 directory are
older than the files on the CD-ROM.
MSVCIRTD.DLL
MSVCRTD.DLL
MSVCP50D.DLL
MSVCP60D.DLL
Interface Directories
The PIHOME Directory Tree
The PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration
file. This pipc.ini file is an ASCII text file, which is located in the WinNT directory. A
typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on the
C: drive. OSI recommends using \pipc as the root directory name. The PIHOME directory
does not need to be on the C: drive.
Interface Installation Directory

Place all copies of the interface into a single directory. The suggested directory is:
PIHOME\interfaces\pi-eda\
Replace PIHOME with the corresponding entry in the pipc.ini file.
Interface Installation Procedure

The PI-EDA interface setup program uses the services of the Microsoft Windows Installer.
Windows Installer is a standard part of Windows 2000. When running on Windows NT 4.0
systems, the PI-EDA setup program will install the Windows Installer itself if necessary.
To install, run the PIEDA_x.x.x.x.exe installation kit.
10
Installing the Interface as an NT Service

The PI-EDA interface service can be created with the PI-Interface Configuration &
Management Utility, or can be created manually.
Installing the Interface Service with PI-Interface Configuration Utility

The PI-Interface Configuration & Management Utility provides a user interface for
creating, editing, and deleting the interface service. The service name will be eda and the
display name will be PI-EDA.
Service Configuration
Service Name
The Service to Add box shows the name of the current interface service. This service name
is obtained from the interface 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. OSIsoft
suggests that the prefix PI- be appended to the beginning of the interface to indicate that
the service is part of the OSI suite of products.
Service Startup Type

The Service Startup Type indicates whether the interface service will start automatically or
need 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.
11
Interface Installation
Generally, interface services are set to start automatically.
Interface Dependencies
The Installed Services list is a list of the services currently installed on this machine.
Services upon which this Interface is dependant should be moved into the Interface
Dependencies list using the Add>> button. For example, if API Buffering is running,
then Bufserv should be selected from the list at the right and added to the list on the left.
When the PI 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 PI interface service will not run.
Note: Please see the PI Log and Operating System Event Logger for messages that
may indicate the cause for any server not running as expected.
Add>>
To add a dependency from the list of Installed Services, select the dependency name, and
click the Add button.
<<Remove
To remove a selected dependency, highlight the service name in the Installed 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.
Create or Remove Interface Service

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 Start / Stop section contains a Start button
and a Stop button
. If this interface
service is not currently installed, these buttons will remain grayed out until the service is
added. If this interface service is running, the Stop button is available. If this service is not
running, the Start button is available.
The status of the Interface service is indicated in the lower portion of the PI-ICU dialog.
12
Installing the Interface Service Manually

One can get help for installing the interface as a service at any time with the command:
pi-eda.exe help
Change to the directory where the pi-eda.exe executable is located. Then, consult the
following table to determine the appropriate service installation command.
NT Service Installation Commands on a PI-API node or a PI Server node
with Bufserv implemented
Manual
service
pi-eda.exe install depend tcpip bufserv
Automatic
service
pi-eda.exe install auto depend tcpip bufserv

NT Service Installation Commands on a PI-API node or a PI Server node
without Bufserv implemented
Manual
service
pi-eda.exe install depend tcpip
Automatic
service
pi-eda.exe install auto depend tcpip
When the interface is installed as a service on the PI Server node and when Bufserv is not
implemented, a dependency on the PI network manager is not necessary because the
interface will spin its wheels until it connects to PI.
Note: Interfaces are typically not installed as automatic services when the interface is
installed on the PI Server node.
Check the Microsoft Windows NT services control panel to verify that the service was
added successfully. One can use the services control panel at any time to change the
interface from an automatic service to a manual service or vice versa .
13
Digital States
For more information regarding Digital States, refer to the PI UDS documentation.
PI 2 Home Node
Digital states are defined by running the Digtl Stat display from the PI menu. The
states must be contiguous for each status type and may be anywhere within the
Digital State Table outside of the range 193 - 320, which is reserved for OSIsoft. The
digital states need to be defined prior to point configuration. The digital state sets
described in the PI 3 sections below should be entered into the PI 2 Digital State Table.
For more information, see the PI UDS documentation.
PI 3 Home Node
Digital State Sets
PI digital states are discrete values represented by strings. These strings are organized in PI
as digital state sets. Each digital state set is a user-defined list of strings, enumerated from
0 to n to represent different values of discrete data. For more information about PI digital
tags and editing digital state sets, see the PI UDS documentation.
An interface point that contains discrete data can be stored in PI as a digital tag. A
digital tag associates discrete data with a digital state set, as specified by the user.
System Digital State Set

Similar to digital state sets is the system digital state set. This set is used for all tags,
regardless of type to indicate the state of a tag at a particular time. For example, if the
interface receives bad data from an interface point, it writes the system digital state
bad input to PI instead of a value. The system digital state set has many unused states
that can be used by the interface and other PI clients.
15
Point Source
The PointSource is a single, unique character that is used to identify the PI point as a point
that belongs to a particular interface. For example, one may choose the letter F to identify
points that belong to the Intellution FIX / iFIX interface. To implement this, one would set
the PointSource attribute to F for every PI Point that is configured for the Random
interface. Then, if one uses /ps=F on the startup-command line of the Random interface,
the Random interface will search the PI Point Database upon startup for every PI point
that is configured with a PointSource of F. Before an interface loads a point, the interface
usually performs further checks by examining additional PI point attributes to determine
whether a particular point is valid for the interface. For additional information, see the /ps
argument.
Case-sensitivity for PointSource Attributes

If the interface is running on a PINet node and the Server node is a PI 3 system, use a
capital letter (or a case-insensitive character such as a number, a question mark, etc.) for
the PointSource attribute when defining points. For all other scenarios, one does not need
to be careful with the case of the PointSource.
In all cases, the point source character that is supplied with the /ps command-line
argument is not case sensitive. That is, /ps=F and /ps=F are equivalent. One only needs
to be careful with the case of the PointSource during point definition, and only if the
interface will be running on a PINet node communicating to a PI 3 Server.
PI 2 Server Nodes
The following point source characters are reserved on PI 2 systems and cannot be used as
the point source character for an interface: C, ?, @, Q, T. Also, if one does not specify
a point source character when creating a PI point, the point is assigned a default point
source character of L. Therefore, it would be confusing to use L as the point source
character for an interface.
Before a PI point with a given point source can be created, the point source character must
be added to the PI 2 point source table. For example, if point source P is not defined in the
PI 2 point source table, a point with a point source of P cannot be created. This prevents
the user from accidentally creating a point with an incorrect point source character.
Defining a Point Source Character in the PI 2 Point Source Table

1. Enter PI by typing the following command from a VMS command prompt:
@pisysexe:pi
2. Select the PointSrc option from the menu.
3. Select New from the menu.
4. Assign a point source next to the Code: field. Also, assign minimum and maximum
values for the Location1 to Location5 attributes.

Location1
Location2
Location3
Location4
Location5
Minimum
-20000000
-20000000
Maximum
98
2000000
256
2000000
17
Point Source
5. Select Save from the menu.
PI 3 Server Nodes
No point source table exists on a PI 3 Server, which means that points can be immediately
created on PI 3 with any point source character. Several subsystems and applications that
ship with PI 3 are associated with default point source characters The Totalizer Subsystem
uses the point source character T, the Alarm Subsystem uses G and @, Random uses R,
RampSoak uses 9, and the Performance Equations Subsystem uses C. Either do not use
these point source characters or change the default point source characters for these
applications. Also, if one does not specify a point source character when creating a
PI point, the point is assigned a default point source character of L. Therefore, it would be
confusing to use L as the point source character for an interface.
18
PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the
PI Data Archive. A single point is configured for each measurement value that needs to be
archived. Use the point attributes below to define what data to transfer.
One PI point (PI tag) must be configured for each FIX field the user wants to read from or
write to. The points can be configured on a PI2 or PI3 home node.
The field names in the table below are consistent with the field names in the PI UDS
documentation. Please refer to the Appendix regarding use of the FixToPI transfer utility to
facilitate in the creation of PI points.
Point Attributes
Tag
A tag is a label or name for a point. Any tag name can be used in accordance to the normal
PI point naming conventions.
PointSource
The PointSource is a single, unique character that is used to identify the PI point as a point
that belongs to a particular interface. For additional information, see the /ps commandline argument and the Point Source section.
PointType
Typically, device point types do not need to correspond to PI point types. 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 PI tags, although the
values will be truncated.
PI 2 Server Nodes
Scaled-real, full-precision real, integer, and digital point types are supported on
PI 2 Servers. For more information on the individual point types, refer to the Data Archive
(DA) section of PI System Manual I.
PI 3 Server Nodes
Float16, float32, int16, int32, digital, string point types are supported on PI 3 Servers. For
more information on the individual point types, see PI Data Archive for NT and UNIX.
Location1
This parameter is used to specify the interface number, which corresponds to the /id=#
flag in the PI-EDA#.bat file. Valid interface numbers are integer values 1 to 99,
inclusive.
When running multiple copies of the interface, this allows all instances to share the same
point source but be differentiated by the interface id. In addition each message the interface
19
writes to the pipc.log file will have a prefix that includes the id. The following message is
from an interface with /id=1;
17-Jun-03 12:16:59
PI-EDA 1> Version 2.2.0.0 of PI-EDA Interface.
Note that the message prefix uses the format PI-EDA #> where # corresponds to the /id
startup parameter.
Location2
This parameter identifies the direction of data flow for the point.
Inputs
Location2 = 0
Defines tag as an input (data goes from Intellution to PI).
Input Update Methods

Values are requested from FIX at a given frequency or after an "event," depending on the
configuration of the input tag.
Configuration 1: Values are requested at a given frequency, defined by the associated scan
class. The scan class is defined through the Location4 attribute. Configuration 1 is the
most efficient update method and enabled if no "triggertag" is specified the input tags
extended descriptor.
Configuration 2: Values are requested after an event is detected for a "trigger tag." The
trigger tag is specified in the input tags extended descriptor. An event occurs whenever a
value reaches the snapshot of the trigger tag.
For both configuration 1 and configuration 2, IO TIMEOUT is written to the input tag if
a communication error occurs.
Outputs
Location2 = 1
Defines tag as an output (data goes from PI to Intellution).
Output Update Methods

Outputs are sent to FIX only upon an event. An event is triggered in one of two ways,
depending upon the configuration of the output tag.
Configuration 1 (Recommended): 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
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. 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 written to the output point. The
20
advantage of using a source tag is you have a record of the output value sent to Intellution
(via the source tag value) and an indication of whether or not the write was successful (via
the output tag value).
Configuration 2: 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.
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.
When do "events" occur? An event is defined as a value sent to PI that has a timestamp
that is more current than what was previously recorded. This event can have the same
value because its the timestamp that determines whether or not the value is a new event.
For example, the snapshot of a SourceTag tag is 51 and the exception maximum time is set
to the default 600 seconds. This means that is a new event does not get sent to the source
tag, after 600 seconds one will be forced to the snapshot. This will trigger an output value
to be sent to Intellution. It may be desired to disable exception max time for output points
and output source points by setting exception max time to 0.
Location3
Location3 is not used by this interface.
Location4
Location4 defines the scan class for the PI point. The scan class defines the frequency at
which input points are scanned for new values. For more information, see the description
of the /f flag in the section called The Startup Command File.
Trigger-Based Inputs and Output Points

Location4 should be set to zero for these points.
Note on Alarm/Event Message Data Collection

If alarm/event message data collection is enabled scan class 1 is used for alarm/event
message data collection EXCLUSIVELY. All tags with Location4=1 will be used for this
purpose.
Performance Considerations
The absolute limit on resolution is 0.01 second. With high data resolution (fast scan rates)
users should monitor CPU loading. The higher the data resolution, the more CPU time the
interface will need.
To optimize performance, tags belonging to a particular node should be grouped into the
same scan classes for more efficient polling. By keeping all tags for individual nodes
within the same group, EDA does not have to poll multiple nodes in order to read values
for a single scan. Note that event-triggered tags take much longer to process since a
separate group is defined for each event tag, which is less efficient than scan based
updates.
Location5
Not used by this interface.
21
InstrumentTag
InstrumentTag is used to specify the "node,tag,field" (NTF) identifier. The node references
the Intellution node name which reads data for the specified tag. Tag references the tag
name within the specified node, and field defines the type of data this tag references. The
NTF identifier is used to map PI points to the corresponding Intellution point.
The following table shows the field values to obtain current values for given data types.
Intellution Data Type
Analog or Integer
Field Value
F_CV
Possible PI Point Types

Float, Integer or Digital
Digital or Boolean
D_CV
Digital or Integer
Multistate Digital
M_CV
Digital or Integer
String
A_CV
String
The interface has the ability to obtain a wide range of data for each block type. A complete
listing of the field options for each Intellution block type see the Intellution Dababase
Manger Online Help, Block Field Reference section.
The InstrumentTag attribute requires the following format;
Node,Tag,Field
The following table provides examples of how to configure the InstrumentTag given the
Intellution node, tag name and block type.
Intellution Node
PLANT1
Tag Name
FLOW_PV
Block Type
Analog Input
PI InstrumentTag Definition
PLANT1,FLOW_PV,F_CV
PLANT1
VALVE_PV
Digital Input
PLANT1,VALVE_PV,D_CV
PLANT2
CONTROL_SP
Multistate Digital Input
PLANT2,CONTROL_SP,M_CV
PLANT2
COMMENT
String
PLANT2,COMMENT,A_CV
Note that the interface is not limited to the block types listed in the above table.
The InstrumentTag is limited to 32 characters. If the NTF definition exceeds this limit the
Extended Descriptor field can be used for defining the Node and Field values. If the NTF
entry in the InstrumentTag is not complete, the ExDesc will be checked. If the full NTF is
specified in the instrument tag, then the interface does NOT check the ExDesc field for
additional information - the interface already has all the information required. Utilizing the
ExDesc for this purpose means the InstrumentTag field will contain the tag name and the
field and node definitions are defined in the ExDesc.
SourceTag
A SourceTag is used in conjunction with an output tag. An output tag has Location2 set to
1.
22
ExDesc
The extended descriptor (ExDesc) is used to configure input tags that are event based
updated. For these points the trigger tag is specified using the following format:
EVENT=[trigger tag]
By specifying a trigger tag, the associated input tag is updated after an "event" instead at a
given frequency. See the Location4 description for essential details on event based input
tags.
The extended descriptor can also be used for defining the Node and Field definitions when
the NTF definition exceeds 32 characters (see InstrumentTag description for more details).
The following format should be used for defining the Node and Field attributes.
NODE=[node name], FIELD=[field name]
All three (event=, node=, and field=) can be defined in the extended descriptor. The
following example shows the syntax for a tag specifying a trigger tag along with the node
and field names (the order that the parameters are defined is not important):
EVENT=[trigger tag],NODE=[node id],FIELD=[field id]
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, SCAN OFF will be written to the PI point. If the scan attribute is
changed from 1 to 0 while the interface is running, SCAN OFF will also be written to the
PI point after the point edit is detected by the interface.
There is one other situation, which is independent of the Scan attribute, where UniInt will
write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited
so that the point is no longer valid for the interface, the point will be removed from the
interface, and SCAN OFF will be written to the point. For example, if the PointSource of a
PI point that is currently loaded by the interface is changed, the point will be removed from
the interface and SCAN OFF will be written to the point.
The Scan field is used by the interface to determine whether or not the tag is to be scanned.
This allows the user to turn a tag on or off while the interface is on-line.
Shutdown
PI 2 Server Nodes
The Shutdown attribute is not used if the server node is a PI 2 system. For information on
configuring shutdown events for PI 2, see Data Archive (DA) section 4.2.3 of
PI System Manual I.
PI 3 Server Nodes
The shutdown attribute is used only if the server node is a PI 3 system.
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 PI points when PI 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
23
15 minutes in the event of a power failure. For additional information on shutdown events,
refer to PI Data Archive for NT and UNIX.
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
/stopstat command-line argument is specified.
One can disable SHUTDOWN events from being written to PI when PI is restarted by
setting the Shutdown attribute to 0 for each point. Alternatively, one can change the default
behavior of the PI Shutdown Subsystem to write SHUTDOWN events only for PI points
that have their Shutdown attribute set to 0. To change the default behavior, edit the
\PI\dat\Shutdown.dat file, as discussed in PI Data Archive for NT and UNIX.
Bufserv
It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility
program that provides the capability to store and forward events to a PI Server, allowing
continuous data collection when the Server is down for maintenance, upgrades, backups,
and unexpected failures. That is, when PI is shutdown, Bufserv will continue to collect
data for the interface, making it undesirable to write SHUTDOWN events to the PI points
for this interface.
24
Performance Point Configuration

One can configure performance points to monitor the amount of time in seconds that an
interface takes to complete a scan for a particular scan class. The closer the scan
completion time is to 0 seconds, the better the performance. The scan completion time is
recorded to millisecond resolution
Configuring Performance Points with PI-ICU

The PI-Interface Configuration & Management Utility (PI-ICU) provides a user interface
for creating and managing Performance Points.
To create or delete a Performance Point, right mouse click the line belonging to the tag to
be created, and click Create or Delete. If a tag already exists, the status is marked
Created, the Delete option will be enabled. If a tag does not exist, the status is marked
Not Created or Deleted, and the Create option is enabled.
The Performance Points are created with the following PI attribute values:
Attribute
Details
Tag
Tag name that appears in the list box
Point Source
Point Source for tags for this interface, as specified on the first tab
Compressing
Off
ExcMax
Descriptor
Interface name + " Scan Class # Performance Point"
Status
The Status column in the Performance Points table indicates whether the Performance
Point exists for the scan class in column 2. If a Performance Point does exist, a status of
Created is displayed. If the Performance Point does not exist, a status of Not Created
25
is displayed. If a Performance Point exists, and is deleted, a status of Deleted is

displayed.
Scan Class
The Scan Class column indicates which scan class the Performance Point in the Tagname
column belongs to. There will be one scan class in the Scan Class column for each scan
class listed in the Scan Classes combo box on the Uniint Parameters tab.
Tagname
The Tagname column holds the Performance Point tag name.
Configuring Performance Points Manually

Performance point configuration is the same on all operating system platforms.
Performance points are configured as follows.
Set the extended descriptor to:
PERFORMANCE_POINT
or to:
PERFORMANCE_POINT=interface_id
where interface_id corresponds to the identifier that is specified with the /id flag on
the startup command line of the interface. The character string PERFORMANCE_POINT is
case insenstive. The interface_id does not need to be specified if there is only one copy
of an interface that is associated with a particular point source.

Set Location4 to correspond to the scan class whose performance is to be monitored. For
example, to monitor scan class 2, set Location4 to 2. See the /f flag for a description of
scan classes.
Set the PointSource attribute to correspond to the /ps flag on the startup command line of
the interface.
Set the PointType attribute to float32.
26
I/O Rate Tag Configuration

An I/O Rate point can be configured to receive 10-minute averages of the total number of
exceptions per minute that are sent to PI by the interface. An exception is a value that has
passed the exception specifications for a given PI point. Since 10-minute averages are
taken, the first average is not written to PI until 10 minutes after the interface has started.
One I/O Rate tag can be configured for each copy of the interface that is in use.
Monitoring I/O Rates on the Interface Node

For NT and UNIX nodes, the 10-minute rate averages (in events/minute) can be monitored
with a client application such as ProcessBook. For Open VMS nodes, the rate
(events/minute) can be monitored with the PISysExe:IOMonitor.exe program or with
another client program such as Process Book. The IOMonitor program is discussed on
page DA-71 of PI System Manual I.
Configuring I/O Rate Tags with PI-ICU

The PI-Interface Configuration & Management Utility (PI-ICU) provides a user interface
for creating and managing IORates Tags.
PI-ICU currently allows for one I/O Rate tag to be configured for each copy of the
interface that is in use. Some interfaces allow for multiple I/O Rates tags.
Enable IORates for this Interface

The Enable IORates for this interface check box enables or disables IORates for the
current interface. To disable IORates for the selected interface, uncheck this box. To enable
IORates for the selected interface, check this box.
Tag Status
The Tag Status column indicates whether the IORates tag exists in PI. The possible states
are:
Created This status indicates that the tag exist in PI
Not Created This status indicates that the tag does not yet exist in PI
Deleted This status indicates that the tag has just been deleted
Unknown This status indicates that the ICU is not able to access the PI Server
In File
The In File column indicates whether the IORates tag listed in the tag name and the event
counter is in the IORates.dat file. The possible states are:
27
Yes This status indicates that the tag name and event counter are in the IORates.dat
file.
No This status indicates that the tag name and event counter are not in the
IORates.dat file.
Event Counter
The Event Counter correlates a tag specified in the iorates.dat file with this copy of
the interface. The command line equivalent is /ec=x, where x is the same number that is
assigned to a tag name in the iorates.dat file.
Tagname
The tag name listed under the Tagname column is the name of the IORates tag.
Right Mouse Button Menu Options

Create
Create the suggested IORates tag with the tag name indicated in the Tagname column.
Delete
Delete the IORates tag listed in the Tagname column.
Rename
Allows the user to specify a new name for the IORates tag listed in the Tagname column.
Add to File
Adds the tag to the IORates.dat file with the event counter listed in the Event Counter
Column.
Search
Allows the user to search the PI Server for a previously defined IORates tag.
Configuring I/O Rate Tags Manually

There are two configuration steps.
Configuring the PI Point on the PI Server

PI 2 Server Nodes
A listing of the I/O Rate Tags that are currently being monitored can be obtained with the
command:
@PISysDat:IOMonitor.com
Create an I/O Rate Tag using one of the existing I/O Rate Tags as a template.
PI 3 Server Nodes
Create an I/O Rate Tag with the following point attribute values.
28
Attribute
Value
PointSource
PointType
float32
Compressing
ExcDev
Configuration on the Interface Node

For the following examples, assume that the name of the PI tag is pieda001, and that the
name of the I/O Rate on the home node is pieda 001.
Edit/Create a file called iorates.dat in the PIHOME\dat directory. The
PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the
pipc.ini file, which is located in the \WinNT directory. If both are specified, the
PIPCSHARE entry takes precedence.
Since the PIHOME directory is typically C:\PIPC, the full name of the iorates.dat
file will typically be C:\PIPC\dat\iorates.dat.
Add a line in the iorates.dat file of the form:
pieda001, x
where pieda001is the name of the I/O Rate Tag and x corresponds to the first
instance of the /ec=x flag in the startup command file. x can be any number between
2 and 34 or between 51 and 200, inclusive. To specify additional rate counters for
additional copies of the interface, create additional I/O Rate tags and additional entries
in the iorates.dat file. The event counter, /ec=x, should be unique for each copy
of the interface.
Set the /ec=x flag on the startup command file of the interface to match the event counter
in the iorates.dat file.
The interface must be stopped and restarted in order for the I/O Rate tag to take effect. I/O
Rates will not be written to the tag until 10 minutes after the interface is started.
29
Startup Command File

Configuring Startup Parameters with PI-ICU Control
The PI-EDA interface on Windows has an ICU Control that will aid in configuring the PIEDA interface startup command file.
Figure 1: Intfix Configuration Menu for the PI-ICU Utility
General
Startup delay (seconds)
Enabling the check box allows you to specify how many seconds the interface waits on
startup before connecting to Intellution. The default is 120. The delay allows the Intellution
software to fully start before trying to connect.
Enable Local System Time

The default behavior of the interface is to use the PI server system time for the data
timestamp. Enable this check box to have the interface use the local interface node system
time for timestamp source.
This option must be used with caution. If the local system time is ahead of the PI server
the data may be rejected. PI discards future data, which is defined as any event more
than 10 minutes ahead of the PI server time. This option should only be used if there is a
compelling reason to do so.
Cluster Failover
The interface redundancy is supported through Microsoft Cluster server. See Appendix C:
Cluster Failover for a complete discussion on operation requirements and configurations.
Enable this check box to if you wish to use failover. Upon enabling this box the failover
configuration options will become active.
31
Cluster Mode:
The interface has the ability to operate with a preference for running on a specified cluster
node if at all possible. This is referred to as running with Primary bias. This behavior
maybe preferred if one of the cluster nodes has proven to be more stable or otherwise
performs better than the others.
If Primary bias is selected using the drop down list, then the This node is the : option will
be enabled. At this point you must specify whether this cluster node is the primary or
backup. Note it is critical that only one cluster node be specified as the primary. If more
than one cluster node is specified as the primary node they will compete for ownership of
the cluster group resource, sending the interface into an endless loop of failovers.
A cluster mode of No bias means the interface does not attempt to control which node runs
the active interface. As a result whichever node owns the cluster resource on startup will be
the active interface. This will remain so until there is a problem that causes failover or a
user uses the Cluster Manger to intentionally manipulate the configuration. The default
value for this option is No Bias.
This node is the:

This option is enabled when Primary bias is specified for the Cluster Mode:. In this
configuration you must specify whether the current node is the primary or backup node for
failover operation. The default value for this option is Backup.
Failover mode:
The interface has the option of running in either warm or hot failover mode. This behavior
determines whether or not an interface running as a backup will query Intellution for point
updates.
Warm failover mode means the interface does not query for point updates when operating
as the backup node. Hot failover mode tells the interface is should query Intellution for
point updates at all times, but send them only when active.
The advantage of running in hot failover mode is you minimize the risk of missing data on
failover. However to minimize loading on inactive cluster nodes we recommend running in
warm failover mode. The default value for this option is Warm.
Resource number for APIOnline :

The resource number is used to indicate the name of the apionline cluster group resource
for the interface. This number will be appended to apionline and used for initialization on
interface startup. For example, if you enter a value of 1, the interface will look for
apionline1 as the cluster group resource. A negative number tells the interface that the
resource has been defined as simply apionline. A procedure for creating cluster group
resources can be found in the section Group and Resource Creation Using Cluster
Administrator.
Active interface node tag :

A PI string tag can be specified to receive the name of the node where the active interface
is running. The button to the right of this option can be used to launch a PI tag search for
selecting the desired tag.
The active cluster tag should be configured as follows:
Table 1: Active Cluster Tag Configuration
32
Attribute
Value
PointSource
PointType
string
Compressing
ExcDev
In addition to receiving the name of the active interface node this tag will also receive
shutdown events whenever the interface is stopped on any of the cluster nodes. The
shutdown event will also contain the name of the machine in the following format;
Shutdown hostname
Alarm/Event Messages
Note that when alarm/event message data collection is enabled, all tags belonging to scan
class one will be used for this purpose in addition to the PI string tag (if specified). For a
complete discussion on alarm/event message data collection see ????????.
It is recommended that a separate copy of the interface be ran specifically for the purpose
of collecting alarm/event message data.
Enable Alarm/Event Msg Data

The check box allows you to configure the interface to collect alarm/event message data.
Once this check box is active it will enable the radio buttons for specifying which
WUSERQ to query. The remaining alarm/event message configuration options will be
enabled after selecting a WUSERQ.
String Position for Alarm/Event Data

In order to collect alarm/event data on a tag by tag basis, the string position and length of
the data with in the message string must be specified.
Refer to the alarm common message format configuration menu accessed through the
Intellution SCADA/View node software package.
33
Figure 2: Intellution Alarm Message Format Configuration Menu
Using Figure 2 as an example, the starting string position is 68 and the data string length is
13. The starting string position is calculated by adding the string length for Date, Time,
Node, Tagname and Alarm Type. The Column Order does not change this calculation as
the interface receives the format as specified by within the Columns menu, the Column
Order is of no consequence for the interface.
String Tag for All Alarm/Event Messages

The interface can be configured to send all alarm/event message strings to a single PI
string tag. This string tag must have the following configurations:
Table 2: Alarm/Event String Tag Configuration
Attribute
Value
PointSource
PointType
string
Compressing
ExcDev
Debug Levels
The interface has the option to enable debug messaging for specific operations. Selecting
max debug level enables messaging for all specific operations plus additional messaging.
Click on the appropriate check box to enable desired level of debug messaging. Note that
34
enabling point checking will slow interface startup proportional to the number of points
(more points means slower interface startup).
Additional Arguments
The additional arguments section is provided for any other parameters that are not directly
configurable from the Intfix ICU Control.
Command Line Parameters

If the Interface Configuration Utility is not used to configure the startup parameters, the
following explains the parameters and their usage. For convenience, the arguments are
defined in a startup command file called PI-EDA#.bat. A sample PI-EDA#.bat file is
included on the installation disks. The command line in the PI-EDA#.bat file must be on
a single line and cannot exceed the 255 character limit.
For NT, command file names have a .bat extension. The NT continuation character (^)
allows one to use multiple lines for the startup command. The maximum length of each
line is 1024 characters (1 kilobyte). The number of flags is unlimited, and the maximum
length of each flag is 1024 characters.
Note: The UniInt End User Document includes details about other command line
parameters which may be useful.
The following is a brief description of interface startup parameters organized by

functionality. At the end of this list is a table listing alphabetically each switch along with a
detailed description of its usage.
General
/HOST
Domain name or IP address of your PI server, and its port number. For
example /host=piserver:5450. PI3 servers use port 5450, PI2 uses 545.
/PS
The point source for the interface.
/ID
Interface instance identifier. The interface uses this number to identify

which tags belong to it when running more than one instance of the
interface. This number is also used as a prefix for messages written to the
pipc.log file. For example, if /id=1 is used messages in the pipc.log will
use this prefix PI-EDA 1> .
/W
Startup delay. Time in seconds the interface waits on startup before

connecting to Intellution allowing it to fully start.
/EC
IORate tag identifier. The interface calculates the number of events per
minute sent to PI and updates this tag every 10 minutes.
Alarm/Event Msg Data Collection

/EM
Enable data collection for alarm/event messages. When specified all tags
belonging to scan class 1 will be used to record alarm data on a tag for tag
basis.
/QN
Intellution WUSERQ to query for alarm/event message data (either /qn=1

for WUSERQ1 or /qn=2 for WUSERQ2).
35

/C
Used to indicate the string position for data within the alarm/event
message (/c=[start]:[length]).
/AL
PI string tag to receive all alarm/event messages.
Interface Cluster Failover

/FO
Enable Microsoft cluster failover support.
/RN
Used to indicate the APIOnline cluster resource name.
/CM
Specifies primary node bias (/cm=0) or no bias (/cm-1) for failover

operation.
/PR
For primary node bias, indicates whether this is the primary (/pr=0) or
backup (/pr=1) cluster node.
/FM
Specifies hot (/fm=0) or warm (/fm=1) failover mode.
/CN
PI string tag to receive the name of the active cluster node.
Debug Messaging
/DB
1 Maximum debug messaging

2 Point checking on startup/edits
3 Input data
4 Ouput data
5 Alarm/event message data collection
6 Interface cluster failover
Complete Alphabetic Parameter Listing

Parameter
Description
/al=[tagname]
When alarm/event data collection is enabled you have the

option of writing all events to a PI string tag. This parameter
specifies that tag. This tag requires the following
configurations:
Alarm/Event String Tag Configuration
Optional
*Used in conjuntion
with /em
/c=[start]:[length]
Optional
*Used in conjuntion
with /em
36
Attribute
Value
PointSource
PointType
string
Compressing
ExcDev
In order to collect alarm/event data on a tag by tag basis, the

string position and length of the data with in the message string
must be specified.
Refer to the alarm common message format configuration menu
accessed through the Intellution SCADA/View node software
package.
Parameter
Description
Figure 2: Intellution Alarm Message Format Configuration

Menu
Using Figure 2 as an example, the starting string position is 68

and the data string length is 13 (/c=68:13). The starting string
position is calculated by adding the string length for Date,
Time, Node, Tagname and Alarm Type. The Column Order
does not change this calculation as the interface receives the
format as specified by within the Columns menu, the Column
Order is of no consequence for the interface.
/cm=[0 or 1]
Optional
Cluster mode, used for cluster failover. Specifies whether the

interface has a bias toward running on the primary node
(/CM=0) or no bias (/CM=1).
*Used in conjuntion
with /fo
Default=1
/cn=[tagname]
Optional
*Used in conjuntion
with /fo
When cluster failover is enabled, a PI string tag can be

specified to receive the name of the node where the active
interface is running. The active cluster tag should be configured
as follows:
Active Cluster Tag Configuration
Attribute
Value
PointSource
PointType
string
Compressing
37

Parameter
Description
ExcDev
In addition to receiving the name of the active interface node

this tag will also receive shutdown events whenever the
interface is stopped on any of the cluster nodes. The shutdown
event will also contain the name of the machine in the following
format; Shutdown hostname
/db=#
or
/db=#,#,...
Optional
The interface has the option to enable debug messaging for

specific operations.
Debug options:
1 Max debug message level.
2 Point checking on startup and tag edits. Note this
will slow interface startup proportional to the number
of points (more tags means slower startup).
3 Input data.
4 Output data.
5 Alarm/event message data collection.
6 Cluster failover.
/ec=x
Optional
The first instance of the /ec flag on the command line is used
to specify a counter number, x, for an I/O Rate point. If x is
not specified, then the default event counter is 1. Also, if the
/ec flag is not specified at all, there is still a default event
counter of 1 associated with the interface. If there is an I/O
Rate point that is associated with an event counter of 1, each
copy of the interface that is running without /ec=x explicitly
defined will write to the same I/O Rate point. This means that
one should either explicitly define an event counter other than
1 for each copy of the interface or one should not associate
any I/O Rate points with event counter 1. Configuration of I/O
Rate points is discussed in the section called I/O Rate Tag
Configuration, p. 27.
For interfaces that run on NT nodes, subsequent instances of
the /ec flag may be used by specific interfaces to keep track
of various input or output operations. One must consult the
interface-specific documentation to see whether subsequent
instances of the /ec flag have any effect. Subsequent
instances of the /ec flag can be of the form /ec*, where * is
any ASCII character sequence. For example, /ecinput=10,
/ecoutput=11, and /ec=12 are legitimate choices for the
second, third, and fourth event counter strings.
/em
Optional
Enable data collection for alarm/event messages. When

specified all tags belonging to scan class 1 will be used to
record alarm data on a tag for tag basis. In addition the
interface can be configured to send all alarm/event messages
to a single PI string tag (/al=[tagname]).
The WUSERQ used for alarm/event data collection is
specified using the /qn switch.
38
Parameter
Description
/f=SS
or
/f=SS,SS
or
/f=HH:MM:SS
or
/f=HH:MM:SS,hh:mm:ss
The /f flag 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.
Required for reading scanbased inputs
Each instance of the /f flag on the command line defines a

scan class for the interface. There is no limit to the number of
scan classes that can be defined. The first occurrence of the
/f flag on the command line defines the first scan class of the
interface, the second occurrence defines the second scan
class, and so on. PI Points are associated with a particular
scan class via the Location4 PI Point attribute. For example,
all PI 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 was started at
05:06:06, the first scan would be at 05:06:10, the second scan
would be at 05:07:10, 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 called
Performance Point Configuration for more information on
skipped or missed scans.
Sub-second Scan Classes
One can also specify sub-second scan classes on the
command line such as
/f=0.5 /f=0.1
where the scanning frequency associated with the first scan
39

Parameter
Description
class is 0.5 seconds and the scanning frequency associated
with the second scan class is 0.1 seconds.
Similarly, sub-second scan classes with sub-second offsets
can be defined, such as
/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 NT and/or UNIX. Previously, wall clock scheduling was
possible, but not across daylight savings time. For example,
/f=24:00:00,08:00:00 corresponds to 1 scan a day
starting at 8 AM. However, after a Daylight Savings 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 savings time),
one should 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.
/fo
Enables cluster failover support.
Optional
A complete discussion on failover operation and configuration

can be found in Appendix C: Cluster Failover.
/fm=[0 or 1]
The interface has the option of running in either warm or hot

failover mode. This behavior determines whether or not an
interface running as a backup will query Intellution for point
updates.
Optional
*Used in conjuntion
with /fo
Default=1
Warm failover mode means the interface does not query for
point updates when operating as the backup node. Hot failover
mode tells the interface is should query Intellution for point
updates at all times, but send them only when active.
The advantage of running in hot failover mode is you minimize
the risk of missing data on failover. However to minimize
loading on inactive cluster nodes we recommend running in
/h
Running the interface from a command prompt with /h as the

only parameter causes the interface to print its version and a
list of parameters essentially an on-line summary of this
table.
/help or /?
Running the interface from a command prompt with /help or

/? as the only parameter causes UniInt to print its version, a
list of UniInt Service configuration parameters, and a list of
UniInt generic interface parameters.
/host=host:port
The /host flag is used to specify the PI Home node. Host is

the IP address of the PI Sever node or the domain name of
the PI Server node. Port is the port number for TCP/IP
communication. The port is always 5450 for a PI 3 Server and
545 for a PI 2 Server. It is recommended to explicitly define
the host and port on the command line with the /host flag.
Nevertheless, if either the host or port is not specified, the
Optional
40
Parameter
Description
interface will attempt to use defaults.
Defaults:
The default port name and server name is specified in the
pilogin.ini or piclient.ini file. The piclient.ini
file is ignored if a pilogin.ini file is found. Refer to the PIAPI Installation Instructions manual for more information on
the piclient.ini and pilogin.ini files.
Examples:
The interface is running on an API node, the domain name of
the PI 3 home node is Marvin, and the IP address of Marvin is
206.79.198.30. Valid /host flags would be:
/host=marvin
/host=marvin:5450
/host=206.79.198.30
/host=206.79.198.30:5450
/id=x
The /id flag 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.
UniInt always uses the /id flag in the fashion described above.
This interface also uses the /id flag to identify a particular
interface copy number that corresponds to an integer value
that is assigned to Location1. For this interface, one should
use only numeric characters in the identifier. For example,
/id=1.
/ls
Optional
The default behavior of the interface is to use the PI server

system time for the data timestamp. Enable this check box to
have the interface use the local interface node system time for
timestamp source.
This option must be used with caution. If the local system time
is ahead of the PI server the data may be rejected. PI discards
future data, which is defined as any event more than 10
minutes ahead of the PI server time. This option should only be
used if there is a compelling reason to do so.
/pr=[0 or 1]
Optional
When cluster failover is enabled, and the cluster mode is set for
primary bias this switch is used to designate the local node as
primary (/pr=0) or backup (/pr=1).
*Used in conjuntion
with /fo and /cm=0
Default=1
/ps=x
Required
The /ps flag specifies the point source for the interface. x is
not case sensitive and can be any single character. For
example, /ps=P and /ps=p are equivalent.
The point source that is assigned with the /ps flag
corresponds to the PointSource attribute of individual PI
Points. The interface will attempt to load only those PI points
with the appropriate point source.
41

Parameter
Description
/qn=n
When alarm/event message data collection is enabled, this

switch is used to specify whether WUSERQ1 (/qn=1) or
WUSERQ2 (/qn=2) is used for the data source.
Optional
*Used in conjuntion
with /em
Default: 1
/rn=#
Optional
*Used in conjuntion
with /fo
/stopstat
or
/stopatat=
digstate
Default:
/stopstat=
Intf Shut
Optional
The resource number is used to indicate the name of the

apionline cluster group resource for the interface. This number
will be appended to apionline and used for initialization on
interface startup. For example, if you enter a value of 1, the
interface will look for apionline1 as the cluster group resource.
A negative number tells the interface that the resource has been
defined as simply apionline. A procedure for creating cluster
group resources can be found in the section Group and
Resource Creation Using Cluster Administrator.
If the /stopstat flag is present on the startup command line,
then the digital state Intf Shut will be written to each PI Point
when the interface is stopped.
If /stopstat=digstate is present on the command line,
then the digital state, digstate, will be written to each PI
Point when the interface is stopped. For a PI 3 Server,
digstate must be in the system digital state table. For a
PI 2 Server, where there is only one digital state table
available, digstate must simply be somewhere in the table.
UniInt uses the first occurrence in the table.
If neither /stopstat nor /stopstat=digstate is
specified on the command line, then no digital states will be
written when the interface is shut down.
Examples:
/stopstat=Intf Shut
The entire parameter is enclosed within double quotes when
there is a space in digstate.
/sio
Optional
The /sio flag stands for suppress initial outputs. The flag
applies only for interfaces that support outputs. If the /sio flag
is not specified, the interface will behave in the following
manner.
When the interface is started, the interface determines the
current Snapshot value of each output tag. Next, the interface
writes this value to each output tag. In addition, whenever an
individual output tag is edited while the interface is running,
the interface will write the current Snapshot value to the
edited output tag.
This behavior is suppressed if the /sio flag is specified on the
command line. That is, outputs will not be written when the
interface starts or when an output tag is edited. In other
words, when the /sio flag is specified, outputs will only be
written when they are explicitly triggered.
42
Parameter
Description
/w=n
This specifies how many seconds the interface waits for the
FIX software to come up completely since the initial startup
before loading tags.
Optional
Default: 120
Sample pi-eda.bat File

rem
rem pi-eda.bat
rem
rem Fix interface startup parameters
rem
pi-eda /host=localhost:5450 /ps=f /id=1 /w=120 /ec=2 /f=00:00:01 ^
/em /c=67:13 /al=VIEWNODE1.ALARMS /q
43
Interface Node Clock

The correct settings for the time and time zone should be set in the Date/Time control
panel. If local time participates in Daylight Savings, from the control panel, configure the
time to be automatically adjusted for Daylight Savings Time. The correct local settings
should be used even if the interface node runs in a different time zone than the PI Server
node.
Make sure that the TZ environment variable is not defined. The currently defined
environment variables can be listed by going to Start | Settings | Control Panel, double
clicking on the system icon, and selecting the environment tab on the resulting dialog box.
Also, make sure that the TZ variable is not defined in an autoexec.batfile. When
the TZ variable is defined in an autoexec.bat file, the TZ variable may not appear as
being defined in the System control panel even though the variable is defined. Admittedly,
autoexec.bat files are not typically used on NT, but this does not prevent a rogue user
from creating such a file and defining the TZ variable unbeknownst to the System
Administrator.
45
Security
If the home node is a PI 3 Server, the PI Firewall Database and the PI Proxy Database
must be configured so that the interface is allowed to write data to the PI Data Archive.
See Modifying the Firewall Database and Modifying the Proxy Database in the
PI Data Archive Manual.
Note that the Trust Database, which is maintained by the Base Subsystem, replaces the
Proxy Database used prior to PI version 3.3. The Trust Database maintains all the
functionality of the proxy mechanism while being more secure.
See Trust Login Security in the chapter PI System Management of the PI Universal
Data Server System Management Guide.
If the home node is a PI 2 Server, the read/write permissions should be set appropriately in
the pisysdat:piserver.dat file on the PI 2 home node. For more information on
setting permissions on PI 2, see the pibuild:piserver.txt file on the PI 2 home node.
If the interface cannot write data to a PI 3 Server because it has insufficient privileges, a
10401 error will be reported in the pipc.log file. If the interface cannot send data to a
PI2 Serve, it writes a 999 error. See the section Appendix A: Error and Informational
Messages for additional information on error messaging, p.Error: Reference source not
found.
47
Starting / Stopping the Interface

This section describes starting and stopping the interface once it has been installed as a
service. See the UniInt End User Document to run the interface interactively.
Starting Interface as a Service

If the interface was installed a service, it can be started from the services control panel or
with the command:
pi-eda.exe start
A message will be echoed to the screen informing the user whether or not the interface has
been successfully started as a service. Even if the message indicates that the service started
successfully, make sure that the service is still running by checking in the services control
panel. There are several reasons that a service may immediately terminate after startup .
One is that the service may not be able to find the command-line arguments in the
associated .bat file. For this to succeed, the root name of the .bat file and the .exe file
must be the same, and the .bat file and the .exe file must be in the same directory. If the
service terminates prematurely for whatever reason, no error messages will be echoed to
the screen. The user must consult the pipc.log file for error messages. See the section
Appendix A: Error and Informational Messages, for additional information.
Stopping Interface Running as a Service

If the interface was installed a service, it can be stopped at any time from the services
control panel or with the command:
pi-eda.exe stop
The service can be removed by:

pi-eda.exe remove
49
Buffering
For complete information on buffering, please refer to the Intellution Fix DMACS (FIX32)
/ Dynamics (iFIX).
PI-API Node buffering consists of a buffering process which runs continuously on the
local node, a PI-API library whose calls can send data to this buffering process, and a
utility program for examining the state of buffering and controlling the buffering process.
Configuring Buffering with PI-ICU

Buffering is enabled through the PI-Interface Configuration Utilitys Tools>API
Buffering menu. Unless buffering is explicitly enabled, the PI-API will not buffer data,
sending data directly to the home node.
The API Buffering dialog allows the user to view and configure the parameters
associated with the API Buffering (Bufserv) process. The user can start and stop the API
Buffering process from the Service tab:
Service Tab
The Service tab allows for some API Buffering service configuration. For further
configuration changes, use the Services applet.
Service Name
The Service name displays the name of the API Buffering Service.
Display Name
The Display name displays the full name associated with the API Buffering service.
51
Log On As
Log on as indicates the Windows user account under which the API Buffering service is
setup to start automatically on reboot, or manually. To modify the user account or
password under which Bufserv runs, use the Microsoft Windows Services applet.
Dependencies
The Dependencies lists the Windows services on which the API Buffering service is
dependent.
Service Startup Type

The Startup Type indicates whether the API Buffering service is setup to start
automatically on reboot or manually on reboot, or is disabled.
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, the API Buffering service is set to start automatically.
Start / Stop Service

The Start / Stop buttons allow for the API Buffering service to be started and stopped.
After a change is made to any of the settings on the Settings tab, the Save button must be
clicked, and then the service must be stopped and restarted for the changes to be picked up
by Bufserv.
Settings Tab
The Settings tab allows for configuration of the 7 configurable settings used by API
Buffering. Default values are used if no other value is provided.
52
Enable API Buffering

Enables the API Buffering feature.
Maximum File Size

Maximum buffer file size in kilobytes before buffering fails and discards events. Default
value is 100,000. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click
the Apply button.
Send Rate
Send rate is the time to wait between sending up to MAXTRANSFEROBJS to the server
(milliseconds). Default value is 100. Range is 0 to 2,000,000.
the Apply button.
Primary Memory Buffer Size

Primary memory buffer size is the size in bytes of the Primary memory buffer. Default
value is 32768. Range is 64 to 2,000,000.
the Apply button.
Secondary Memory Buffer Size

Secondary memory buffer size is the size in bytes of the Secondary memory buffer. Default
value is 32768. Range is 64 to 2,000,000.
the Apply button.
Max Transfer Objects

Max transfer objects is the maximum number of events to send between each SENDRATE
pause. Default value is 500. Range is 1 to 2,000,000.
the Apply button.
Pause Rate
When buffers are empty the buffering process will wait for this number of seconds before
attempting to send more data to the home node. Default value is 2. Range is 0 to
2,000,000.
the Apply button.
Retry Rate
When the buffering process discovers the home node is unavailable it will wait this number
of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.
the Apply button.
53
Buffering
Max Theoretical Send Rate

This is the theoretical max send rate is calculated like this:
max = MAXTRANSFEROBJS / SENDRATE * 1000
Default value is 5000.
There are no additional steps needed to install buffering after installing the PI-API. The
delivered PI-API library supports both buffered and un-buffered calls.
Configuring Buffering Manually

Buffering is enabled through the use of a configuration file, piclient.ini. Unless this
file is modified to explicitly enable buffering, the PI-API will not buffer data, sending data
directly to the home node.
There are no additional steps needed to install buffering after installing the PI-API. The
delivered PI-API library supports both buffered and un-buffered calls.
Note: When buffering is configured to be on, the Bufserv process must be started
before other programs using the PI-API, so that these programs can access the shared
buffering resources. Any program that makes a connection to a PI Server has this
requirement even if it does not write to PI.
Configuration of buffering is achieved through entries in the piclient.ini file. The file
is found in the dat subdirectory of the PIHOME directory (typically c:\pipc\dat) under
Windows NT. This file follows the conventions of Microsoft Windows initialization files
with sections, keywords within sections, and values for keywords. All buffering settings are
entered in a section called [APIBUFFER]. To modify settings, simply edit the
piclient.ini file in a text editor (Notepad on Windows) to the desired values.
The following settings are available for buffering configuration:
54
Keywords
Values
Default
Description
BUFFERING
0,1
Turn off/on buffering. OFF = 0,

ON = 1,
PAUSERATE
0 - 2,000,000
When buffers are empty the

buffering process will wait for this
long before attempting to send
more data to the home node
(seconds)
RETRYRATE
0 - 2,000,000
120
When the buffering process

discovers the home node is
unavailable it will wait this long
before attempting to reconnect
(seconds)
MAXFILESIZE
1 - 2,000,000
100,000
Maximum buffer file size before

buffering fails and discards
events. (Kbytes)
MAXTRANSFERO
BJS
1 - 2,000,000
500
Maximum number of events to

send between each SENDRATE
pause.
Keywords
Values
Default
Description
BUF1SIZE
64 - 2,000,000
32768
Primary memory buffer size.

(bytes)
BUF2SIZE
64 - 2,000,000
32768
Secondary memory buffer size.

(bytes)
SENDRATE
0 - 2,000,000
100
The time to wait between sending

up to MAXTRANSFEROBJS to
the server (milliseconds)
In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define
the default PI server and an optional time offset change that may occur between the client
and server.
Keywords
Values
Default
Description
PIHOMENODE
string
none
Windows default server is in

pilogin.ini
DSTMISMATCH
02,000,000
The time that the server and client

local time offset is allowed to jump.
Typically, 3600 if the nodes are in
time zones whose DST rules differ
(seconds)
Example piclient.ini File

On Windows NT the default server information is stored in the pilogin.ini file so the
piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1
indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to
100 Megabytes of data storage. Do not use commas or other separators in the numeric
entries. The retry rate is set to 600 seconds meaning wait 10 minutes after losing a
connection before retrying.
On NT a piclient.ini file might look like:
[APIBUFFER]
BUFFERING=1
MAXFILESIZE=100000
; The PI-API connection routines have a 1 minute default timeout.
RETRYRATE=600
55
Appendix A:
Error and Informational Messages
A string NameID is pre-pended to error messages written to the message log. Name is a
non-configurable identifier that is no longer than 9 characters. ID is a configurable
identifier that is no longer than 9 characters and is specified using the /id flag on the
startup command line.
Message Logs
The location of the message log depends upon the platform on which the interface is
running. See the UniInt End User Document for more information.
Messages are written to PIHOME\dat\pipc.log at the following times.
When the interface starts many informational messages are written to the log.
These include the version of the interface, the version of UniInt, the command-line
parameters used, and the number of points.
As the interface retrieves points, messages are sent to the log if there are any
problems with the configuration of the points.
System Errors and PI Errors

System errors are associated with positive error numbers. Errors related to PI are
associated with negative error numbers.
Error Descriptions on NT
On NT, descriptions of system and PI errors can be obtained with the pidiag utility:
\PI\adm\pidiag e error_number
Interface-Specific Troubleshooting
If the interface is behaving in an unexpected manner, check the pipc.log file. Even when
the interface runs in interactive mode, not all error messages are written to the screen.
Interface Startup and Point Loading Errors
57
Check that the NT Environmental Variables (Control Panel -> System) contain the path to
the eda.dll and fixtools.dll (assuming Intellution software is installed on the machine).
EDA Failed to add tag [NODE, TAG, FIELD] to the group. NDK:Network
Command Table (NCT) full.
Interface failed to initialize because the Intellution program TCPTask.exe has hung or is
not running. Verify TCPTask is part of the startup list for the Intellution software. Restart
the Intellution software and interface.
EDA Failed to add tag, [tagname], to the group. Location2 out of range.
Location2 defines whether the tag is an input (0) or output (1). Verify the PI tag definition
has a Location2 value of either 0 or 1.
Complete NODE:TAG:FIELD information unavailable for PI tag: [tagname]
Verify that either the complete Node, Tag, Field (NTF) definition has been defined. The tag
definition uses the IntrumentTag. If the NTF definition requires more than 32 characters
use the Exdesc tag attribute to define the Node and Field parameters.
EDA Failed to add tag [NODE,TAG,FIELD] to the group. [tagname]
When debug is enabled for point checking, the interface attempts to verify the tag with
Intellution during startup. If this fails it prints this message to the pipc.log file. Check the
tag configuration for this point, in particular the NTF definition. Launch the Intellution
Database Builder program and verify you can view current values for this point.
Data Collection Errors

The following list of error codes describe the common return values the interface receives
from Intellution when a tag update request fails. They can grouped into two general
categories; network errors and non-network errors.
Non-Network Errors
When the interface receives a non-network error from Intellution in response to a data
request it writes Bad Input, prints the error to the pipc.log file and continues scanning
for data. The tag does not get dropped from the scan list (the interface will continue to try
and read data for the point) but the error message will not be repeated in the pipc.log file,
its only printed the first time the read fails.
Read failed. Error 1209 returned calling eda_get_float(); [tagname]
This error gets returned to the interface from Intellution on an update request and
translates to "Illegal block field". Verify the NTF definition (InstrumentTag) for the PI tag
configuration.
translates to Field's value not known". Verify that the Intellution software is currently
scanning data for that point. Run Intellution Database Builder program and check that it is
on scan and you can view a current value.
58
translates to "Tag name is not defined". Run Intellution Database Builder program and
verify that the tag exists on the defined node. Verify the NTF definition (InstrumentTag) for
the PI tag configuration.
Network Errors
When the interface receives a network error from Intellution it writes IO Timeout, stops
scanning for updates and goes into a wait loop while trying to re-establish a connection to
Intellution.
Read failed. Error 1914 returned calling eda_get_float(); [tagname] [Node,Tag,Field]
translates to "Connection NOT established with node". Verify the local Intellution software
is running. If the tag data is coming from a remote Intellution View/SCADA node check
the network connection.
59
Appendix B:
FIXtoPI Configuration Transfer Utility
Overview
A utility is provided to transfer configuration information contained in the FIX EDA
database to tags in the PI Data archive. This utility must be considered as an aid rather
than a total solution for configuring the PI Data Archive to work with the FIX EDA
database.
The utility is a command line program called FIXToPI.exe.
The utility transfers the configuration information of the active raw data points in the FIX
database, and formats them in a text file of appropriate commands for entry into the
piconfig program.
The text file is named FIXToPI.scr, and it may be utilized in either of two ways. The first
method is to run the piconfig utility with input redirected from this file. The second method
is to use the @INPUT command of the piconfig utility.
The configuration transfer utility is designed to transfer information contained in Analog
Input, Analog Output, Analog Register, Digital Input, Digital Output, Digital Register, and
Multiple Digital Input blocks. If you wish to archive information contained in other than
those blocks, this must be done manually. In addition, the "Register" type blocks are
configured as PI input points and thus will be read by the interface instead of being able to
write to the Registers. If the client wishes to configure "Register" type blocks as PI output
tags, the tag must be edited manually in piconfig.
The utility must be run on a FIX SCADA node, as it uses FIX functions that will not work
on a simple VIEW node.
The program is designed to be flexible, allowing the transfer of all the information
contained for the above type blocks as a default, and allowing the user to restrict that
transfer in a manner of the user's choosing.
The user can choose to allow the program to transfer configuration information
from the SCADA node that the utility is running on and all the attached SCADA
nodes, or he can choose to restrict it to any subset of those nodes.
He can choose to allow it to transfer all tags of the types described above, or he
can restrict that to any subset of those types.
He can choose to allow transfer of all tags on the specified nodes, or he can
exclude certain tagnames based on a simple pattern-matching scheme.
He can also choose to only include tagnames that match a particular pattern. The
pattern-matching scheme is simple - it is the one used in MS-DOS to match filenames;
the '?' character matches any character, the '*' character matches all characters from
that point on, and any other character is an exact match. Please note that the pattern
matching is case sensitive, so "ONE" is not the same pattern as "one".
The utility creates a unique digital set for each unique digital set in FIX when building the
file to create the PI tags. The digital set names assigned to the digital sets all start with the
61
prefix dmFIXds. The suffix XXXX is appended where XXXX is a value from 0000 to 9999.
The first digital set will be named dmFIXds0000, the second digital set will be named
dmFIXds0001, etc. The user should edit the digital state set names in the file where
appropriate.
All digital output tags are assigned a source tag with the same name as the tag tame. This
should be edited and the appropriate source tag name used.
User Instructions
The format of the command line for using the utility is:
FIXToPI /p=<pointsource> [/n=<node> [/n=<node>]] [/t=<type> [/t=<type> ]]
[/I=<include pattern> [/I=<include pattern> ]]
[/e=<exclude pattern> [/e=<exclude pattern> ]]
Parameters
Parameter
Description
/p
The PI point source that you would like these

points to have. This is a required parameter,
and if not included, the program will exit with
nothing done.
Required
/n
Optional
/t
Optional
/e
Optional
/I
Optional
Name of a node. This parameter may be

repeated for each node that the user wishes to
include in the list of nodes. If no parameter of
this type is specified, the program defaults to
all nodes accessible by the machine on which
the program is running.
Name of a block type. This parameter may be
repeated for each block type that the user
wishes to include in the list of block types.
These can be any of
"AI","AO","AR","DI","DO","DR","MDI, "AA",
"DA". If no parameter of this type is specified,
the default is to include all the above in the list
of types.
Pattern to match to the FIX block name to
exclude from configuration transfer. The
parameter may be repeated for each pattern
the user wishes to exclude. If any of these type
of parameters appears, the utility attempts to
match each block name as encountered, and if
the pattern match succeeds, the configuration
information is NOT transferred. If multiple
patterns are included, if the block name
matches ANY of the patterns, the configuration
information is NOT transferred.
Pattern to match to the FIX block name to
transfer configuration information. This
parameter may be repeated for each pattern
that the user wishes to include. If no parameter
of this type is specified, the default is to
62
Parameter
Description
include all the tags with the exception of the
above exclude list.
If one or more of these parameters are
included, the configuration Information is
transferred for any block whose name matches
any of the patterns in the list.
Note: Exclude processing is done before include processing, and therefore, if a block
name matches the pattern of something on the exclude list, it will not be subjected to
include list processing.
Sample Command Lines

FIXToPI /p=E /n=SCADA1
Transfer all tags on node SCADA1
FIXToPI /p=G /t=AO /t=AI /t=AR

Transfer all the analog points for all connected SCADA nodes
FIXToPI /p=x /I=I* /I=J* /n=LOCAL /t=DI

Transfer the Digital Input block information on node "LOCAL" whose names begin with
the letters 'I' or 'J'
FIXToPI /p=k /e=1??CHK*

Transfers all configuration information of all blocks on all connected nodes except for the
blocks with names containing a '1' as the first character, anything in the next two
characters, "CHK" as the next three characters and anything after that.
Sample FixToPI.scr File

Once the Utility has been run, the user should first edit the file FIXToPI.scr prior to
creating the PI tags and digital sets. The following example output shows the file that will
be created in order to create a PI tag for each FIX point type.
FIX Tag Name FIX Point Type
AI1
AO1
AR!
DI1
DO1
DR1
MDI1
AA1
DA1
AI
AO
AR
DI
DO
DR
MD
AA (supported but not shown)
DA (supported but not shown)
63
Appendix B: FIXtoPI Configuration Transfer Utility
Sample Output
Sample output from the utility is:
@table pids
@mode create, t
@istructure set,state,...
dmFIXds0000,OPEN,CLOSE
dmFIXds0001,OPENUP,CLOSEUP
dmFIXds0002,state0,state1,state2,state3,state4,state5,state6,state7
@endsection
@table pipoint
@ptclass classic
@mode create, t
@istructure
tag,pointsource,descriptor,pointtype,digitalset,ptaccess,dataaccess,
archiving,scan,instrumenttag,location1,location2,location4
DAVID:DI1,E,Digital Input 1,Digital,dmFIXds0000,o:rw g:rw w:rw,o:rw g:rw
w:rw,1,1,"DAVID,DI1,D_CV",1,0,1
DAVID:DO1,E,Digital Output 1,Digital,dmFIXds0001,o:rw g:rw w:rw,o:rw g:rw
w:rw,1,1,"DAVID,DO1,D_CV",1,1,1
DAVID:DR1,E,Digital Register 1,Digital,dmFIXds0000,o:rw g:rw w:rw,o:rw g:rw
w:rw,1,1,"DAVID,DR1,D_CV",1,0,1
DAVID:MDI1,E,,Digital,dmFIXds0002,o:rw g:rw w:rw,o:rw g:rw
w:rw,1,1,"DAVID,MDI1,M_CV",1,0,1
@endsection
@istructure tag,sourcetag
DAVID:DO1,DAVID:DO1
@endsection
@table pipoint
@ptclass classic
@mode create, t
@istructure
tag,pointsource,descriptor,pointtype,zero,span,typicalvalue,engunits,
excdev,excmin,excmax,compdev,compmin,compmax,ptaccess,dataaccess,archiving,
compressing,scan,instrumenttag,location1,location2,location4
DAVID:AI1,E,Analog Input 1,Float32,0.000000,100.000000,50.000000,,1.000000,
0, 600, 2.000000, 0, 28800,o:rw g:rw w:rw,o:rw g:rw
w:rw,1,1,1,"DAVID,AI1,F_CV",1,0,1
DAVID:AO1,E,Analog Output
1,Float32,0.000000,100.000000,50.000000,ao1,1.000000, 0, 600, 2.000000, 0,
28800,o:rw g:rw w:rw,o:rw g:rw w:rw,1,1,1,"DAVID,AO1,F_CV",1,1,1
DAVID:AR1,E,Analog Register
1,Float32,0.000000,100.000000,50.000000,,1.000000, 0, 600, 2.000000, 0,
28800,o:rw g:rw w:rw,o:rw g:rw w:rw,1,1,1,"DAVID,AR1,F_CV",1,0,1
@endsection
@istructure tag,sourcetag
DAVID:AO1,DAVID:AO1
@endsection
@bye
Once the editing has been done, the last step is to utilize the text file generated by this
utility to generate tags in the PI Data Archive itself. There are two methods of doing this.
The first involves standard input redirection, which means that you run the piconfig utility
64
but instead of accepting input from the keyboard, you redirect that input so that it comes
from the file.
Piconfig < FIXToPI.scr
The second way of utilizing this file is to use the @INPUT command of the piconfig
command set. To do this, start the piconfig utility:
Piconfig
Then, at the command prompt, enter the command @INPUT followed by the file name:
(Ls - ) PIconfig>@INPUT FIXToPI.scr
In both cases, ensure that you prepend the correct path information if this file is not in the
current subdirectory.
Note: FixToPI utility is not a tag auto-synchronization program. Once it is run and
changes are made later in FIX point database, it is the users responsibility to check that
the changes are still compatible with PI point attributes and if necessary, PI point
database is appropriately modified.
65
Appendix C:
Cluster Failover
Cluster Node 1
apionline
pi-eda
Is the interface running??
Is apionline running?
Resource Owner
Shared Cluster Disk

Cluster
Administrator
Cluster Group: pi-eda
Group Resource: apionline
Cluster Node 2
apionline
pi-eda
Is the interface running??
Is apionline running?
Figure 1: Cluster Failover Configuration Diagram
Interface-level failover is supported through Microsoft clustering. A cluster is composed of

two or more nodes. Each member of the cluster has a copy of the interface installed and
running, with only one node sending data to PI at any given time. Microsoft provides a
Cluster Administrator program which is used for configuration and management of failover
resources. A system failure (hardware or software) on the active cluster node will cause the
Cluster Administrator to initiate a failover. On failover ownership of a cluster resource is
shifted from the node of failure to another available cluster node. In this way we ensure
that the only one cluster node owns the active interface at any given time.
Note that failover activity does not apply with respect to alarm/event message data
collection. If enabled, alarm/event data will be collected on each interface node
independent of cluster failover. However it is strongly recommended that you run a
separate copy of the interface specifically for collecting this type of data to maximize
performance.
Setting up interface failover requires creating cluster groups and resources. These
configurations are accomplished using the Cluster Administrator (see Group and Resource
Creation Using Cluster Administrator, page 75). The interface installation will distribute
the program apionline into the install directory whose purpose is to run as a cluster group
resource. On startup the interface checks to see if the designated apionline cluster resource
is running. If this is true it tells the interface the local node owns the cluster group resource
67
and is responsible for sending data to PI. The basic idea is which ever cluster node owns
the group resource is also the node where the active interface runs.
The apionline program serves two purposes: It indicates to the interface that it is currently
active and it also prevents the Cluster Administrator from having an active node where the
interface is not running.
The interface will query the Cluster Administrator to see if the apionline service is active.
Since apionline is configured as a cluster group resource, it will only be active if the
Cluster Administrator designates the local node as the group resource owner. In turn, when
the apionline service is active it checks to see that the interface service is running. If at
anytime the interface service terminates, apionline will shut itself down, thus initiating a
failover. In this way apionline prevents the Cluster Administrator from designating a node
where the interface is not running to be owner of the cluster resource group.
The interface has the option of running in either warm or hot failover mode. Warm failover
means an inactive interface will not request data updates from Intellution, but otherwise
functions normally (processing tag edits, alarm/event data collection, etc.). Hot failover
means an inactive interface will request data updates but does not send them to PI. The
advantage of running in hot failover mode is you minimize the risk of missing data on
warm failover mode.
The interface can be configured to operate with a preference for running on a particular
cluster node. This is referred to as running with primary node bias. In this configuration
the interface will attempt to run on the primary node whenever possible. This behavior
Note that the Intellution software must also be installed on each cluster node. Redundancy
should be enabled on both nodes so they share the same point database. See FIX
Redundancey and PI-EDA for information on how to set this up.
Cluster Failover Configurations

Configuring APIOnline
The interface installation kit will distribute the apionline files (apionline.bat and
apionline.exe) into the interface install directory. Configuring apionline is a three step
process. The fist step is to configure the apionline.bat file so it includes the name of the
interface service used for failover. The second step is to install the apionline program to
run as a service. The last step is to define apionline as a cluster group resource.
The apionline.bat file is where you specify the name of the interface service. This file
requires two parameter definitions. The first parameter is the name of the apionline
executable. The /proc parameter is used to define the interface service. For example, if the
interface service is installed as pi-eda and the apionline executable is apionline.exe then
the apionline.bat file would contain the following:
REM sample apionline.bat
apionline.exe /proc=pi-eda
Note that apionline uses the same parameters whichever node it runs on. This means that
you must have the same installation directory and executable name on each cluster node.
For example if on one node you install the interface here:
68
c:\Program Files\pipc\interfaces\pi-eda\pi-eda.exe
Then on the other cluster nodes the install directory and interface name must match. Here
is an example of how this might look on another cluster node:
d:\pipc\interfaces\pi-eda\pi-eda.exe
However to keep things simple its recommended that you use the same name and
installation path across all systems.
The apionline application must also be installed as a service. Installing a program to run as
a service is done from the command prompt at the path where the program resides. The
following is an example of installing the apionline service:
d:\pipc\interfaces\pi-eda>apionline install depend tcpip
The apionline.bat and apionline.exe file should reside in the same directory. By default
these files are located in the interface install directory, however this is not required. Once
apionline has been installed as a service the files should not be moved without first
removing the service, then reinstalling after relocating the files. The following is an
example of removing an installed apionline service:
d:\pipc\interfaces\pi-eda>apionline remove
The final configuration step requires that a unique cluster group be created for each unique
instance of apionline. Each group should have its own copy of apionline defined as a
resource. Resources are moved between cluster nodes by group. Please see Group and
Resource Creation Using Cluster Administrator for information on how to setup cluster
group resources.
Configuring the Interface

Configuring with the PI-ICU Control
The ICU simplifies configuration and maintenance, and we strongly suggest using it if you
can. PI-ICU can only be used for interfaces which are collecting data for PI3 systems,
version 3.3 and up.
Figure 2: PI-ICU Configuration Screen for PI-EDA Interface
69
Appendix C Cluster Failover
Enable interface cluster failover

Enable this check box to if you wish to use failover. Upon enabling this box the failover
configuration options will become active.
Cluster Mode:
The interface has the ability to operate with a preference for running on a specified cluster
node if at all possible. This is referred to as running with Primary bias. This behavior
If Primary bias is selected using the drop down list, then the This node is the : option will
be enabled. At this point you must specify whether this cluster node is the primary or
backup. Note it is critical that only one cluster node be specified as the primary. If more
than one cluster node is specified as the primary node they will compete for ownership of
the cluster group resource, sending the interface into an endless loop of failovers.
A cluster mode of No bias means the interface does not attempt to control which node runs
the active interface. As a result whichever node owns the cluster resource on startup will be
the active interface. This will remain so until there is a problem that causes failover or a
user uses the Cluster Manger to intentionally manipulate the configuration. The default
value for this option is No Bias.
This node is the:

This option is enabled when Primary bias is specified for the Cluster Mode:. In this
configuration you must specify whether the current node is the primary or backup node for
failover operation. The default value for this option is Backup.
Failover mode:
The interface has the option of running in either warm or hot failover mode. This behavior
determines whether or not an interface running as a backup will query Intellution for point
updates.
Warm failover mode means the interface does not query for point updates when operating
as the backup node. Hot failover mode tells the interface is should query Intellution for
point updates at all times, but send them only when active.
The advantage of running in hot failover mode is you minimize the risk of missing data on
Resource number for APIOnline :

interface startup. For example, if you enter a value of 1, the interface will look for
apionline1 as the cluster group resource. A negative number tells the interface that the
resource has been defined as simply apionline. A procedure for creating cluster group
resources can be found in the section Group and Resource Creation Using Cluster
Administrator.
70
Active interface node tag :

A PI string tag can be specified to receive the name of the node where the active interface
is running. The button to the right of this option can be used to launch a PI tag search for
selecting the desired tag.
The active cluster tag should be configured as follows:
Attribute
Value
PointSource
PointType
string
Compressing
ExcDev
Shutdown hostname
Configuring the Interface Manually

If the PI-ICU is not used, then the interface startup bat file must be manually configured.
The following table lists the parameters that are concerned with interface-level failover. A
complete discussion on these parameters is included the following sections.
Table 2: Startup Command File Parameters for Cluster Failover
Interface Parameter
Description
/FO
(required)
Tells the interface to enable cluster failover support.
/RN=#
(required)
Specifies the number used for the matching apionline

resource.
/CM=#
(optional)
default: 1
Specifies the Cluster Mode, whether the interface has

a bias toward running on the primary node (/CM=0) or
no bias (/CM=1).
/PR=#
(required if /CM=0)
Specifies that this is the primary (/PR=0) or backup

(/PR=1) node. This parameter need only be defined if
the cluster mode is set for primary bias (/CM=0).
/FM=#
(optional)
default: 1
Specifies either hot (/FM=0) or warm (/FM=1) failover

mode. This parameter determines whether the backup
interface will query Intellution for point updates.
/CN=PI string tag

(optional)
Specifies a PI string tag which receives the name of

the node which is currently active. This tag will also
receive a shutdown event for each node whenever the
interface is stopped.
71
/FO : Enable Cluster Failover Support

This parameter must be specified to enable cluster failover support. If its not specified,
and other failover parameters are included in the startup file the interface will print a
message to the pipc.log file and exit.
/RN=# : APIOnline Resource Number

interface startup. For example if /RN=1, the interface will look for apionline1 as the
cluster group resource. A negative number tells the interface that the resource has been
defined as simply apionline. /RN is a required parameter for failover operation. If this
parameter is missing or an invalid definition is specified the interface will print an error in
the pipc.log file and exit. A procedure for creating cluster group resources can be found in
the section Group and Resource Creation Using Cluster Administrator.
/CM=# : Cluster Mode

If the interface is configured for a cluster mode of primary bias (/CM=0) then the
designated primary node will run the active interface if at all possible. This means if the
interface on the primary node is up, running and connected to Intellution it will be the
active interface. In this configuration the interface checks on startup to see if it is
designated as the primary or a backup node (/PR). For this reason its required the
interface startup file contain the /PR parameter if the cluster mode is configured for
primary bias. Note it is critical that only one cluster node be specified as the primary. If
more than one cluster node is specified as the primary node they will compete for
ownership of the cluster group resource, sending the interface into an endless loop of
failovers.
A cluster mode of no bias (/CM=1) means the interface does not attempt to control which
node runs the active interface. As a result whichever node owns the cluster resource on
startup will be the active interface. This will remain so until there is a problem that causes
failover or a user uses the Cluster Manger to intentionally manipulate the configuration.
The default setting for cluster mode is no bias (/CM=1).
/PR=# : Primary or Backup Node

This parameter need only be specified if the cluster mode is set for primary bias (/CM=0).
With the cluster mode is set to primary bias the interface checks on startup to see if it is
designated as the primary or backup node. For this reason its required the interface startup
file contains the /PR parameter when configured for primary bias.
/FM=# : Failover Mode

There are two possible configurations for failover mode; warm failover (/FM=0) or hot
failover (/FM=1). The failover mode determines the behavior of the backup interface,
whether to query Intellution for input data (hot failover) or not (warm failover). The
advantage of hot failover is to minimize the chance for data loss on failover. The advantage
of warm failover is to minimize loading on the Intellution system. We recommend testing
the interface first in hot failover configuration and if the loading on the Intellution is too
great to use warm failover.
72
/CN=PI String Tag : Active Cluster Node Tag

A PI string tag can be specified using the /CN parameter to receive the name of the node
where the active interface is running. The active cluster tag should be configured as
follows:
Attribute
Value
PointSource
PointType
string
Compressing
ExcDev
Shutdown hostname
Sample Startup File Configurations

The following are sample startup file configurations for a two node cluster. The first set of
files show the configurations for running with a cluster mode of no bias. The second set of
files show the configuration for running with a cluster mode of primary bias.
Sample Startup File Configurations: No Bias Cluster Mode
Cluster Node 1:
REM sample pi-eda.bat

pi-eda.exe /host=piserver:5450 /ps=f /id=1 /f=5 /w=60 /fo /rn=1 /cm=1 /fm=0 /cn=active.cluster
Cluster Node 2:

pi-eda.exe /host=piserver:5450 /ps=f /id=1 /f=5 /w=60 /fo /rn=1 /cm=1 /fm=0 /cn=active.cluster
The configuration files specify the interface should look for cluster group resource
apionline (/RN=-1) to indicate when the interface is active. It also specifies the interface is
to run in warm failover mode and write active cluster node information to the PI string tag
active.cluster.
Sample Startup File Configurations: Primary Bias Cluster Mode
Cluster Node 1:

pi-eda.exe /host=piserver:5450 /ps=f /id=1 /f=5 /w=60 /fo
/rn=2 /cm=0 /pr=0 /fm=1 /cn=active.cluster
73

Cluster Node 2:

pi-eda.exe /host=piserver:5450 /ps=f /id=1 /f=5 /w=60 /fo
/rn=2 /cm=0 /pr=1 /fm=1 /cn=active.cluster
The configuration files specify the interface should look for cluster group resource
apionline2 (/RN=2) to indicate when the interface is active. Cluster node 1 is specified as
the primary node (/PR=0), meaning it will be active if at all possible. Cluster node 2 is
designated as the backup node and will only be active if cluster node 1 cannot run. It also
specifies the interface is to run in hot failover mode (meaning the backup interface will
query Intellution for point updates) and write active cluster node information to the PI
string tag active.cluster.
Running Multiple Instances of the Interface

Running multiple instances of the interface on each cluster node requires a unique instance
of apionline for each instance of the interface. Each copy of apionline must also belong to
a unique cluster group and installed to run as a service. Running multiple instances of the
interface is useful for tracking problems or for distributing interface loading.
To differentiate between copies of apionline append an integer to the name. This integer
gets passed to the corresponding interface through the /RN interface parameter. For
example, if we were to run two copies of the interface we would also need two copies of
apionline on each cluster node. The following table displays a list of the files and
configuration parameters required for each cluster node to run in this configuration:
Table 4: Required Files and Configuration Parameters
Program
Executable
Configuration
File
Required Configuration
Parameters
apionline1.exe
apionline1.bat
apionline1.exe /proc=pi-eda1
pi-eda1.exe
pi-eda1.bat
/FO /RN=1 /ID=1 *
apionline2.exe
apionline2.bat
Apionline2.exe /proc=pi-eda2
pi-eda2.exe
pi-eda2.bat
/FO /RN=2 /ID=2 *
This is not a complete listing of the necessary interface startup parameters to run the interface. Please
see Startup Command File section for a complete listing and definition of the available parameters.
Note its not required that each interface use a unique /ID parameter. However it is highly
recommend for differentiating interface messages to the pipc.log file. The interface appends
the /ID parameter to each message it print to this file:
PI-EDA #> - where # corresponds to the /ID=# definition in the
interface startup file
Without using a unique /ID parameter for each instance of the interface it is nearly
impossible to tell which copy of the interface printed what message. Note that the
Location1 point attribute for interface tags must match the /ID parameter. The /ID is used
by the interface in conjunction with the point source to identify which points belong to it.
The final configuration step requires that a unique cluster group be created for each unique
instance of apionline. Each group should have its own copy of apionline defined as a
resource. MSCS moves resources between cluster nodes by group. For this reason its
required that a unique cluster group resource be defined for each unique copy of apionline.
74
Please see Group and Resource Creation Using Cluster Administrator for information on
how to setup cluster group resources.
Buffering Data on Cluster Nodes

Buffering is fully supported on cluster nodes. In order to take advantage of buffering,
bufserv.exe should be installed on all participating cluster nodes at the time of PI-API
installation. No special configurations are required to enable buffering on a cluster node. It
should be noted that there is a risk of incurring a substantial amount of out or order data in
the scenario a failover occurs at a time where both interfaces are disconnected from PI
(thus buffering data). Upon reconnection each cluster node will send buffered data
simultaneously which will result in out of order data. This will cause the PI server to
increase resource consumption, particularly the PI Archive Subsystem, as it attempts to
process these out of order events. For a complete discussion on how to configure buffering,
see Buffering.
Group and Resource Creation Using Cluster Administrator

Before this step, make sure that MSCS is installed and configured. You should test and
verify that Clustering is functioning correctly prior to creating groups and resources for
interface failover. We'll also specify some steps for verifying correct cluster configuration
at the end of this section. Apionline should also be installed and configured as described in
the section Configuring APIOnline.
Cluster Group Configuration

Note: Interfaces must not be run under the Local System account if you are using
Cluster Failover. You must set up the service to run under an account that has
administrator privileges.
Installation of Cluster Group

From the desktop, click on Start-> Programs-> Administrative Tools(Common)-> Cluster
Administrator. Click on File-> New-> Group. Enter the name of the group and description.
75

Click Next. Do not add any to the Preferred owners box, since owner preference is built
into the interface through the cluster mode. Below, Grommit and Wallace are the cluster
nodes.
Click Finish.
Right click on the group you just created and select Properties. Fill out the name of the
cluster and the description. Do not select the Preferred owners since these are the nodes
on which you prefer the group to run. Preferred ownership is built into the interface
through the cluster mode. Therefore you should not set this from the Cluster Administrator.
76
Set the Threshold and Period as follows. Threshold is the maximum number of times you
want to allow the group to fail over in the time specified by Period.
For the Failback tab, select Prevent failback, since failback mechanism is also built into
interface through cluster mode.
Click on Apply and then OK.
77
Installation of the Resources

Right click on the group in Cluster Administrator, select New and then Resource. Type the
name of the resource, and description. Select the Resource type Generic Service.
Running this resource in a separate Resource Monitor is not necessary, unless this resource
seems to be causing a lot of problems and you are trying to isolate the problem.
Click on Next and verify that the cluster nodes are in Possible owners list. These are the
nodes on which the resource can run, and therefore the nodes onto which the group can fail
over.
78
Click Next and skip Dependencies. Move on to Generic Service Parameters.
This resource (in the example above, it is called apionline1) should have been installed as a
service prior to cluster resource as described in the section Configuring APIOnline.
Click on Next and skip Registry Replication. Click on Apply and OK.
Right click on the resource and then select Properties. In Advanced tab, set the entries as
below. Note that we're telling MSCS to pass ownership of the resource to another cluster
node before attempting to start it.
Click Apply and then OK.
79

Repeat the group and resource creation process for each instance of the interface on the
node. Now you are ready to configure the interface.
Testing Cluster Configuration

You can save yourself a lot of potential frustration if you verify things step by step. Here's
a simple configuration procedure that will help you identify any problems quickly. This is
written for just one copy of the interface on each node. If you're configuring multiple
copies, the first 5 steps only need to be done for the first copy of the interface that you test.
When it says "matching" below, it means that if you're working with pi-eda3.exe, look for
apionline3.exe, and the apionline3 service and resource.
1. Configure the interface on each node with a dummy pointsource, one which is not
currently used by any tags, or with a pointsource and ID number that don't match the
pointsource and Location1 pair of any tags. The idea is to bring up both interfaces
with no tags at all. Do not configure any failover-related parameters.
2. Start both interfaces, check pipc.log to verify that both of them come up completely
and sit there with no tags. Any errors reported in pipc.log must be corrected before
continuing with the next step.
3. Using Cluster Administrator, bring the matching cluster resource online by selecting
the matching cluster group, then right-clicking on the resource and selecting Bring
Online. You should be able to use Task Manager to see that the matching apionline
process is running on the node that Cluster Manager says owns the resource. We'll call
that node OriginalOwner.
4. Still using Cluster Administrator, fail over the resource by selecting Initiate Failure in
the right-click menu of the resource. You should see the resource state go to Failed and
then Online Pending and then Online, with the other node now the owner. Depending
on your system, you may not see the intermediate states, but you should definitely see
the resource end up Online with the other node as the owner. If not, you have a
configuration problem and you must correct that before continuing the test.
5. Use Task manager to verify that the matching apionline on the OriginalOwner node is
no longer running, and that the matching apionline service is now running on the other
node (OriginalBackup node). If all this is good so far, move the resource to whichever
node will be your primary node.
6. Now use Cluster Manager to take the resource Offline, then shut down both copies of
the interface. Configuring the Interface the way you intend to have them run (don't
forget to reset the pointsource and /ID to the correct values).
7. Bring up the interface on the node that does not currently own the group. You should
see in pipc.log that it says
Cluster resource not online, state 4, waiting
8. Bring the resource online. You should see the resource failover to the node where the
interface is running. Once apionline is running on the same node as the interface, you
should see in pipc.log
Cluster Resource apionline1 on this node
or possibly
Resource now running on this node
9. Now bring up the other interface. If the interface is configured with a cluster mode of
primary node bias and the interface is currently running on the backup node, you will
80
see the resource failover to the primary node. In pipc.log on the primary node, you will
see again one of the two messages listed in the last step.
If you've gotten this far, you should be configured correctly. You could try failing the
resource over a time or two, and shutting down one interface at a time, just to make sure
that the interfaces do what you expect them to do
.
81
Appendix D:
FIX Redundancy and PI-EDA
Both FIX32 and iFIX support failover (starting from FIX32 version 6.15 and FIX
Dynamics version 2.0). PI-EDA can take advantage of this functionality by running on a
View node. A View node can look at a pair of SCADA nodes that have the identical
databases (and are connected to the same PLC) and obtain data from the currently active
node. More information on Failover can be found in Intellutions documentation for FIX32
or iFIX. Although FIX allows a backup SCADA configuration that involves two SCADA
servers and no View node, PI-EDA, as of version 2.0.0, does not support this
configuration.
Note: iFIX does not synchronize the process databases on the SCADA servers. You
must ensure that both databases are identical. It is also important that the failover-paired
SCADA nodes clocks are synchronized in order to ensure that the tags get the same
data regardless of which SCADA the values are pulled from.
Note: FIX32 version 7.0 and iFIX 2.1 have been tested at OSI for failover support and
PI-EDA compatibility with FIX redundancy. The redundancy system tested consisted of
pure FIX32 or pure iFIX combinations, i.e., 2 FIX32 SCADA nodes and 1 FIX32 VIEW
node, or 2 iFIX SCADA nodes and 1 iFIX VIEW node. The average time the VIEW node
took to fail over from one SCADA node to the other was about 20-30 seconds. This is
reflected in the data gap in PI Archive.
This section describes the setup on VIEW node and the failover-pair SCADA nodes and PI
tag configurations so that PI-EDA can seamlessly collect data regardless of which SCADA
node is active. Configurations are slightly different depending on whether the system is
FIX32 or iFIX.
FIX32 Redundancy Setup

FIX32 View Node
In Configure/Network dialog, enter remote node names with which the VIEW node
communicates.
Note: Only the primary node of the pair SCADA nodes needs to be entered here.
Click on Configure button and get the following screen.

Enter the backup node name for this remote SCADA node.
82
FIX32 Primary SCADA Node

In SCU........
In Configure/SCADA screen, fill in the database name. This database must reside both on
the primary SCADA node and the backup SCADA node with the identical tag definitions.
Define Partner SCADA in Redundancy box.
Then in Configure/Network dialogue,
Enter the View node name and the SCADA partner node name in Remote Nodes box. Then
highlight the SCADA partner node (i.e., this nodes backup node) and click on
Configure Then enter its backup nodes name in redundancy box (since this is the
backup nodess backup, it would be primary nodes name).
FIX32 Backup SCADA Node

Do the same thing as on the primary node, except that the local node name is the backup
node name, Partner SCADA is the primary node, and the remote nodes backup node is the
backup node.
83
Appendix D FIX Redundancy and PI-EDA
FIX32 View Nodes Network Status Display

In FIX View, when you open nsdredun.odf you will see which SCADA node is active
currently. This is the SCADA node from which PI-EDA will be getting tag values. For
details on how to set this up, see FIX documentation.
FIX32 Node \winnt\system32\drivers\etc Host File

View node and both SCADA nodes must all have host files with the View node name,
primary and backup SCADA node names and IP addresses. For example,
xxx.xxx.xxx.1
xxx.xxx.xxx.2
xxx.xxx.xxx.3
FIXVIEW
FIXPRMRY
FIXBAKUP
PI Tag Configuration for FIX32 Tag

All configuration settings are the same as when no redundancy is required except that the
NODE field in InstrumentTag attribute must be the primary node name.
iFIX Redundancy Setup

iFIX View Node
In SCU/Configure/Network screen, enter the logical name that the View node is to
communicate with in the Remote Node Name field. Click the Add button. The logical node
name appears in the Configured Remote Nodes list.
84
Then click on Configure button and check Enable Logical Names box. Enter the local node
name of the primary node in the Primary Node field. Enter the local node name of the
backup node in the Backup Node field.
85
Appendix D FIX Redundancy and PI-EDA
iFIX Primary SCADA Node

In SCU/Configure/LocalStartup screen, enter the logical name for the primary node and
the backup SCADA pair.
Then in SCU/Configure/SCADA screen, enter the backup SCADA name.

Then go to SCU/Configure/Network screen and enter the logical name for this SCADA
and its backup SCADA nodes in the Remote Node Name box. Click Add.
Then click on Configure button and check Enable Logical Names box. Enter the local
node name of the primary node in the Primary Node field. Enter the local node name of the
backup node in the Backup Node field.
Go back to SCU/Configure/Network screen and add the View node name in Remote Node
Name box.
iFIX Backup SCADA Node

Do the same thing as on the primary node, except that the local node name is the backup
node name, and the Partner SCADA name in Configure/SCADA is the primary node name.
The Configure/Network setting is identical to that of the primary SCADA node.
86
iFIX Network Status Redundancy Display

NetworkStatusRedundancyDisplay.grf file can be setup to show which SCADA
node is currently active. PI-EDA gets its data from this active node.
iFIX Node \winnt\system32\drivers\etc Host File

View node and both SCADA nodes must all have host files with the View node name and
primary and backup SCADA node names and IP addresses. For example,
xxx.xxx.xxx.1
xxx.xxx.xxx.2
xxx.xxx.xxx.3
FIXVIEW
FIXPRMRY
FIXBAKUP
PI Tag Configuration for iFIX Tag

All configuration settings are the same as when no redundancy is required, except that the
NODE field in InstrumentTag attribute must be the logical SCADA node name for the
failover (a.k.a. redundancy) SCADA pair.
87
Revision History
Date
Author
Comments
21-Oct-97
MH
First draft
22-Oct-97
MH
First version reviewed
11-Nov-97
DM
Data type revisions
12-Nov-97
DM
Local failure detection
23-Jan-98
DM
Added configuration transfer utilities
09-Apr-98
DM
Offloaded NTF components to ExDesc field in PI
15-Apr-98
JFZ
Re-added utility info from version 1.3 manual.
13-May-98
DM
Additional information on string tags
16-Jun-98
HAO
Fixed table of contents, page nums were all listed

as 0
17-Jul-98
KL
Noted changes since version 1.4.
08-Aug-98
KL
Corrected descriptions in /L switch and logging tag

sections. Deleted Logging Tag section. Modified /L
description to reflect the change in code which
causes the interface to abort instead of hanging
(v1.8).
10-Sep-98
KL
Corrected the error in manuals up to version 1.8.2

regarding the delimiter after event=xxxx entry in the
PI extended descriptor. Now both , and ; are
allowed to end NODE name and FIELD name.
However, a comma must still be used to end event
tag name.
03-Dec-98
KL
Added a more detailed message list under Troubleshooting section. Added comments on added
features (optional local server time switch).
29-Mar-99
KL
Added descriptions of enhancement features.
15-Apr-99
KL
Modified explanation for eda error 1212. Included

debug symbol installation instructions. Added
descriptions of more debug switches in command
line.
03-Aug-99
KL
Added explanation for new data type support (FIX

float to PI digital mapping) .
25-Jan-00
KL
Added FIX redundancy information.
03-Jul-00
KL
Corrected Location1 range from 1 to 99 to 0 to 98.
28-Jul-00
KL
Added more comments about user queue in /qn

section
09-Aug-02
POW
Updated for alarm/event msg data collection.

Changed manual format to meet new standard.
2-Oct-02
CG
Updated to skeleton 1.11
21-Apr-03
POW
Added Appendix C: Cluster Failover. Included

failover parameters in startup file section.
88
Date
Author
Comments
11-Jun-03
POW
Updated version on title page to 2.1.3.0
13-Jun-03
POW
Updated for new ICU, incremented version to 2.2.0.

Moved FIX redundancy section to Appendix D.
Revised command line startup switches section.
18-Jun-03
POW
Revised Point Attribute, Principles of Operation &

Supported Features sections. Revised Hardware
Diagram. Removed Logging section from Appendix
A (now supported through debug startup switch).
Revised Error Messages in Appendix A.
19-Jun-03
POW
Added alarm/event message data and redundancy

subsections to Principles of Operation. Added
diagrams for redundancy architecture to Principles
of Operation section.
89

PI IntFix 2.2.0.0

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

PI IntFix 2.2.0.0

Uploaded by

Copyright:

Available Formats

Intellution Fix DMACS (FIX32) /

OSI Software, Ltd

OSIsoft Canada ULC

OSI Software Asia, Pte Ltd.

European Joint Venture

For additional information, please see our Web site:

Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual

Interface Startup and Point Loading Errors............................................................57

Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual

UniInt End User Document

PI Data Archive Manual

PI-API Installation Instructions

Intellution Electronic Books

Float32 / Int32 / Float16 / Int16 /Digital / String

Sub-Second Scan Classes

Inputs to PI: Scan-Based /

Scan-Based / Event Tags

Maximum Point Count

PINet to PI 3 String Support

PI server or PI-API node

Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual

* Vendor Software Required on PIAPI / PINet Node

* Vendor Software Required on

Vendor Hardware Required

* Additional PI Software Included

* See paragraphs below for further explanation.

Vendor Software Required

Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual

**Intellution Software Compatibility Testing

Supported Data Types

Diagram of Hardware Connection

(NT 4, Windows 2000 or XP)

Architecture of the Intellution FIX/iFIX Interface

Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual

Alarm/Event Message Data Collection

Point for Point Alarm/Event Message Data

All Alarm/Event Message Data to a Single PI String Tag

SCADA Node Failover

Intellution View Node

Redundant SCADA Nodes

Architecture of SCADA/View Node Redundancy

Interface Cluster Failover

Microsoft Cluster Sever

Architecture of Interface Cluster Failover

8. Configure performance points.

Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual

Naming Conventions and Requirements

Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual

Interface Installation Directory

Replace PIHOME with the corresponding entry in the pipc.ini file.

Interface Installation Procedure

Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual

Installing the Interface as an NT Service

Installing the Interface Service with PI-Interface Configuration Utility

Service Startup Type

If the Auto option is selected, the service will be installed to start

Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual

Create or Remove Interface Service

Start or Stop Service

Installing the Interface Service Manually

pi-eda.exe install depend tcpip bufserv

pi-eda.exe install auto depend tcpip bufserv