Intellution Fix DMACS (FIX32) / Dynamics (iFIX)
Interface to the PI System

Version 2.2.0.0

OSIsoft, Inc.

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)
/ OSI Software, Ltd
Level 5 / 393 Khyber Pass Rd.
Newmarket
Auckland 1003 New Zealand
or PO Box 8256
Symonds Street
Auckland 1035 New Zealand
(64) 9-522-5900
(64) 9-522-5901 (fax)
OSIsoft Canada ULC
8150,MetropolitainBlvd.East,Suite 200
Anjou (QC) H1K 1A1Canada
(01) 514-493-0663
(01) 514-493-0980 (fax) / OSI Software Asia, Pte Ltd.
152 Beach Road
#09-06 Gateway East
Singapore 189721
(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:

BatchView.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

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

Table of Contents

Introduction

Reference Manuals

Supported Features

Diagram of Hardware Connection

Principles of Operation

Data Updates

Alarm/Event Message Data Collection

Point for Point Alarm/Event Message Data

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

Data Redundancy

SCADA Node Failover

Interface Cluster Failover

Installation Checklist

Interface Installation

Naming Conventions and Requirements

Microsoft DLLs

Interface Directories

The PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing the Interface as an NT Service

Installing the Interface Service with PI-Interface Configuration Utility

Installing the Interface Service Manually

Digital States

Point Source

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

SourceTag

ExDesc

Scan

Shutdown

Performance Point Configuration

Configuring Performance Points with PI-ICU

Configuring Performance Points Manually

I/O Rate Tag Configuration

Monitoring I/O Rates on the Interface Node

Configuring I/O Rate Tags with PI-ICU

Configuring I/O Rate Tags Manually

Configuring the PI Point on the PI Server

Configuration on the Interface Node

Startup Command File

Configuring Startup Parameters with PI-ICU Control

Command Line Parameters

Interface Node Clock

Security

Starting / Stopping the Interface

Starting Interface as a Service

Stopping Interface Running as a Service

Buffering

Configuring Buffering with PI-ICU

Configuring Buffering Manually

Example piclient.ini File

Appendix A: Error and Informational Messages

Message Logs

System Errors and PI Errors

Interface-Specific Troubleshooting

Interface Startup and Point Loading Errors

Data Collection Errors

Appendix B: FIXtoPI Configuration Transfer Utility

Overview

User Instructions

Parameters

Sample Command Lines

Sample FixToPI.scr File

Sample Output

Appendix C: Cluster Failover

Principles of Operation

Cluster Failover Configurations

Configuring APIOnline

Configuring the Interface

Buffering Data on Cluster Nodes

Group and Resource Creation Using Cluster Administrator

Cluster Group Configuration

Installation of the Resources

Testing Cluster Configuration

Appendix D: FIX Redundancy and PI-EDA

Principles of Operation

FIX32 Redundancy Setup

FIX32 View Node

FIX32 Primary SCADA Node

FIX32 Backup SCADA Node

FIX32 View Node’s Network Status Display

FIX32 Node \winnt\system32\drivers\etc Host File

PI Tag Configuration for FIX32 Tag

iFIX Redundancy Setup

iFIX View Node

iFIX Primary SCADA Node

iFIX Backup SCADA Node

iFIX Network Status Redundancy Display

iFIX Node \winnt\system32\drivers\etc Host File

PI Tag Configuration for iFIX Tag

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

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 Intellution’s 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
* Failover / Yes
* UniInt-Based / Yes
* Vendor Software Required on PI-API / 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.

It’s 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.

It’s 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
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

Principles of Operation

The interface uses Intellutions’s 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 Intellution’s 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.

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

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

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.

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

Interface Installation

OSI recommends that interfaces be installed on API nodes instead of directly on the PIServer node. An API node is any node other than the PI Server node where the PIApplication Programming Interface (PI-API) has been installed (see the PIAPIInstallation 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 PI-APInode (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.