Foxboro I/A 50 and 70 Series Interface to the PI System

Foxboro I/A 50 and 70 Series
Interface to the PI System

Version 2.0.7

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
Hauptstrae 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 ©(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.
fxb51_70.doc

 2000 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577

02/15/00 4:56 PM1

Table of Contents

Introduction......

Foxboro I/A to PI Interface......

Introduction......

Software and Hardware Configurations......

PI Software Operation......

Additional Documentation......

PI Point Definition......

PI Point Attributes......

Example point configurations......

FoxAPI Setup......

Interface Installation......

Windows NT......

Installing the files......

Configuring Fxbais to run as a service......

Modifying the API start and stop scripts......

Running fxbais interactively......

Configuring iorate counters......

Interface configuration......

Solaris Installation......

Installing the files......

Configuring iorate counters......

Automatic start of the interface......

Interface configuration......

PI Software Configuration......

Interface Command Line Parameters......

Initialization file......

Interface Operation......

Windows NT Interface Startup......

Shutdown - NT......

Solaris Interface Startup......

Solaris Shutdown......

Performance Summaries......

Appendix......

Migrating from version 1.16 to version 2......

Relinking the AP51 Interface......

Setting Timestamps......

Troubleshooting Tips......

1: Waiting for central to start......

2: fxbais process not killed......

3: Library not found or interface does not start......

4: “Undefined symbol”......

5: Unable to write to files sitestart and sitestop......

6: Bits used for extra debugging information......

7: Error status, -242 for a string point......

8: Error “sh: /opt/fox/ais/bin/open_action: not found”......

9: Error “sh: /opt/fox/ais/bin/clsset_action: not found”......

10: The event count seems too high or too low......

11: I/A network traffic drastically increased......

12: Environment variables are not defined in VT100 window......

February, 001

Introduction

The PI interface to the Foxboro I/A Series systems provides for the bi-directional transfer of data between Foxboro I/A Series computers FoxAPI (Foxboro API) and PI systems. The 51 series computers run on Sun’s SPARC platforms on the Solaris 2.x operating system while the 70 series run under Windows NT 4.0. The FoxAPI libraries are backward compatible with AIS version 3, which ships with all AP51 series stations. PI systems run on VMS, UNIX, and Windows NT platforms.

To setup the interface, two separate PI modules must be installed on the I/A Series workstation:

PI Module / Purpose
PI-API / Provides communication between the interface node and the PI system
PI-Foxboro AP51/AW70 / Interface software

This document describes installation and operation of the PI-Foxboro interface. The PI-API installation must be completed before the interface is installed. Instructions describing setup of the API node are found in the ”PI-API Installation” document.

Important note: Detailed instructions regarding the migration from version 1.16 to version 2.0.7 of the interface are in the appendix.

Foxboro I/A to PI Interface

Introduction

Software and Hardware Configurations

The Foxboro I/A to PI Interface Program is part of the link that connects a Plant Information (PI) System with a Foxboro I/A Series control system. The PI interface resides in a Sun SPARC station (50 Series) or a Windows NT workstation (70 Series) along with Foxboro API software (FoxAPI), OSI’s Application Programming Interface (PI-API), and TCP/IP. Also, the I/A workstation may be a PI3 server.[1] The following is a simplified connection diagram.

PI (Server or PINet Node)
TCP/IP


Foxboro
50 or 70 Series workstation / TCP/IP
OSI PI-API
OSI Interface Program
Foxboro AIS or FoxAPI
| / |
| / |
Foxboro IA / DNBI / INI
| / |
IA Node Bus

The diagram shows a PI server or PINet node connected to a n I/A 50 or 70 Series workstation (referred to as the “I/A” below). One or more interface programs connect the I/A workstation to the PI-API for two-way communication between the I/A workstation and the PI server.

PI Software Operation

The interface polls for new data and status bits from the I/A and sends values with good status to the PI server. The interface may use either pisn_sendexceptionqx or pisn_putsnapshotqx calls with these values. For bad status values, bad input or time-out digital state values are sent to PI. Timestamps for the new values are the current PI server times at when the values are read from the FoxAPI.

The interface also can retrieve exceptions from the PI server and send the values to the I/A (outputs).

Additional Documentation

PI Point Definition

The following point attributes define PI points for reading and/or writing to the Foxboro I/A. The general description of each point attribute used by the interface is given first, then examples of points for various input and output configurations are given. The interface monitors updates to the PI point database and incorporates changes into its point list.

In the following discussion, the Foxboro tag name is often called the Foxboro I/A object name. The term I/A object is used in the FoxAPI programmer’s manual. Also, the I/A point type and the PI point type may be different. I/A data types are converted to PI point types of digital, int32, or float32.

PI Point Attributes

Tag

The text name identifier may be up to 80 characters long (12 characters for PI 2 or longname may be up to 80 characters).

Instrumenttag

Instrument tag: The Foxboro tag name (also called the I/A object) used for reading/writing from/to the I/A. It may contain up to 32 characters in the compound:block.parameter or alias formats. If this field is empty, the extended descriptor is used to determine the I/A object. If both the instrumenttag and exdesc fields contain Foxboro tag names, the instrumenttag attribute is used.

ExDesc (inputs)

Extended descriptor: For reading data (inputs are defined by location3 >= 0) from the I/A, the Extended Descriptor has the form:

FoxIA_tag_name, PROFILE=Profile_info, EVENT=Pitag,

BTM=x,y,z... ! comments

If the instrument tag field is empty, the Foxboro data object that is being read, FoxIA_tag_name, is obtained from the extended descriptor. Up to 32characters may be used beginning in the left most position. The full Foxboro name in the proper case must be used. The instrument tag PI point attribute is preferred for specifying the I/A object name instead of the extended descriptor.

EVENT=, TRIG=, or TRG=Pitag is an optional specification for trigger or event tags. With inputs the current I/A tag value is sent to the PI point when a new snapshot is received for the PItag on the PI server. The current PI server time stamp is used for the value sent to the PI point. The interface signs up for new exception values to PItag with the PI server and must be connected to receive the values. If the exception occurs on the PI server while the interface is disconnected, the PItag exception will be missed even if the interface is buffering. However, the profile data scans described below will not be missed while disconnected.

PROFILE=[SCAN][###][DISCRETE] is for reading profile data if the appropriate Foxboro libraries are available. Three types or points are available, the SCAN points check for an update in the time reported by the I/A object. The numeric entry indicates the profile array position on a scanner. The DISCRETE entry indicates the I/A object should be read when triggered by a new event. The EVENT=<PI tag with SCAN specification> specification should also be used with the array-position and discrete entries.

BTM=x,y,z... is for a bit mask and is optional. The bit mask is x,y,z... where x is the bit location in the source (0-31 for long integers) whose value is put in the low order bit (0) in the target. Then y is the bit location in the source whose value is put in the next bit (1) in the target. Up to 31 bits can be put in the target, and unspecified target bits are set to 0. Only integral Foxboro types can be masked. An example is BTM=31,0,7,8 which puts bit 31 of the source to bit 0 of the target, bit 0 to bit 1, bit 7 to bit 2, and bit 8 of the source to bit 3 of the target.

Note: the MSG=IA_string_object_name specification is no longer supported. Instead, a PI string tag should be configured and the location 2 parameter should be set to I/A point type 4.

Exdesc (outputs)

For writing (outputs are defined by location3 < 0) to the I/A the ExDesc form is:

FoxIA_tag_name SRC=PITag1 ! comments

FoxIA_tag_name is the Foxboro data object name that is being written (instrument tag is the preferred method of specifying the I/A tag name). It is up to 32 characters, begins in the left most position, and is case sensitive. The FoxAPI Programmer’s Guide cautions that the read/write access mode secures the object so that no other process can write to that I/A object. This mode is required for writing.

SRC=PITag1, SOURCE=PITag1 , or EVENT=pitag1 is optional (the sourcetag attribute is preferred over using the extended descriptor SRC= specification). SRC=PITag1 can start any place after the FoxIA_tag_name ends. The SRC= option allows the output tag to point to another PI tag that contains the value to be written. PITag1 is the name of the PI tag that supplies the value; it can have the same Point Source as interface tags but may also have a different pointsource than the interface.

If the output tag and the SRC=pitag1 tag are different, the value read from pitag1 is written to the I/A and then written back to the output PI tag. If the output tag and the SRC=pitag1 are the same, the value read from pitag1 is written to the I/A, but not written back to PI.

I/A automatically reads any written variables, and the values are available for subsequent reading

Note: The RTN option is no longer used. Standard UNIINT output configuration is now used. This causes the interface to automatically read the value written to the I/A variable and send the value re-read from the I/A back to the PI output tag (if the PI output tag is the same as the source tag, the write-back to PI will not occur).

Sourcetag

Source tag: For outputs, the source tag contains the PI tag that provides the output values. If this field is empty, the extended descriptor is checked for a PI tag defined by SRC=PITag1 or (SOURCE=, EVENT=PITag1 work in the same manner).

Pointtype

All PI point types may be used. Real (R, float16, float32, or float64), integer (I, int16 or int32), digital (D), or string types are valid. The I/A value will be converted to the destination PI point type. For digital values, the I/A value is sent as a positive offset into the specified digital set (0 to Maximum digital states for the set). The I/A data range for the object selected should be appropriate if PI point types int16 or float16 are used (positive values only for 16 bit point types). The I/A data ranges are listed in the table under location3, below.

Pointsource

A single character code (for example, F) for Foxboro I/A points. For VMS (PI 2) servers, it must be defined in the PI Point Source Table (PI2 only). A new character may be used by adding the letter to the Point Source Table and defining the same character in the point source parameter in the script file fxbais.sh (I/A 50 Series) or fxbais.bat (I/A 70 Series). PI3 servers do not use point source tables. Point source characters used by other PI programs should be avoided to reduce confusion and decrease the startup time for the interface. Some point sources which should be avoided are C (PE calculations), T (totalizer), Q (PI2-SQC), G (PI3-alarm groups), @ (alarms), ? (PI2-fractal), L (lab and default pointsource).

On PI 2 systems, a point source range is specified by selecting the PointSrc option on the PI Menu, choosing a blank field from the point source list, and entering the following location parameter limits. After the limits have been defined, you will be prompted to define the point source for the point source list.

Location 1 / Location 2 / Location 3 / Location 4 / Location 5
Minimum / 100 / 0 / -10 / 0 / -86400
Maximum / 9999 / 2100000000 / 10 / 1000 / 86400

Location1

This parameter is the result of calculating (n*100) where n is the interface id number in the range 1 to 99. The interface id number associates PI tags with an interface and is an arbitrary parameter that is set in the interface script file, fxbais.sh. The gateway number is obsolete with FoxAPI and is no longer used in this interface. Previously, the gateway number ranging from 1 to 99 was added to the location1 parameter. Any remainder of location1/100 is not used. The range for Location1 is 100 to 9999.

Location2

Location2 governs whether or not a point is added to a buffered list. Buffered values are those updated by the FoxAPI in the system shared memory. Unbuffered objects make requests to the CP for each function call. Buffered access is recommended to reduce load on the system.

Location2>0: This parameter is the data list number. It groups PI tags into lists used for FoxAPI scopen() calls. Any value greater than zero indicates a member of a continually updated buffered list (value and status of I/A tags are updated in shared memory by FoxAPI). Read values and write values must be in separate data lists, and typically values in different CP modules are in separate data lists. The range is 1 to MAXINT32 (greater than 2 billion). For each PI list used for scopen() a unique data set number is returned by FoxAPI. The data set number may be different than the PI list number used for grouping tags.
Location2=0: A value of zero indicates unbuffered object read/write (uread(), uwrite(), sread(), swrite()). I/A string tags are unbuffered.

Location3

This parameter is the I/A value type. For read values (PI receiving from I/A) they are positive. For write values they are negative.

Location3 / I/A Type / I/A data range
(+/-) 1 / 1, char / ‘0’ to ‘9’
(+/-) 2 / 2, short int / -32768 to 32767
(+/-) 3 / 3, float / (IEEE limits)
(+/-) 4 / 4, string / up to 256 bytes
(+/-) 5 / 5, boolean / 0 to 1
(+/-) 6 / 6, long int / -2147483648 to 2147483647
(+/-) 8 / 8, short int / 0 to 255
(+/-) 9 / 9, packed boolean / 0 to 65535
(+/-) 10 / 10, long packed boolean / 0 to 4294967295

As examples: a type 2 would be for int exceptions received by PI, and a type -3 would be for float writes to I/A. Outputs (writes) can be enabled with a configurable parameter (-write) in the script file fxbais.sh. The I/A type as read from the object will be used when reading/writing values regardless of the location3 parameter. A message will be written to the log for any point type mismatches and the correct type will be used internally. The user may then update the location3 parameter in the PI point database.

Location4

This parameter specifies the scan class to which the point belongs. The Fox I/A scan rate parameter for the point will be equal to double the rate for the scan class. The scan class is defined on the interface command line by the /f parameter . The actual rate at which the I/A scans for changes equals ½ of the scan rate parameter, in seconds. The scan rate parameter is used by the I/A and is an argument in the FoxAPI scopen() function call. The range is 1 to 20. A scan class with frequency greater than 10 seconds (scan rate parameter > 20) defaults to scan rate parameter 20. The smallest scan rate value of a list’s members is used for that set.

For migration of location4 from version 1.16 to version 2 of the interface, refer to the Appendix.

Location5

This parameter is used only by points that total a list’s I/A object change counts or pisn_sendexceptionqx events. Please refer to the troubleshooting section for details.

If location5 is non-zero, and location2 > 0, then the point is considered a counter whose value will be incremented by the I/A object change count increment for points in the list specified in location2. Location5 indicates the frequency in seconds with which the summation is written to the counter point (for example, 120 seconds).

ExcMin, ExcMax, ExcDev and ExcDevPercent

These are the exception-specification attributes. Note that there is no ExcDevPercent attribute for PI 2 servers.

The ExcDev attribute may be set to the same as the I/A object “read delta”.

The exception-specification attributes are used to define exception-reporting specifications. Exception reporting is basically a filter. Raw values that the interface receives are filtered if they do not pass the exception-reporting specifications. If the raw values pass exception, they are sent to the snapshot, where they can be viewed by client applications such as PI-ProcessBook. Unless the /sn flag is specified on the command line of the interface, standard exception reporting will be implemented.

ExcMin is the exception minimum time, ExcMax is the exception maximum time, and ExcDev is the exception deviation dead band. For PI 2, ExcDev is defined in terms of engineering units or in terms of percent of the Span attribute, depending on how the DeviationUnits attribute is set. For PI 3, ExcDev is always defined in terms of engineering units.

Raw values are said to “pass exception” if:

The difference between the new value and the last value that passed exception is greater than ExcDev and the difference between the times of the new value and the last value that passed exception is greater than ExcMin.

The difference between the times of the new value and the last value that passed exception is greater than ExcMax.

The last value that passed exception is called the “old value.” The next value that passes exception is called the “new value.” The last value that was received by the interface before the new value is called the “previous value.” There will not be a “previous value” if the interface did not receive a value between the “old value” and the “new value.” When a new value passes exception, the previous value and the new value will be sent to the snapshot. The new value will then become the old value, and the cycle continues.