Max 1000+PLUS
Interface to the PI System
Version 1.3
OSI Software, Inc.
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 ©(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_MAX1000pp.doc
1997-2002 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction
Supported Features
Principles of Operation
Hardware Configuration Diagram
PI Tag Configuration
MAX1000+ Tag Address Format
General PI Tag Configuration Information
Tag
PointSource
PointType
Location1
Location2
Location3
Location4
InstrumentTag
ExDesc
Scan
SourceTag
Excmin, Excmax – Exception Specs
Output Tag Configuration
Creation of Quality Digital State Set
Quality Tag Configuration
Watchdog Tag Configuration
Additional PI2 Configuration
Point Source
Digital State Code
Hardware and Software
Software Requirements
Hardware Requirements
Startup Command File
Command-line Parameters
Sample Startup Command File
Interface Installation
NT-Intel Installation Disk File List
Disk File List
Installation Procedure
To Run in Interactive Mode
Interface System Administration
Starting the Interface
Interactive Startup
Automatic Startup – Suggested Method
Stopping the Interface
Status, Warning, and Error Messages
I/O Rates
Time Stamps
Appendix A: Communication Error Recovery
Appendix B: Troubleshooting
Frequently Asked Questions
Appendix C: Message Logging
Logging Configuration
Run Time Logging Configuration
Revision History
Max 1000+PLUSInterface to the PI System1
Introduction
This is a description of the MAX 1000+PLUS Interface (from hereon referred to as the Max1000+ interface)to the PI System. The interface 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
Note: The interface requires that the MAX1000+ software be present on the same PC as the interface and the PC have network access to the SBP.
Migration interfaces are available to connect PI to all generations of MAX systems. The minimum requirement is that a MAX1000+Plus DBM must be present.
Note: The customer must contact MCS to run a system analysis to determine available throughput on older systems.
For proper interface operation, the user must configure points (tags) on a PI2 or PI3 home node (the words "point" and "tag" are used interchangeably in this manual). Tags are used to update and receive data from MAX1000+ members. A single interface can collect data from one or more MAX1000+ members at a time. Data is received at a given frequency. All values that are written to the snapshot or archive use the system time from the PI home node.
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 a fixed scan rate cannot be found for a given point, the point will be removed from or will not be added to the point list.
Supported Features
Feature / SupportInterface Platforms supported / NT-Intel
Vendor Software Required / Yes
Sign up for Updates / Yes
Exception Reporting / Yes
PI API Node Support / Yes
UNIINT / Yes
Input / Exception based
Outputs / Event based
Text Transfer / No
Multiple Links / Yes
History Recovery / No
Failover / No
Number of Points / Unlimited
Supported Data Types
The MAX1000+ interface provides support for any type of data. Directly supported PI data types for values from the MAX1000+Plus system are digital, int16, int32, float16, and float32. A separate PI tag (digital) is required to store the associated quality that may be passed with a value.
Max 1000+PLUSInterface to the PI System1
Principles of Operation
The MAX1000+Plus SBP uses “subscriptions” to mark data points for frequent update. The interval between updates is configurable on a point by point basis. The MAX1000+Plus system only sends data to a client when an exception has occurred. An exception occurs if the value changes by more then the given dead band, or the exception maximum time has expired and the dead band (exception deviation) has not been exceeded.
When the Interface first starts up it initially establishes communication with PI. A connection to the local MAX1000+Plus server is then established. The connection is uniquely identified by the client with a “user name” parameter, and uniquely identified to the server by an identification number. The interface to the MAX1000+Plus system can subscribe to data points, unsubscribe to data points, and read from specific data points. It also has the ability to write to a designated WatchDog tag on the MAX1000+Plus system which can be optionally configured by the user. All data handled by the MAX1000+ SBP is done with variant data types. This means that when data is assigned to a tag, the data is automatically handled using the most compatible type. The MAX1000+ SBP has comparable data types to handle all types supported by PI.
Exception reporting is done on the MAX1000+Plus system using the PI exception parameters which are passed to it during subscription. As each point belonging to the interface is identified, the interface subscribes the MAX1000+Plus point (specified in the Instrument Tag and/or the Extended Descriptor) on the SBP. The exception minimum, exception maximum, and exception deviation (in engineering units) are also sent to the SBP. The MAX1000+Plus system will check to see if the point subscribed is valid, or if it is valid, can it be accessed. If either condition occurs an error code is returned. The interface will then print out a message to the pipc.log file indicating when points cannot be subscribed. Note – some points may not be accessible at the time of interface startup, once they do become accessible data will automatically start being collected for them. Prior to data collection the digital state CONFIGURE is written to all points. This allows the user to easily determine which points have not begun collecting data. BAD INPUT is written to points when an error other than that indicating I/O Timeout is returned from the MAX1000+Plus system.
The MAX1000+Plus system uses the PI exception specifications that are passed for a point to determine when to check for an exception and determine when an exception has occurred. An exception occurs when the MAX1000+Plus tag exceeds the exception deviation for the point or the exception maximum time has been exceeded with no exception occurring. The exception minimum time controls the frequency at which exceptions are checked for. The minimum exception minimum time passed to the MAX1000+Plus system is 1 second. If a tag has its exception minimum parameter set to 0 then a value of 1 will be passed to the MAX1000+Plus system. The maximum exception maximum time passed to the MAX1000+Plus system is 30 seconds if the /excmax flag isn't used. The /excmax flag can be used in the interface startup file to set the maximum exception maximum parameter for all tags to a value greater than 30 seconds.If /excmax isn’t set in the interface startup file and a tag has its exception maximum parameter set greater than 30 seconds then a value of 30 will be passed to the MAX1000+Plus system. If /excmax is set in the interface startup file and a tag has its exception maximum parameter set greater than /excmax then the /excmax value will be passed to the MAX1000+Plus system. Please consult your MAX Control Systems representative for recommendations for exception maximum settings. Typical systems will be able to handle excmax times of 30 seconds for all tags. However older systems may not.
Since exception reporting is done on the MAX1000+Plus side no exception reporting is done on PI. Value and quality data are sent to PI when they are received by the interface. Although the scan frequency is not used, the Location4 parameter for all input points must still be set to one.
Hardware Configuration Diagram
Max 1000+PLUSInterface to the PI System1
PI Tag Configuration
MAX1000+ Tag Address Format
The MAX1000+ interface uses a "reference-member" (RefMem) identifier to reference a specific point in MAX1000+. The reference represents the MAX1000+ tag group (or service) in which the tag resides. Member references the actual tag within the specified reference.
General PI Tag Configuration Information
One PI point (PI tag) must be configured for each MAX1000+ member the user wants to read from or write to. The points can be configured on a PI2 or PI3 home node. Each tag from the MAX1000+Plus system may also have quality along with a value. The user can choose to store the quality that comes with each value in a separate PI tag.
The following describes the field names associated with PI point configuration that have specific meaning for use with the MAX1000+ interface. Other fields may also need to be specified for proper configuration of the PI point. Some of these fields include 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.
Tag
This is the name of the PI point.
PointSource
All points to be used by the MAX1000+ 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 PIMAX#.bat startup command file.
PointType
The interface supports all three PI point types for PI2. real R, integer I, and Discrete D and Float16, Float32, Int16, Int32, and Discrete point types for PI3.
Location1
This parameter is used to specify the interface number, which corresponds to the /id=# flag in the PIMAX#.bat file. Valid interface numbers are integer values 1 to 99, inclusive.
Location2
The Location2 field is used to specify if this tag is an input, output or watchdog tag. Possible values are:
0 = Input Tag
1 = Output Tag
2 = Watchdog Tag.
Location3
This parameter is used to indicate whether the PI tag will hold a value or a quality.
0 = value tag
1 = quality tag
Quality tags should be defined as digital tags.
Location4
This field determines the frequency at which a watchdog tag will send data to the SBP. The possible scanning frequencies for a given interface are specified by the user on the command line in the PIMAX#.bat file (see the section entitled “Startup Command File”). Say part of the command line is as follows:
/f=00:00:05 /f=00:00:15 /f=00:01:00,00:00:10
Then, the point can be configured to send a “heartbeat” to the SBP every 5 seconds, every 15 seconds, or every 1 minute. For the 5-second and 15 second periods, heartbeats will begin on the hour or at a multiple of 5 or 15 seconds after the hour. For the 1-minute period, heartbeats will begin 10 seconds after the hour or at a multiple of 1 minute and 10 seconds after the hour. If Location4 is 1 for the above command line, then the watchdog tag will update every 5 seconds. If Location4 is 2, then the tag will update every 15 seconds, and so on.
InstrumentTag
This field is used to specify the RefMem address for MAX1000+. RefMem stands for Reference-Member, and is used to address a specific tag within MAX1000+. Each entry in the RefMem must be separated with a period, with no spaces between the period and text. For example the InstrumentTag field for a PI tag would contain:
[domain]service.member.ext.ext
Typically only the service and member need be specified. An example of this type of address is: FIC101.PVwhere FIC101 is the service and PV is the member of interest.
ExDesc
The ExDesc (Extended Descriptor) is used to specify the member portion of the MAX1000+ point address if not given in the InstrumentTag field.
The member name is placed at the end of the ExDesc field in the following format:
RM=MemberName
This string, if required, must appear the end of the ExDesc field. The “RM=” must be given with capitol letters; however the actual member name should match that given in MAX1000+.
This interface does not support the standard trigger based scanning that uniint supports since all data comes from the MAX1000 Plus+ system on an exception basis.
Scan
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. The digital state SCAN OFF will be written to a tag if the Scan Flag is turned OFF.
SourceTag
The SourceTag field is typically used in conjunction with an output tag. However for input tags this field is used to specify the name of the quality PI tag associated with the PI value tag. Specification of a quality tag is optional.
Excmin, Excmax – Exception Specs
Upon interface startup the interface sends the PI exception parameters for a point to the MAX1000+Plus system for each tag. The MAX1000+Plus will then only send data to the interface when an exception occurs; this includes a data change or when the maximum exception time has been exceeded. The ExcMin time is used to determine how quickly the data on the SBP is refreshed. The minimum allowable refresh rate is 1 second. If a value of 0 is entered for ExcMin, a default of 1 second is used. The ExcMax time, which is the maximum exception time, is passed to the MAX1000+Plus system when tags are subscribed on the MAX1000+Plus system. The MAX1000+Plus system will then send a value back to PI at least every ExcMax seconds. The ExcMax time defaults to 30 seconds. It can be changed using the /excmax flag in the interface startup file. If /excmax isn’t set in the interface startup file and the point is passed an ExcMax value greater then 30 seconds, a value of 30 is used. If /excmax is set in the interface startup file and the point is passed an ExcMax value greater than the /excmax value, the /excmax value is used. Please consult your MAX Control Systems representative for recommendations for exception maximum settings. Typical systems will be able to handle excmax times of 30 seconds for all tags. However older systems may not.
Output Tag Configuration
Output tags are used to send values to the SBP. A tag is an output tag if a 1 is specified in Location2. Values are sent to the SBP only upon an event. An event is triggered in one of two ways, depending upon the configuration of the output tag.
Configuration 1:(Recommended): In this configuration, a value is written to the SBP when an event is detected for a SourceTag. A SourceTag is associated with an output tag through the output tag’s SourceTag field (see the section entitled "PI Point Definition" above). The value of the SourceTag is written to the output tag if the command is successful. The output tag and the SourceTag should be given the same exception specifications (ExcDev, ExcMin, and ExcMax). Otherwise, values that appear in the snapshot of the SourceTag may not appear in the snapshot of the output tag. The PointType of the output tag and SourceTag do not need to be the same, but data loss could result from differences in precision for different PointTypes.
Configuration 2:In this configuration, a value is written to the SBP when an event is detected for the output tag itself. This configuration is enabled if no SourceTag is defined in the output tag’s SourceTag field.
When do "events" occur? An event occurs whenever a value reaches the snapshot of the SourceTag (configuration 1) or the output tag (configuration 2). The actual value of the snapshot does not need to change to trigger an event. For example, say the current value in the snapshot of a SourceTag tag is 51, and say that exception testing is turned on for the SourceTag. Even if the value of the SourceTag does not change, the exception maximum time for the SourceTag will eventually be exceeded. When this happens, a value of 51 will be sent to the snapshot of the SourceTag, triggering an event that will cause a value to be sent to the SBP.
Creation of QualityDigitalState Set
The user must create a digital state set for use with quality tags. A suggested name is MAXQUALITIES. The digital state set must contain the states shown exactly in the order as they appear below.
OTHER, GOOD, NOT KNOWN, DOUBTFUL, SUBSTITUTED, BAD, BAD REF, NO VALUE
The value of OTHER will be given if the returned quality is not one of the known qualities shown above (excluding OTHER).