Intellution Fix DMACS (FIX32) / Dynamics (iFIX)
Interface to the PI System
Version 2.1.0
v
UniInt End-User Interface to the PI System
How to Contact Us
Phone / (510) 297-5800 (main number)(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web / http://www.osisoft.com
Mail / OSI Software, Inc.
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrabe 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721
OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand
Unpublished -- rights reserved under the copyright laws of the United States.
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
Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HPUX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PI_IntFix.doc
Ó 1997 - 2002 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
v
UniInt End-User Interface to the PI System
Table of Contents
Introduction 1
Reference Manuals 1
Supported Features 2
Diagram of Hardware Connection 4
Principles of Operation 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 11
Installing the Interface Service with PI-Interface Configuration Utility 11
Installing the Interface Service Manually 13
Digital States 15
Point Source 17
PI Point Configuration 19
Point Attributes 19
Tag 19
PointSource 19
PointType 19
Location1 20
Location2 20
Location3 21
Location4 21
Location5 22
InstrumentTag 22
SourceTag 25
ExDesc 25
Scan 25
Shutdown 26
Performance Point Configuration 27
Configuring Performance Points with PI-ICU 27
Configuring Performance Points Manually 28
I/O Rate Tag Configuration 29
Monitoring I/O Rates on the Interface Node 29
Configuring I/O Rate Tags with PI-ICU 29
Configuring I/O Rate Tags Manually 30
Configuring the PI Point on the PI Server 30
Configuration on the Interface Node 31
FIX Redundancy and PI-EDA 33
FIX32 View Node 33
FIX32 Primary SCADA Node 34
FIX32 Backup SCADA Node 35
FIX32 View Node’s Network Status Display 35
FIX32 Node \winnt\system32\drivers\etc Host File 35
PI Tag Configuration for FIX32 Tag 35
iFIX View Node 36
iFIX Primary SCADA Node 37
iFIX Backup SCADA Node 37
iFIX Network Status Redundancy Display 38
iFIX Node \winnt\system32\drivers\etc Host File 38
PI Tag Configuration for iFIX Tag 38
Startup Command File 39
Configuring Startup Parameters with PI-ICU Control 39
Command Line Parameters 41
Configuring Startup Parameters Manually 47
Sample pi-eda.bat File 47
Interface Node Clock 49
Security 51
Starting / Stopping the Interface 53
Starting Interface as a Service 53
Stopping Interface Running as a Service 53
Buffering 55
Configuring Buffering with PI-ICU 55
Configuring Buffering Manually 58
Example piclient.ini File 59
Appendix A: Error and Informational Messages 61
Message Logs 61
Logging Configuration 61
System Errors and PI Errors 62
Interface-Specific Troubleshooting 62
Frequently Asked Questions 62
Communication Error Recovery 71
Appendix B: FIXtoPI Configuration Transfer Utility 73
Overview 73
User Instructions 74
Parameters 74
Sample Command Lines 75
Sample FixToPI.scr File 75
Sample Output 76
Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual 13
Introduction
This is a description of the Intellution FIX DMACS (FIX32) / Dynamics (iFix) interface to the PI system. The interface supports bi-directional communication and runs on Windows NT platform (NT 4.0 sp6a, Windows 2000 and XP). The interface uses Intellutions’s EDA (Easy Data Access) library to request data from the FIX/iFix database. The EDA library is common to both FIX and iFix making this interface compatible with both platforms. The interface must run on either a FIX/iFix SCADA node or VIEW node where eda.dll and fixtools.dll are installed.
Input tags are used to receive data from FIX nodes, either local or remote (the words "point" and "tag" are used interchangeably). A single interface can collect data from one or more FIX nodes at a time. Data is received either at a given frequency or after a new value is received by a given "trigger tag”. These tags will be referred to as the event-triggered tags.
Output tags write values to a specified FIX node. A command is sent to FIX after a value that is sent to a "SourceTag" passes exception or after a value that is sent to the output tag itself passes exception, depending on the configuration of the output tag.
In addition, this interface is able to fetch data from the user queue where FIX SAC places alarm and event messages. These points will be referred to as alarm tags. In order to enable this functionality these tags must be configured as alarm- and/or event message-enabled in the FIX database. Either WUSERQ1.exe or WUSERQ2.exe must be running in order for the interface to access this data. These executables are responsible for monitoring alarm areas and making the data available to the interface. Interface alarm tags can be configured on a one-to-one basis (one PI alarm tag for each FIX alarm/event point) or all alarm/event data can be written to a single alarm tag.
Reference Manuals
OSI
· UniInt End User Document
· PI Data Archive Manual
· PI-API Installation Instructions
Intellution
· Electronic Books
· EDA
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 / Server level (FIX) only
* 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 points to receive the PI server system timestamp. Adding the /LS switch to the interface startup file will cause the interface to use the interface local system time for timestamps. In this configuration it is crucial the interface node system clock is no more than 10 minutes ahead of the PI server system time. If this happens the PI server will reject the data due to illegal timestamps.
Alarm/event-message points can store the FIX timestamp as part of the string text but the event itself is stored using the specified system time (PI Server or PI API node).
Failover
Interface-level failover is not available. However, when the interface is running on a VIEW node it can collect data from partner SCADA nodes if the active one becomes unavailable (see 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 requires one of the following vendor software packages:
· Intellution FIX MMI version 6.x (or FIX32 version 7.0 or later). If using FIX MMI version 6.12 you must use interface version 1.7 or later.
· FIX Dynamics HMI/SCADA version 1.0 or later (or iFIX version 2.1 or later)
Note: The FIX Dynamics HMI/SCADA software package was renamed to iFIX Integration Toolkit as of version 2.1
SCADA support does not need to be enabled in order for this interface to run (interface can be run on a FIX View node).
The interface must run on Windows NT platform (NT 4.0 sp6a, Windows 2000 or XP) for Intel and requires PI-API version 1.3.2 or later. The interface node must be configured with the ability to connect to FIX on the local or remote PC. That is, FIX SCADA and/or VIEW node support must be available on the interface node. The eda.dll and fixtools.dll must also be installed (this is normally done during the installation of FIX).
PI-EDA running on a View node can take advantage of this functionality to continuously collect data from partner SCADA nodes if the active one becomes unavailable. See the section on FIX Redundancy, page 33, in this manual.
Note: To take advantage of automatic failover functionality, a minimum of FIX32 version 6.15 or iFix Dynamics version 2.0 is required.
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 (Some modification may be required, see Appendix.).
Supported Data Types
The FIX interface provides support for analog, digital, and string values from FIX. The interface uses integer values to represent digital states. This reduces the overhead involved in passing digital state values between applications making communication more efficient. Two state digital points return either 1 or 0 to PI. Multi-state digital points return values from 0 to 7. These values represent digital state placeholders as defined by the digital state set. Values for all FIX tags that are alarm and/or event-message enabled can be collected via this interface, provided that they belong to scan class 1 and event message flag (/EM) is set in the startup command file.
Mapping a FIX float to a PI digital is also supported in versions 1.9.5 or greater. If a point is defined as a float in FIX (field is F_CV) but is configured as a digital in PI, values read as float is typecast to integer and this integer is sent as digital offset in PI. For example, value 0 will be mapped to the first digital state in the digital set associated with the tag, and value 1 will be mapped to the second digital state, and so on. Fixtopi utility will convert FIX float types to PI float32 by default. It is the user's responsibility to modify the script file generated by fixtopi (fixtopi.scr) to change the pointtype to digital if mapping is desired. For more information on fixtopi utility see Appendix F.
Note: FIX analog values can be stored as PI integers. However, there is a risk of a significant loss of precision due to the truncation of analog data into an integer value.
Diagram of Hardware Connection
Intellution Fix DMACS (FIX32) / Dynamics (iFIX) Interface Manual 13
Principles of Operation
The interface uses Intellutions’s EDA (Easy Data Access) library to request data from the FIX/iFix database. The EDA library is common to both FIX and iFix making this interface compatible with both platforms. The interface must run on either a FIX/iFix SCADA node or VIEW node where eda.dll and fixtools.dll are installed.
Point updates are collected either at a specific frequency (defined in the interface startup file) or triggered by an update to a given source tag (event-triggered). Interface tags are mapped through the FIX node, tag and file name. At startup the interface searches through the PI point database using the point source and interface id, as defined in the startup file, to identify what points to load. It then groups these points according to scan class. One EDA group is defined for each scan class. In addition, if output tags are defined they will be placed in a separate group. Alarm tags are a special case and do not require an EDA 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 specific group. Also, 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 scanning multiple tags grouped together.
Alarm tags get updates through WUSERQ1.exe or WUSERQ2.exe, defined in the interface startup file. These programs are responsible for making alarm/event data available to the interface. Therefore, you must ensure that one of these programs is running and specified in the interface startup file. It is recommended that a separate instance of the interface is used specifically for alarm data. Alarm tags must belong to scan class one. When alarm data collection is enabled, only alarm tags should be configured for scan class one. Any other input type belonging to scan class one will not receive updates if they belong to scan class one and alarm/event message data collection is enabled (/em in startup file).
During runtime, the interface continues to check the PI Point Database for tag edits/additions/deletions and modifies its point list accordingly. If the ‘Scan’ attribute of any point on the point list is set to off, the point is removed from the point list. The point is added once again after the Scan field is turned back on. If neither a fixed scan rate nor a valid trigger tag is found for a given point, the point will be removed from, or will not be added to the point list. This applies to alarm/event-message tags also - specifically, they must be in scan class 1 and specify a valid trigger tag in the Extended Descriptor field. See General PI Tag Configuration section.