Intellution Fix DMACS (FIX32) / Dynamics (iFIX)
Interface to the PI System
Version 2.0.1 or Greater
How to Contact Us
Phone / (510) 297-5800 (main number)(510) 297-5828 (technical support)
Fax / (510) 357-8136
Internet /
World Wide Web /
Bulletin Board / (510) 895-9423
Telebit WorldBlazer modem (Hayes, MNP, or PEP compatible)
8 data bits, 1 stop bit, no parity, up to 14400 bps download
protocols: Xmodem, Ymodem, Zmodem, Kermit
Mail / OSI Software, Inc.
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland /
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.
intfix184.doc
1997 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
7/28/00 10:56 AM1
Table of Contents
Overview......
Supported Data Types......
PI Point Definition......
FIX Tag Address Format......
General PI Tag Configuration Information......
PointSource......
PointType......
Location1......
Location2......
Location4......
InstrumentTag......
Scan......
SourceTag......
ExDesc......
Input Tag Configuration......
Performance and EDA Usage......
Output Tag Configuration......
Additional PI2 Configuration......
Point Source......
Digital State Code......
Hardware and Software......
Interface Software Requirements......
Interface Hardware Requirements......
Startup Command File......
FIX DMACS Interface Installation......
NT-Intel Installation Disk File List......
Disk File List......
Installation Procedure......
To run as a service......
To run in interactive mode......
To install debug symbols......
FIX DMACS Interface System Administration......
Starting the FIX DMACS Interface......
Automatic Service Startup......
Manual Service Startup......
Interactive Startup......
Stopping the FIX DMACS Interface......
Status, Warning, and Error Messages......
IORates......
FIX Redundancy and Pi-eda......
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 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......
Appendix A Communication Error Recovery......
Appendix B Troubleshooting......
Frequently Asked Questions......
More messages logged to “pipc.log” file and explanations......
"Completed re-processing tags"
“EDA error <#> occurred during function XXXX on FIX NTF <X, Y, Z>”
"Test field for tag T is Z. Interface aborting"
"Local host XXX restored at day-month-year hour:min:second "
"No FIX field type specified for PI tag X"
"No FIX tag name specified for PI tag X"
"No conversion is supplied for float"
"EDA Digital type tags are configured in PI as PI digital types"
"EDA Multistate Digital type tags are configured in PI as PI digital types"
"EDA (A)lphanumeric field is defined, but the PI field is not 'string'"
"Field type <Z> not supported"
"No tag configuration specified for <T>"
"Could not retrieve local host name. Interface aborted"
"Interface running on local FIX node NNNN"
"Could not create EDA group for scanclass #!"
"Could not create EDA group for event-tag T triggered tags!"
"Created group for scanclass #"
"Created group for event-tag T triggered tags"
"Edited tag T could not be added"
"Complete NODE:TAG:FIELD information unavailable for PI tag: T"
"Fatal Error on tree manipulation"
"EDA Failed to add tag [N, T, F] to the group"
"Removed tag: [N, T, F]"
"Unrecognized state <xxxx> in (Multistate) Digital tag [N, T, F]"
"Unknown data type for tag [N, T, F]"
"Connection with node N reestablished"
"Unsupported type for FIX tag [N, T, F]"
"Driver shutdown"
For FIX EDA Errors, consult Intellution EDA manual.
Appendix C Message Logging......
Logging Configuration......
Appendix D FIX to PI Configuration Transfer Utility......
Overview......
User Instructions......
Overview
This is a description of the Intellution FIX DMACS (FIX32) / Dynamics (iFIX) interface to the PI System for Windows NT. In addition to having the previously existing functionalities this version of the interface allows the user to collect the data placed on an alarm/event queue by FIX with subsecond timestamps. This enhanced version can be run on one of the following:
- An NT PI3 Server
- An NT PI API node with network access to a PI2 or PI3 Server
The interface requires that the Intellution FIX MMI software version 6.x (or FIX32 version 7.0) or later or FIX Dynamics HMI/SCADA version 1.0 or later (or iFIX version 2.1) be present on the same PC as the interface. SCADA support does not need to be enabled in order for this interface to run. That is, this interface can be run on a FIX View node.
Note: Previously several customers have been unable to run the interface on version 6.12 of FIX. With version 1.7 and later the interface runs with FIX 6.12 as well. For important information regarding running this interface with FIX Dynamics, see release notes. Up to FIX Dynamics 1.0 and FIX DMACS 6.15, a FIX Dynamics SCADA node and a FIX DMACS SCADA node do not talk to each other. FIX32 version 7.0 node, however, can be seen by iFIX version 2.1 node and vice versa.
FIX32 version 6.15 and FIX Dynames version 2.0 introduced automatic failover functionality. Pi-eda running on a View node (and View node only – see the section on Redundancy in this manual) 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 in this manual.
Note: This interface requires PI API version at least 1.3.2 (see release notes).
For proper interface operation, configure input points (input tags) and/or output points (output tags) on a PI2 or PI3 home node (the words "point" and "tag" are used interchangeably in this manual). Input tags are used to receive data from FIX nodes, either local or remote. A single interface can collect data from one or more FIX nodes at a time. Data are received either at a given frequency or after a value that is sent to a given "triggertag" passes exception. These tags will be referred to as the event-triggered tags in this manual.
Output tags are used to send commands to FIX. 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.
All values that are written to the snapshot or archive use the system time from the PI home node. In addition, this interface is able to fetch data from the user queue where FIX SAC places alarm and event messages. The points for which data are collected this way will be referred to as the event-message tags in this interface manual. The event-message tags MUST be configured as alarm- and/or event message-enabled in FIX database. It is recommended that separate instances of this interface be run for strictly scan-based data collection and event-message collection in order to take full advantage of event-messaging feature of this interface. This will be discussed further in General PI Tag Configuration section. Either WUSERQ1.exe or WUSERQ2.exe (please see FIX manual for details) must be running in order for this feature to work. These executables will monitor alarms/events from alarm areas and make them available to our interface.
Note: WUSERQ1 and WUSERQ2 cannot monitor alarm areas named other than A-P. This interface was designed to use WUSERQ1 or WUSERQ2, and therefore will not work if the alarm areas are named other than A-P. This will be fixed in future release.
At startup, the interface scans the PI Point Database for all associated points and builds its own point list. During runtime, the interface continues to check the PI Point Database for point updates and modifies its point list accordingly. If the Scan field 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 scanrate nor a valid triggertag are found for a given point, the point will be removed from, or will not be added to the point list. This applies to event-message tags also - specifically, they must be in scan class 1. See General PI Tag Configuration section.
Supported Data Types
The FIX DMACS interface provides support for analog, digital, and string values from FIX. Digital values in FIX are stored as strings. The interface converts the strings to a numerical state corresponding to the position of the string within the FIX setup. For digital points, the values returned to PI will be either 1 or 0. For multi-state digital points, the values returned to PI will be from 0 to 7. 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. That is, 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 D.
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.
PI Point Definition
FIX Tag Address Format
The FIX DMACS interface uses a "node-tag-field" (NTF) identifier to reference a specific point in FIX. The node references the FIX node on which the tag resides. Tag references the actual tag within the specified node, and field determines which of the tag’s attributes to reference.
General PI Tag Configuration Information
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 following describes the field names associated with PI point configuration that have specific meaning for use with the FIX DMACS interface. Other fields may also need to be specified for proper configuration of the PI point. Some of these fields include point name (tag name), typical value, engineering units, resolution code (PI2 only), filter code, etc. The user may wish to create I/O Rate Tags for each interface. For more information on PI Point configuration see the Data Archive (DA) section of the PI System Manual (for PI2 home nodes) or the PI Data Archive Manual for Windows NT and UNIX (for PI3 home nodes).
The field names in the table below are consistent with the field names in the Data Archive Manual for PI3. Please refer to the Appendix regarding use of the FixToPI transfer utility to facilitate in the creation of PI points.
PointSource
All points to be used by the FIX DMACS interface must share a common point source (for example, M). For a PI2 home node, one must edit the point source table to include this PointSource (choose "point source" from the PI2 System main menu). See "Additional configuration for PI2" below. For PI3, the only requirement is to configure the tag with the same PointSource that is defined in the PI-EDA#.bat startup command file.
PointType
The interface supports all three PI point types for PI2, i.e., real R, integer I, and Discrete D, and Float16, Float32, Int16, Int32 and Discrete point types for PI3. The interface also supports the PI String point type.
Location1
This parameter is used to specify the interface number, which corresponds to the /id=# flag in the PI-EDA#.batfile. Valid interface numbers are integer values 0 to 98, inclusive.
Location2
This parameter identifies the I/O type for the tag. If the tag is an output tag, this parameter must be set to 1.
= 0 Input tag
= 1 Output tag
Invalid Location2 values will cause the tag not to be added to the scan list. However, the interface will add other valid tags to the list and continue to run.
Location4
This field determines the frequency at which an input tag is scanned. The field is ignored for output tags (I/O type 1). The field is also ignored for input tags (I/O type 0) if a "triggertag" is specified in the extended descriptor. By specifying a triggertag, the associated input tag is scanned after an "event" instead of being scanned at the frequency specified in Location4. See the section entitled "Input Tag Configuration" for essential details on input tags and triggertags. To be safe, set Location4 to 0 for event-based input tags or for output tags.
The possible scanning frequencies for a given interface are specified by the user on the command line in the PI-EDA#.batfile (see the section entitled "Startup Command File"). For example,if part of the command line is as follows:
/f=00:00:05 /f=00:00:15 /f=00:01:00,00:00:10 /f=00:00:0.05,0
Then, the point can be configured to scan FIX every 5 seconds, every 15 seconds, or every 1 minute. For the 5-second and 15 second periods, scanning will begin on the hour or at a multiple of 5 or 15 seconds after the hour. For the 1-minute period, scanning will begin 10 seconds after the hour or at a multiple of 1minute and 10 seconds after the hour.
If Location4 is 1 for the above command line, then the point will be scanned every 5 seconds. If Location4 is 2, then the point will be scanned every 15 seconds, and so on. The last scanclass shows the format for subsecond scan frequency.
Note: The highest scan resolution available in FIX is 0.05 seconds as of FIX32 verison 7.0 and iFIX version 2.1. Pi-eda has about the same resolution with buffering on. User should watch CPU usage on the node pi-eda is installed on. Depending on how loaded the CPU is, this performance can improve or degrade. The absolute limit on resolution is 0.01 second.
Important notes for event-message tags:
- For all event-message tags, Location4 value MUST be 1. It does not matter what that frequency is as long as the event-message tags are configured so that they all belong to scan frequency class 1 (Location4 = 1). This configuration in combination with /EM switch in the startup command file is used to let the interface know that these tags are to receive values from the alram/event-message queue instead of FIX database which the interface polls at pre-specified intervals. If /EM switch is set and the tags that have Location4 value equal to 1 are not alarm/event-message enabled in FIX, they will receive NO data through this interface. It is the user’s responsibility to configure these tags correctly within FIX database.
- It is strongly recommended to run separate instances of the interface for scan-based tags and event-message based tags. Although this interface is capable of doing both types of data collection, if the interface has to spend time scanning at fixed intervals, it cannot take full advantage of the event-messaging feature. This interface is a UniInt (OSI interface standard) based interface and fetches event messages from the queue while the interface is not scanning (during so-called “inbetween scan times”). Both collection methods’ performances will be compromised if the list of each is long.
- Due to the current UniInt limitation, scan-based tags cannot be scanned at subsecond intervals. However, event-message tags receive sub-second timestamps upto the current FIX subsecond scanning resolution.
- The sub-second timestamp resolution for event-message tags in PI is only as good as that of FIX’s SCAN rate. That is, if FIX can only send alarms to the queue every 0.05 seconds, that is the highest resolution that the PI tags will get. For the latest information on the highest resolution available, please contact Intellution TechSupport.
InstrumentTag
This field is used to specify the NTF address for FIX. NTF stands for Node-Tag-Field, and is used to address a specific tag within FIX. Each entry in the NTF must be separated with a comma, with no spaces between the commas and text.
F_CV (F for float) is the only Field that is specified for analog FIX points (for other supported analog Fields see the next paragraph). Qualifying FIX float-valued blocks are converted to PI float tags by our utility FixToPI and are assigned this Field. For block types that are automatically converted (without requiring manual intervention by the user), see the section on FixToPI at the end of this manual. Other block types that result in float value are also supported by this interface, but they need to be manually configured in PI. This attribute is also specified in the InstrumentTag field for the PI tag.
If FIX NTF = LocalNode,TagX,F_CV the InstrumentTag field for a PI tag would contain:
LocalNode,TagX,F_CV
Note: The Analog Alarm types in FIX are supported by this interface by configuring them as one of the following three PI data types: digital (two states only), multi-state digital or strings (if the server is PI3).
For digital and multi-state digital FIX points, the Field specified in FIX is A_CV for both types of digital points (A for alphanumeric). However, when configuring PI tags for FIX digital and multi-state digital points, the field name must be modified from the FIX format. For digital tags, the field must always start with D_ and for multi-state tags, the field name must start with M_. This is an interface-specific requirement, and no modification of the FIX database is required.