Max 1000+PLUS
Max 1000+PLUS
Interface to the PI System
Version 1.3.0.1 – 1.4.1.0
Rev D
How to Contact Us
|Phone |(510) 297-5800 (main number) |
| |(510) 297-5828 (technical support) |
|Fax |(510) 357-8136 |
|E-mail |techsupport@ |
|World Wide Web | |
|Mail |OSIsoft |OSI Software, Ltd |
| |P.O. Box 727 |P O Box 8256 |
| |San Leandro, CA 94577-0427 |Symonds Street |
| |USA |Auckland 1035 New Zealand |
| | | |
| |OSI Software GmbH |OSI Software, Asia Pte Ltd |
| |Hauptstra(e 30 |152 Beach Road |
| |D-63674 Altenstadt 1 |#09-06 Gateway East |
| |Deutschland |Singapore, 189721 |
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. HP-UX 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
( 1999-2004 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction 1
Supported Features 1
Diagram of Hardware Connection 3
Principles of Operation 5
Installation Checklist 7
Interface Installation 9
Naming Conventions and Requirements 9
Interface Directories 9
The PIHOME Directory Tree 9
Interface Installation Directory 10
Interface Installation Procedure 10
Installing the Interface as an NT Service – Not Recommended 10
Installing the Interface Service with PI-Interface Configuration Utility 11
Installing the Interface Service Manually 13
Digital States 15
PointSource 17
PI Point Configuration 19
MAX1000+ Tag Address Format 19
General PI Tag Configuration Information 19
Tag 19
PointSource 19
PointType 19
Location1 20
Location2 20
Location3 20
Location4 20
InstrumentTag 21
ExDesc 21
Scan 21
Shutdown 21
SourceTag 22
ExcMin, ExcMax, ExcDev 22
Output Points 22
Trigger Method 1 (Recommended) 23
Trigger Method 2 23
When do "Events" Occur? 23
Quality Points 23
Watchdog Points 24
Performance Point Configuration 25
I/O Rate Tag Configuration 27
Monitoring I/O Rates on the Interface Node 27
Configuring I/O Rate Tags with PI-ICU (NT-Intel) 27
Configuring I/O Rate Tags Manually 28
Configuring the PI Point on the PI Server 29
Configuration on the Interface Node 29
Startup Command File 31
Command-line Parameters 31
Sample Startup Command File 34
Interface Node Clock 35
Security 37
Starting / Stopping the Interface 39
Interactive Startup 39
Automatic Startup – Suggested Method 39
Stopping the Interface 40
Buffering 41
Configuring Buffering with PI-ICU (NT-Intel) 41
Configuring Buffering Manually 44
Example piclient.ini File 45
Appendix A: Communication Error Recovery 47
Appendix B: Troubleshooting 49
Frequently Asked Questions 49
Message Logging 49
Logging Configuration 50
Run Time Logging Configuration 50
Revision History 53
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 PI 3 Server
• An NT PI Interface node with network access to a PI 2 or PI 3 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 PI 2 or PI 3 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 |Support |
|Part Number |PI-IN-MCS-PLUS-NTI |
|Platforms |NT Intel (NT4 – SP6, Windows 2000, Windows XP) |
|PI Point Types |float16, float32, float64, int16, int32, digital |
|Sub-second Timestamps |No |
|Sub-second Scan Classes |N/A (unsolicited data) |
|Automatically Incorporates PI Point Attribute Changes |Yes |
|Exception Reporting |Yes |
|Outputs from PI |Yes |
|Inputs to PI: Scan-Based / Unsolicited / Event Tags |Unsolicited |
|Maximum Point Count |Unlimited |
|Uses PI-SDK |Yes |
|PINet to PI 3 String Support |N/A |
|* Source of Timestamps |maxAPPS (Software Backplane) |
|History Recovery |No |
|* Failover |Interface failover – no |
| |Software Backplane failover - Yes |
|* UniInt-based |Yes |
|* Vendor Software Required on PI-API / PINet Node |Yes |
|* Vendor Software Required on Foreign Device |Yes |
|* Vendor Hardware Required |Yes |
|* Additional PI Software Included with Interface |Yes |
|* Device Point Types |int16, int32, float16, float32, float64, digital |
* See paragraphs below for further explanation.
Source of Timestamps
Timestamps are generated by the maxAPPS software, which is running on the same machine as the interface.
Failover
The Max1000+Plus interface does not itself support failover. However, the Software Backplane does handle failing over from one DPU to another. In most cases, the interface needs to re-subscribe its points after a failover. Virtual DPU as well as physical DPU failover has been tested.
Note: When recovering a failed virtual DPU in primary/backup mode, make sure the backup DPU is started completely before starting the primary DPU. This is to make sure the primary DPU is able to load its point list correctly. Otherwise, re-subscribe attempts will fail.
UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by our developers, and is integrated into many interfaces, such as the PI-IN-MCS-1000PP 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. In any UniInt-based interface, the interface uses some of the UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.
The UniInt End User Document is a supplement to this manual.
Because UniInt version 3.5.8 or later was used to create version 1.4.1.0 or later of the Max1000+Plus interface, msvcp71.dll, msvcr71.dll and atl71.dll are required to be on the interface node. These three dlls are included in the interface install kit on CD, and are also normally installed with Microsoft’s .NET Framework version 1.1. If these files are not installed, then installing version 1.3.1 or greater of the PI-SDK will install them.
Vendor Software Required
Software Backplane is the generic name given to the software that runs between the interface and the DPUs. It consists of several parts. The relevant ones for this interface are maxAPPS and maxSTATION. maxSTATION is the full version of the software distributed by Metso Automation (formerly MAX Controls). It runs on its own machine. maxAPPS is the software that is needed on the interface node.
Vendor Hardware Required
The Software Backplane connects to the DPUs that are used to collect plant data. The DPUs can be physical DPUs or virtual DPUs (software emulation of hardware).
Additional PI Software
The PI-SDK is include on the Max1000+Plus interface CD.
Device Point Types
The Software Backplane supports int16, int32, float16, float32, and float64 point types for data, and digital types for quality reporting.
Diagram of Hardware Connection
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 than 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 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, unsubscribe, 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 InstrumentTag and/or the ExDesc) on the SBP. The exception minimum (ExcMin), exception maximum (ExcMax), and exception deviation (ExcDev) (in engineering units) are also sent to the SBP. The MAX1000+Plus system will check to see if the point subscribed is valid, and if it is valid, can it be accessed. An error code is returned if the point is invalid or cannot be accessed and the interface will print a message that it could not be subscribed.
Note: Some points may not be accessible at interface startup, but 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. If connection is lost to the MAX1000+Plus system, I/O Timeout is written to all the input tags. BAD INPUT is written to points when any other error 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 ExcDev for the point or the ExcMax time has been exceeded with no exception occurring. The ExcMin time controls the frequency at which exceptions are checked. The minimum exception minimum time passed to the MAX1000+Plus system is 1 second. If a tag has its ExcMin 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 ExcMax 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 ExcMax 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 further exception reporting is done within the interface. 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.
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI-Max1000+ interface running. If you are not familiar with PI interfaces, you should return to this section after reading the rest of the manual in detail.
1. Verify that the maxAPPS software is installed and is working correctly.
2. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)
3. Verify that PI-API has been installed.
4. Install the interface.
5. Define digital states, if quality tags are being used.
6. Choose a point source. If PI 2 home node, create the point source.
7. Configure PI points.
Location1 is the interface instance.
Location2 is whether the tag is an input (0), output (1), or watchdog (2) tag.
Location3 is whether the tag is a value (0) or quality (1).
Location4 is the scan class.
Location5 is not used.
ExDesc is not used unless the member portion of the point address is omitted in the InstrumentTag.
InstrumentTag is the point address on the Software Backplane.
8. Configure I/O Rate tag.
9. Edit startup command file using the PI-ICU.
10. Set interface node clock.
11. Set up security.
12. Start the interface without buffering.
13. Verify data.
14. Stop interface, start buffering, start interface.
Interface Installation
OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PI Server node. A PI Interface Node is any node other than the PI Server node where the PI Application Programming Interface (PI-API) has been installed (see the PI-API manual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. 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 Interface Node (once again, see the PI-API 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 Interface 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 pimax.exe and that the startup command file is called pimax.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 pimax1.exe and pimax1.bat for interface number 1, pimax2.exe and pimax2.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.
Interface Directories
The PIHOME Directory Tree
The PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the WinNT directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on the C: drive. OSIsoft recommends using \pipc as the root directory name. The PIHOME directory does not need to be on the C: drive.
Interface Installation Directory
Place all copies of the interface into a single directory. The suggested directory is:
PIHOME\interfaces\max1000pp\
Replace PIHOME with the corresponding entry in the pipc.ini file.
Interface Installation Procedure
The MAX 1000+PLUS interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000. When running on Windows NT 4.0 systems, the MAX 1000+PLUS setup program will install the Windows Installer itself if necessary. To install, run the Max1000pp_x.x.x.x.exe installation kit.
Installing the Interface as an NT Service – Not Recommended
Note: The maxAPPS software does not run as a service. It must be started and running before the MAX1000+PLUS interface can start. It is recommended that the interface not be installed as a service. It is possible to put a line in the maxAPPS initialization routine that will start the interface.
The MAX 1000+PLUS interface service can be created, preferably, with the PI-Interface Configuration & Management Utility, or can be created manually.
Installing the Interface Service with PI-Interface Configuration Utility
The PI-Interface Configuration & Management Utility provides a user interface for creating, editing, and deleting the interface service:
[pic]
Service Configuration
Service Name
The Service to Add box shows the name of the current interface service. This service name is obtained from the interface executable.
Display Name
The Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix “PI-” be appended to the beginning of the interface to indicate that the service is part of the OSI suite of products.
Service Type
The Service Type indicates whether the interface service will start automatically or need to be started manually on reboot.
• If the Auto option is selected, the service will be installed to start automatically when the machine reboots.
• If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.
• If the Disabled option is selected, the service will not start at all.
Generally, interface services are set to start automatically.
Dependencies
The Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependant should be moved into the Dependencies list using the [pic] button. For example, if API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. Often interface services also depend on a vendor program, such as the Fisher-Rosemount chipservice. To remove a service from the list of dependencies, use the [pic] button, and the service name will be removed from the “Dependencies” list.
When the PI Interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the PI interface service will not run.
Note: Please see the PI Log and Operating System Event Logger for messages that may indicate the cause for any server not running as expected.
[pic] - Add Button
To add a dependency from the list of Installed services, select the dependency name, and click the Add button.
[pic] - Remove Button
To remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.
The full name of the service selected in the Installed services list is displayed below the Installed services list box.
Create
The Create button adds the displayed service with the specified Dependencies and with the specified Startup Type.
Remove
The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.
Start or Stop Service
To Start or Stop an interface service, use the Start button [pic] and a Stop button [pic] on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.
The status of the Interface service is indicated in the lower portion of the PI-ICU dialog.
[pic]
Installing the Interface Service Manually
One can get help for installing the interface as a service at any time with the command:
pimax.exe –help
Change to the directory where the pimax1.exe executable is located. Then, consult the following table to determine the appropriate service installation command.
|NT Service Installation Commands on a PI Interface Node or a PI Server node |
|with Bufserv implemented |
|Manual service |pimax.exe –install –depend “tcpip bufserv” |
|Automatic service |pimax.exe –install –auto –depend “tcpip bufserv” |
|NT Service Installation Commands on a PI Interface Node or a PI Server node |
|without Bufserv implemented |
|Manual service |pimax.exe –install –depend tcpip |
|Automatic service |pimax.exe –install –auto –depend tcpip |
When the interface is installed as a service on the PI Server node and when Bufserv is not implemented, a dependency on the PI network manager is not necessary because the interface will repeatedly attempt to connect to the PI Server until it is successful.
Note: Interfaces are typically not installed as automatic services when the interface is installed on the PI Server node.
Check the Microsoft Windows NT services control panel to verify that the service was added successfully. One can use the services control panel at any time to change the interface from an automatic service to a manual service or vice versa.
Digital States
For more information regarding Digital States, refer to the Data Archive Manuals.
PI 2 Home Node
Digital states are defined by running the Digtl Stat display from the PI menu. The states must be contiguous for each status type and may be anywhere within the Digital State Table outside of the range 193 – 320, which is reserved for OSIsoft. The digital states need to be defined prior to point configuration. The digital state sets described in the PI 3 sections below should be entered into the PI 2 Digital State Table.
For more information, see the DA manual.
PI 3 Home Node
Digital State Sets
PI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.
An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.
Creation of Quality Digital State Set
The user must create a digital state set for use with quality tags. A suggested name is MAX1000pp_QUALITIES. 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 other qualities shown above.
System Digital State Set
Similar to digital state sets is the system digital state set. This set is used for all tags, regardless of type to indicate the state of a tag at a particular time. For example, if the interface receives bad data from an interface point, it writes the system digital state bad input to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients.
PointSource
The PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For example, one may choose the letter M to identify points that belong to the interface. To implement this, one would set the PointSource attribute to M for every PI Point that is configured for the interface. Then, if one uses /ps=M on the startup-command line of the interface, the Random interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of M. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the /ps argument.
Case-sensitivity for PointSource Attributes
If the interface is running on a PINet node and the Server node is a PI 3 system, use a capital letter (or a case-insensitive character such as a number, a question mark, etc.) for the PointSource attribute when defining points. For all other scenarios, one does not need to be careful with the case of the PointSource.
In all cases, the point source character that is supplied with the /ps command-line argument is not case sensitive. That is, /ps=M and /ps=m are equivalent. One only needs to be careful with the case of the PointSource during point definition, and only if the interface will be running on a PINet node communicating to a PI 3 Server.
PI 2 Server Nodes
The following point source characters are reserved on PI 2 systems and cannot be used as the point source character for an interface: C, ?, @, Q, T. Also, if one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface.
Before a PI point with a given point source can be created, the point source character must be added to the PI 2 point source table. For example, if point source M is not defined in the PI 2 point source table, a point with a point source of M cannot be created. This prevents the user from accidentally creating a point with an incorrect point source character.
Defining a Point Source Character in the PI 2 Point Source Table
1. Enter PI by typing the following command from a VMS command prompt:
@pisysexe:pi
2. Select the PointSrc option from the menu.
3. Select New from the menu.
4. Assign a point source next to the Code: field. Also, assign minimum and maximum values for the Location1 to Location5 attributes.
|Location 1 |Location 2 |Location 3 |Location 4 |Location 5 |
|1 |0 |0 |1 |-20000000 |
|99 |2 |1 |256 |20000000 |
5. Select “Save” from the menu.
PI 3 Server Nodes
No point source table exists on a PI 3 Server, which means that points can be immediately created on PI 3 with any point source character. Several subsystems and applications that ship with PI 3 are associated with default point source characters. The Totalizer Subsystem uses the point source character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Either do not use these point source characters or change the default point source characters for these applications. Also, if one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface.
PI Point 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 PI 2 or PI 3 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 PI point attributes 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 (PI 2 only), filter code, etc. The user may also wish to create I/O Rate Tags for each interface.
The attribute names used below are consistent with the names in the Data Archive Manual for PI 3.
Tag
A tag is a label or name for a point. Any tag name can be used in accordance to the normal PI point naming conventions.
PointSource
The PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the /ps command-line argument and the “Point Source” section.
PointType
Typically, device point types do not need to correspond to PI point types. For example, integer values from a device can be sent to floating point or digital PI tags. Similarly, a floating-point value from the device can be sent to integer or digital PI tags, although the values will be truncated.
PI 2 Server Nodes
Scaled real, full-precision real, integer, and digital point types are supported on PI 2 Servers. For more information on the individual point types, refer to the Data Archive (DA) section of PI System Manual I.
PI 3 Server Nodes
Float16, float32, float 64, int16, int32, and digital, point types are supported on PI 3 Servers. For more information on the individual point types, see PI Server manuals.
Note: Make Quality and Watchdog tags digital.
Location1
Location1 indicates to which copy of the interface the point belongs.
Location2
The Location2 attribute is used to specify whether this tag is an input, output or watchdog tag. Possible values are:
0 = Input Tag
1 = Output Tag
2 = Watchdog Tag.
Location3
This attribute is used to indicate whether the PI tag will hold a value or a quality.
0 = Value tag
1 = Quality tag
Location4
Input and Output Tags
Location4 should be set to 1.
Note: 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.
Watchdog Tags
Location4 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 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 attribute 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 attribute for a PI tag would contain:
[domain]service.member.ext.ext
Typically only the service and member need to be specified. An example of this type of address is: FIC101.PV where 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.
The member name is placed at the end of the ExDesc attribute in the following format:
RM=MemberName
This string, if required, must appear the end of the ExDesc attribute. The RM= must be given with capital letters; however the actual member name should match that given in MAX1000+.
Scan
By default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when the interface starts, SCAN OFF will be written to the PI point. If the scan attribute is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to the PI point after the point edit is detected by the interface.
There is one other situation, which is independent of the Scan attribute, where UniInt will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed from the interface, and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point.
Shutdown
PI 2 Server Nodes
The Shutdown attribute is not used if the server node is a PI 2 system. For information on configuring shutdown events for PI 2, see Data Archive (DA) section 4.2.3 of PI System Manual I.
PI 3 Server Nodes
The shutdown attribute is used only if the server node is a PI 3 system.
The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Server manuals.
Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the interface when the /stopstat=Shutdown command-line argument is specified.
One can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, one can change the default behavior of the PI Shutdown Subsystem to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Server manuals.
Bufserv
It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shut down, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.
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, ExcDev
See the section Principles of Operation for information on how these attributes are used with this interface.
Output Points
Output points control the flow of data from the PI Data Archive to any destination that is external to the PI Data Archive, such as a PLC or a third-party database. For example, to write a value to a register in a PLC, one would use an output point. Each interface has its own rules for determining whether a given point is an input point or an output point. There is no de facto PI point attribute that distinguishes a point as an input point or an output point.
Outputs are triggered for UniInt-based interfaces. That is, outputs are typically not scheduled to occur on a periodic basis. There are two mechanisms for triggering an output.
Trigger Method 1 (Recommended)
For trigger method 1, a separate trigger point must be configured. The output point must have the same point source as the interface. The trigger point can be associated with any point source, including the point source of the interface. Also, the point type of the trigger point does not need to be the same as the point type of the output point.
The output point is associated with the trigger point by setting the SourceTag attribute of the output point equal to the tag name of the trigger point. An output is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous value that was sent to the Snapshot to trigger an output, but the timestamp of the new value must be more recent than the previous value. If no error is indicated, then the value that was sent to the trigger point is also written to the output point. If the output is unsuccessful, then an appropriate digital state that is indicative of the failure is usually written to the output point. If an error is not indicated, the output still may not have succeeded because the interface may not be able to tell with certainty that an output has failed.
Trigger Method 2
For trigger method 2, a separate trigger point is not configured. To trigger an output, write a new value to the Snapshot of the output point itself. The new value does not need to be different than the previous value to trigger an output, but the timestamp of the new value must be more recent than the previous value.
Trigger method 2 may be easier to configure than trigger method 1, but trigger method 2 has a significant disadvantage. If the output is unsuccessful, there is no tag to receive a digital state that is indicative of the failure, which is very important for troubleshooting.
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.
Quality Points
Quality tags are declared by setting the tag’s Location3 field to a 1. An input tag can then specify this quality tag in its SourceTag field. When data is sent from the SBP, its quality is then written to this quality tag.
Quality tags must be of Digital data type. Also, the DigitalSet field of a quality tag must match the digital set created for qualities as described above. Failure to meet these requirements will cause the quality tag to report erroneous data.
Watchdog Points
A watchdog tag is used as a software “heartbeat.” It creates a timer in the local status server set for a 60-second timeout.
For the tag to function correctly it needs two things. The first is a service name to use as the destination. This is specified in the tag’s InstrumentTag field. On startup, the interface will create a service in the local status server using the name given in this field. The second thing the tag needs is a heartbeat interval. Location4 corresponds with the desired heartbeat interval. See the description of Location4 above for a detailed explanation of specifying heartbeat intervals.
While operational, the tag automatically sets the timer to 60 seconds at the interval given in Location4. Therefore, the interval referenced by Location4 should be considerably less than 60 seconds. In the event that the interface fails to reset the timer before the 60-second time limit, an alarm will be raised in the newly created service.
The actual value stored in the PI tag when it is fully operational is the digital state Good. Should the target SBP item become unreachable, the digital state I/O Timeout is written to the watchdog tag.
While the watchdog tag is operational, one can view the current state of the timer by subscribing to the SBP item ServiceName.time left. However, the user must ensure that this subscription does not occur before the service is created. Failure to meet this requirement would cause the subscription attempt to fail.
Performance Point Configuration
Because input to this interface is unsolicited and not based on scanning frequency, performance points are not applicable.
I/O Rate Tag Configuration
An I/O Rate point can be configured to receive 10-minute averages of the total number of exceptions per minute that are sent to PI by the interface. An exception is a value that has passed the exception specifications for a given PI point. Since 10-minute averages are taken, the first average is not written to PI until 10 minutes after the interface has started. One I/O Rate tag can be configured for each copy of the interface that is in use.
Monitoring I/O Rates on the Interface Node
For NT and UNIX nodes, the 10-minute rate averages (in events/minute) can be monitored with a client application such as ProcessBook.
Configuring I/O Rate Tags with PI-ICU (NT-Intel)
The PI-Interface Configuration & Management Utility (PI-ICU) provides a user interface for creating and managing IORates Tags.
[pic]
PI-ICU currently allows for one I/O Rate tag to be configured for each copy of the interface that is in use. Some interfaces allow for multiple I/O Rates tags.
Enable IORates for this Interface
The Enable IORates for this interface check box enables or disables IORates for the current interface. To disable IORates for the selected interface, uncheck this box. To enable IORates for the selected interface, check this box.
Tag Status
The Tag Status column indicates whether the IORates tag exists in PI. The possible states are:
• Created – This status indicates that the tag exist in PI
• Not Created – This status indicates that the tag does not yet exist in PI
• Deleted – This status indicates that the tag has just been deleted
• Unknown – This status indicates that the ICU is not able to access the PI Server
In File
The In File column indicates whether the IORates tag listed in the tag name and the event counter is in the IORates.dat file. The possible states are:
• Yes – This status indicates that the tag name and event counter are in the IORates.dat file
• No – This status indicates that the tag name and event counter are not in the IORates.dat file
Event Counter
The Event Counter correlates a tag specified in the iorates.dat file with this copy of the interface. The command line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file.
Tagname
The tag name listed under the Tagname column is the name of the IORates tag.
Snapshot
The Snapshot column holds the snapshot value of the IORates tag, if the IORates tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the interface is first loaded.
Right Mouse Button Menu Options
Create
Create the suggested IORates tag with the tag name indicated in the Tagname column.
Delete
Delete the IORates tag listed in the Tagname column.
Rename
Allows the user to specify a new name for the IORates tag listed in the Tagname column.
Add to File
Adds the tag to the IORates.dat file with the event counter listed in the Event Counter Column.
Search
Allows the user to search the PI Server for a previously defined IORates tag.
Configuring I/O Rate Tags Manually
There are two configuration steps.
Configuring the PI Point on the PI Server
PI 2 Server Nodes
A listing of the I/O Rate Tags that are currently being monitored can be obtained with the command:
@PISysDat:
Create an I/O Rate Tag using one of the existing I/O Rate Tags as a template.
PI 3 Server Nodes
Create an I/O Rate Tag with the following point attribute values.
|Attribute |Value |
|PointSource |L |
|PointType |float32 |
|Compressing |0 |
|ExcDev |0 |
Configuration on the Interface Node
For the following examples, assume that the name of the PI tag is max1000pp001, and that the name of the I/O Rate on the home node is max1000pp001.
1. Edit/Create a file called iorates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the pipc.ini file, which is located in the \WinNT directory. If both are specified, the PIPCSHARE entry takes precedence.
Since the PIHOME directory is typically C:\PIPC, the full name of the iorates.dat file will typically be C:\PIPC\dat\iorates.dat.
Add a line in the iorates.dat file of the form:
max1000pp001, x
where max1000pp001 is the name of the I/O Rate Tag and x corresponds to the first instance of the /ec=x flag in the startup command file. X can be any number between 2 and 34 or between 51 and 200, inclusive. To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the iorates.dat file. The event counter, /ec=x, should be unique for each copy of the interface.
2. Set the /ec=x flag on the startup command file of the interface to match the event counter in the iorates.dat file.
The interface must be stopped and restarted in order for the I/O Rate tag to take effect. I/O Rates will not be written to the tag until 10 minutes after the interface is started.
Startup Command File
The MAX1000+ interface requires several command-line parameters for successful execution. For convenience, the parameters are defined in a startup command file called PIMAX.bat. A sample PIMAX.bat.new file is included on the installation disks.
Command-line arguments can begin with a / or with a -. For example, the /ps=M and –ps=M command-line arguments are equivalent.
For NT, command file names have a .bat extension. The NT continuation character (^) allows one to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of flags is unlimited, and the maximum length of each flag is 1024 characters.
The PI-Interface Configuration & Management Utility (PI-ICU) provides a tool for configuring the Interface startup command file.
This interface does not have a PI-ICU Control, but this screen shot shows where the startup parameters are to be entered in standard command line fashion:
[pic]
Command-line Parameters
|Parameter |Description |
|/id=# |Defines a unique identifier (#) between 1 and 99 for each version of the interface|
|Required |that is running. The identifier corresponds to location1 of the PI tag |
| |definition. |
|/ps=x |Defines the point source x, where x can be any single character. A corresponding |
|Required |point source must be defined on the PI2 or PI3 home node. |
|/f=hh:mm:ss |Defines the time period in between scans in terms of hours (hh), minutes (mm), and|
|Required |seconds (ss). Several time periods can be defined on a single command line. |
| |Location4 determines which time period is used. |
|/excmax=x |This parameter specifies the maximum exception time, which is the maximum value |
|default: 30 seconds |that a tag’s excmax attribute can be set to in seconds. If the /excmax parameter |
| |isn’t set, the maximum exception maximum time is 30 seconds. Please consult your |
| |MAX Control Systems representative for recommendations for exception maximum |
| |settings, usually this value should be 30. |
|/subchk=x |This parameter specifies the amount of time (in seconds) the interface should wait|
|default: 30 seconds |between unsuccessful subscription attempts. Setting this too low will cause |
| |unnecessary network traffic and will use more processor time. |
|/host=host:port |The /host flag is used to specify the PI Home node. Host is the IP address of the|
|Optional |PI Sever node or the domain name of the PI Server node. Port is the port number |
| |for TCP/IP communication. The port is always 5450 for a PI 3 Server and 545 for a |
| |PI 2 Server. It is recommended to explicitly define the host and port on the |
| |command line with the /host flag. Nevertheless, if either the host or port is not |
| |specified, the interface will attempt to use defaults. |
| |Defaults: |
| |The default port name and server name is specified in the pilogin.ini or |
| |piclient.ini file. The piclient.ini file is ignored if a pilogin.ini file is |
| |found. Refer to the PI-API manual for more information on the piclient.ini and |
| |pilogin.ini files. |
| |Examples: |
| |The interface is running on a PI Interface Node, the domain name of the PI 3 home |
| |node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host flags |
| |would be: |
| |/host=marvin |
| |/host=marvin:5450 |
| |/host=206.79.198.30 |
| |/host=206.79.198.30:5450 |
|/sn |When this flag is specified on the command-line, then all exception reporting is |
|Required |disabled. The flag must be specified since exception reporting is already done on|
| |MAX1000+. |
|/stopstat |If the /stopstat flag is present on the startup command line, then the |
|or |digital state Intf shut will be written to each PI Point when the interface is |
|/stopatat= |stopped. |
|digstate |If /stopstat=digstate is present on the command line, then the digital state, |
|Default: |digstate, will be written to each PI Point when the interface is stopped. For a PI|
|/stopstat= |3 Server, digstate must be in the system digital state table. For a PI 2 Server, |
|”Intf shut” |where there is only one digital state table available, digstate must simply be |
|Optional |somewhere in the table. UniInt uses the first occurrence in the table. |
| |If neither /stopstat nor /stopstat=digstate is specified on the command line, then|
| |no digital states will be written when the interface is shut down. |
| |Examples: |
| |/stopstat=”Intf shut” |
| |The entire parameter is enclosed within double quotes when there is a space in |
| |digstate. |
|/q |When the /q flag is present, Snapshots and exceptions are queued before they are |
|Optional |sent to the PI Server node. |
| |The maximum queue size is 255 bytes for a PI 3 Server and 36 bytes for a PI 2 |
| |Server. For example, if the interface is running on a UNIX node and is |
| |communicating to a PI 2 Server, then the maximum queue size is 36. The queue is |
| |flushed between scans if it is not filled. |
| |When the /q flag is specified in non-extended API mode, the PI-API sends integer |
| |values as 16-bit integers instead of 32-bit integers. Therefore, integer points |
| |will be limited to values between 0 and 32767. Values higher than 32767 need to be|
| |sent to floating-point PI tags. |
|/ec=x |The first instance of the /ec flag on the command line is used to specify a |
|Optional |counter number, x, for an I/O Rate point. If x is not specified, then the default |
| |event counter is 1. Also, if the /ec flag is not specified at all, there is still |
| |a default event counter of 1 associated with the interface. If there is an I/O |
| |Rate point that is associated with an event counter of 1, each copy of the |
| |interface that is running without /ec=x explicitly defined will write to the same |
| |I/O Rate point. This means that one should either explicitly define an event |
| |counter other than 1 for each copy of the interface or one should not associate |
| |any I/O Rate points with event counter 1. Configuration of I/O Rate points is |
| |discussed in the section called “I/O Rate Tag Configuration,” p. 3. |
| |For interfaces that run on NT nodes, subsequent instances of the /ec flag may be |
| |used by specific interfaces to keep track of various input or output operations. |
| |One must consult the interface-specific documentation to see whether subsequent |
| |instances of the /ec flag have any effect. Subsequent instances of the /ec flag |
| |can be of the form /ec*, where * is any ASCII character sequence. For example, |
| |/ecinput=10, /ecoutput=11, and /ec=12 are legitimate choices for the second, |
| |third, and fourth event counter strings. |
|/sio |The /sio flag stands for “suppress initial outputs.” The flag applies only for |
|Optional |interfaces that support outputs. If the /sio flag is not specified, the interface |
| |will behave in the following manner. |
| |When the interface is started, the interface determines the current Snapshot value|
| |of each output tag. Next, the interface writes this value to each output tag. In |
| |addition, whenever an individual output tag is edited while the interface is |
| |running, the interface will write the current Snapshot value to the edited output |
| |tag. |
| |This behavior is suppressed if the /sio flag is specified on the command line. |
| |That is, outputs will not be written when the interface starts or when an output |
| |tag is edited. In other words, when the /sio flag is specified, outputs will only |
| |be written when they are explicitly triggered. |
|/pisdk=x |This parameter tells the interface whether or not to use the PI-SDK in retrieving |
|Optional |the point attributes. Set to 1 to enable the PI-SDK. This is useful if an |
|Default: 0 (no) |instrumenttag field needs to be longer than 32 characters. The PI-SDK must be |
| |installed if this option is set to 1. |
|/L=fff |This parameter specifies the logging configuration file. The interface provides |
|Optional |logging facilities beyond the standard PI logging. See the section on Operation |
| |Logging later in this manual for a full explanation. |
Sample Startup Command File
The following is a sample command line, and brief explanation of what it will do when run.
PIMax /host=localhost:5450 /id=1 /ps=M /f=00:00:30 /sn /stopstat=”Intf Shut" /excmax=30 /subchk=30 /pisdk=0 /q
This command line will create a new PI-Max1000+Plus session with an identification number of one. The interface will only be concerned with tags with PointSource “M.” Watchdog tags whose Location4 parameter is set to 1 will send heartbeats to the SBP every 30 seconds. PI exception reporting is turned off and when the interface stops, it will write the digital state Intf Shut to all configured input tags. The maximum exception reporting time is set to 30 seconds. The subscription retry rate is set to 30 seconds. Data will be sent to the PI server running on the local machine. Data will be queued before being sent.
Interface Node Clock
The correct settings for the time and time zone should be set in the Date/Time control panel. If local time participates in Daylight Savings, from the control panel, configure the time to be automatically adjusted for Daylight Savings Time. The correct local settings should be used even if the interface node runs in a different time zone than the PI Server node.
Make sure that the TZ environment variable is not defined. The currently defined environment variables can be listed by going to Start | Settings | Control Panel, double clicking on the system icon, and selecting the environment tab on the resulting dialog box. Also, make sure that the TZ variable is not defined in an autoexec.bat file. When the TZ variable is defined in an autoexec.bat file, the TZ variable may not appear as being defined in the System control panel even though the variable is defined. Admittedly, autoexec.bat files are not typically used on NT, but this does not prevent a rogue user from creating such a file and defining the TZ variable unbeknownst to the System Administrator.
Security
If the home node is a PI 3 Server, the PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Data Archive. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server manuals.
Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.
See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.
If the home node is a PI 2 Server, the read/write permissions should be set appropriately in the pisysdat:piserver.dat file on the PI 2 home node. For more information on setting permissions on PI 2, see the pibuild:piserver.txt file on the PI 2 home node.
If the interface cannot write data to a PI 3 Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.
Starting / Stopping the Interface
Note: Do not run this interface as a Service. This means the PI-ICU should not be used to start this interface.
Interactive Startup
If both PI and the MAX1000+Plus interface are started interactively, one can start both of them with
pistart.bat
Alternatively, one can start the interface independently of the PI Data Archive by typing the following command from the interfaces\ directory:
start "MAX" Max1000+Plus\PIMAX.bat
Or one can issue the following command from the interfaces\ directory:
Max1000+Plus\PIMAX.bat
When start "MAX"… command is used, a new MsDos window is created.
Automatic Startup – Suggested Method
The PI-MAX1000+Plus interface must run in the foreground because the MAX1000+Plus programs do not run as services and it is imperative that the MCS program start up prior to the interface. The PI-Max1000+Plus interface startup and shutdown procedures can be automated through the use of the MaxStation startup script. The MaxStation startup script should also be used to automate the startup and shutdown of the PI Buffering program. The PI Buffering program, Bufserv, should not be set up to run as a service since it will be stopped and started in conjunction with the MAX1000+Plus processes. This script allows the user to customize which applications should start when the system is started and in what order. The programs listed in the Startup.ini file will be automatically started when the user logs in to the system as Engineer.
To instigate automatic startup, add the interface and the Bufserv program to the end of the MaxStation Startup.ini file. This file is typically found in c:\mcs\sbp. It should already contain commands for automatically starting the RRS, LSS, MaxTransport and several other programs.
Note – all entries into the Startup.ini file are case sensitive and all entries specifying program paths and program titles must be specified exactly as they appear.
The format for specifying a program to start is:
Delay, Path to Program, Program Title, Program Arguments
Delay represents the number of seconds that MaxStation should wait after starting the previous program before starting this one. It may take several seconds (several minutes in some cases) to register all available SBP items with RRS. The delay value must be long enough to allow all items to be registered. If the delay is too short, some subscriptions could fail.
Path to Program is the fully qualified path to the program executable (Pi-Max#.exe in this case).
Program Title is the name of the program. It must exactly match the title bar of the program’s window. In most cases this will be c:\PathToInterface\PiMax.exe (ie. it mimics the path to program). It is crucial that this parameter be entered correctly if the user wishes to have the interface shutdown automatically.
Program Arguments specifies all command line parameters that are to be passed to the interface. All command line arguments must appear in this field and not in the path to program.
Note: Separate specification of program arguments is not necessary since a bat file will be used to specify the program arguments for the interface.
An example Startup.ini file might look like this:
0, C:\MCS\Sbp\MAXrrs.exe, MAXrrs
6, C:\MCS\Sbp\MAXlss.exe, MAX1000 Local Status Server
0, C:\MCS\Sbp\MaxTransport.exe, MAX1000 + Plus Transport Daemon
120, C:\PIPC\bin\bufserv, C:\WINNT\System32\cmd.exe
5, C:\PIPC\interfaces\max\pimax#1.bat, C:\WINNT\System32\cmd.exe
Stopping the Interface
One can stop the MAX1000+Plus interface by 1) selecting the Ms Dos window that corresponds to the MAX# interface, and 2) holding down the control key while typing the letter c (note that there is no pisitestop.bat file to correspond to the pisitestart.bat file).
If the interface was started automatically using the MaxStation Startup.ini file, it can be shutdown by shutting down the MaxStation. This requires that the Program Title field in Startup.ini exactly matches the title bar of the Ms Dos window that corresponds to the interface. If this field does not match, the interface will not shutdown.
The interface and Bufserv will be stopped if the system is shutdown. The programs will be shut down in reverse order from that specified in the Startup.ini file. Do not stop the interface prematurely from the system dialogue box.
Buffering
For complete information on buffering, please refer to the .
PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI-API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process.
Note: Change the Local Security Policy on Windows XP.
1. Open "Administrative Tools" from the control panel.
2. Open "Local Security Policy" from administrative tools.
3. Browse to "Security Options" under "Local Policies."
4. Double click on "System Objects: Default owner for objects created by members of the Administrators group."
5. Change the dropdown from "Object Creator" to "Administrators group."
The behavior of Bufserv should now be the same on XP as it was for NT4 and 2000.
Configuring Buffering with PI-ICU (NT-Intel)
Buffering is enabled through the PI-Interface Configuration Utility’s Tools>API Buffering… menu. Unless buffering is explicitly enabled, the PI-API will not buffer data, sending data directly to the home node.
The API Buffering… dialog allows the user to view and configure the parameters associated with the API Buffering (bufserv) process. The user can start and stop the API Buffering process from the Service tab:
[pic]
Service Tab
The Service tab allows for some API Buffering service configuration. For further configuration changes, use the Services applet.
Service Name
The Service name displays the name of the API Buffering Service.
Display Name
The Display name displays the full name associated with the API Buffering service.
Log On As
Log on as indicates the Windows user account under which the API Buffering service is setup to start automatically on reboot, or manually. To modify the user account or password under which bufserv runs, use the Microsoft Windows “Services” applet.
Dependencies
The Dependencies lists the Windows services on which the API Buffering service is dependent.
Service Startup Type
The Startup Type indicates whether the API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled.
• If the Auto option is selected, the service will be installed to start automatically when the machine reboots.
• If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.
• If the Disabled option is selected, the service will not start at all.
Note: Bufserv, should not be set up to run as a service since it will be stopped and started in conjunction with the MAX1000+Plus processes.
Generally, the API Buffering service is set to start automatically.
Start / Stop Service
The Start / Stop buttons allow for the API Buffering service to be started and stopped.
After a change is made to any of the settings on the Settings tab, the Save button must be clicked, and then the service must be stopped and restarted for the changes to be picked up by bufserv.
Settings Tab
The Settings tab allows for configuration of the 7 configurable settings used by API Buffering. Default values are used if no other value is provided.
[pic]
Enable API Buffering
Enables the API Buffering feature.
Maximum File Size
Maximum buffer file size in kilobytes before buffering fails and discards events. Default value is 100,000. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Send Rate
Send rate is the time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds). Default value is 100. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Primary Memory Buffer Size
Primary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Secondary Memory Buffer Size
Secondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Max Transfer Objects
Max transfer objects is the maximum number of events to send between each SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Pause Rate
When buffers are empty the buffering process will wait for this number of seconds before attempting to send more data to the home node. Default value is 2. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Retry Rate
When the buffering process discovers the home node is unavailable it will wait this number of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Max Theoretical Send Rate
This is the theoretical max send rate is calculated like this:
max = MAXTRANSFEROBJS / SENDRATE * 1000
Default value is 5000.
There are no additional steps needed to install buffering after installing the PI-API. The delivered PI-API library supports both buffered and un-buffered calls.
Configuring Buffering Manually
Buffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI-API will not buffer data, sending data directly to the home node.
There are no additional steps needed to install buffering after installing the PI-API. The delivered PI-API library supports both buffered and un-buffered calls.
Note: When buffering is configured to be on, the bufserv process must be started before other programs using the PI-API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.
Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the dat subdirectory of the PIHOME directory (typically c:\pipc\dat) under Windows NT. This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad on Windows) to the desired values.
The following settings are available for buffering configuration:
|Keywords |Values |Default |Description |
|BUFFERING |0,1 |0 |Turn off/on buffering. OFF = 0, ON = 1, |
|PAUSERATE |0 – 2,000,000 |2 |When buffers are empty the buffering process will wait for|
| | | |this long before attempting to send more data to the home |
| | | |node (seconds) |
|RETRYRATE |0 – 2,000,000 |120 |When the buffering process discovers the home node is |
| | | |unavailable it will wait this long before attempting to |
| | | |reconnect (seconds) |
|MAXFILESIZE |1 – 2,000,000 |100,000 |Maximum buffer file size before buffering fails and |
| | | |discards events. (Kbytes) |
|MAXTRANSFEROBJS |1 – 2,000,000 |500 |Maximum number of events to send between each SENDRATE |
| | | |pause. |
|BUF1SIZE |64 – 2,000,000 |32768 |Primary memory buffer size. (bytes) |
|BUF2SIZE |64 – 2,000,000 |32768 |Secondary memory buffer size. (bytes) |
|SENDRATE |0 – 2,000,000 |100 |The time to wait between sending up to MAXTRANSFEROBJS to |
| | | |the server (milliseconds) |
In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define the default PI server and an optional time offset change that may occur between the client and server.
|Keywords |Values |Default |Description |
|PIHOMENODE |string |none |Windows default server is in pilogin.ini |
|DSTMISMATCH |0 – 2,000,000 |0 |The time that the server and client local time |
| | | |offset is allowed to jump. Typically, 3600 if the |
| | | |nodes are in time zones whose DST rules differ |
| | | |(seconds) |
Example piclient.ini File
On Windows NT the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds meaning wait 10 minutes after losing a connection before retrying.
On NT a piclient.ini file might look like:
[APIBUFFER]
BUFFERING=1
MAXFILESIZE=100000
; The PI-API connection routines have a 1 minute default timeout.
RETRYRATE=600
Appendix A:
Communication Error Recovery
If a remote MAX1000+Plus node "goes down" (becomes inoperable), the tags associated with that node will return an error code to PI (I/O Timeout), and will not report any future values to PI until the remote node becomes operable again. Once the remote node is operable, the interface automatically starts sending data to PI.
Prior to version 1.3, there was an issue with the communication error recovery. The situation occurred when there was no active DPU. There are several situations where there is no active DPU.
One situation is when there is only one DPU, and that DPU either fails or is pulled out for replacement or maintenance. Another situation is when there is more than one DPU, but backup mode is not enabled. In this case, there may be other DPUs on the network, but they will not become active because backup mode is not enabled.
Prior to version 1.3, when the DPU once again became available, the interface would not resume collecting data. This was a subscription issue, and has been corrected in version 1.3.
Appendix B:
Troubleshooting
If the interface is behaving in an unexpected manner, check the pipc.log file and the user-specified log file. (Not all error messages are written to the screen). In general, the user-specified log file will contain greater detail then the pipc.log file.
Frequently Asked Questions
Q. As soon as I start the interface, it exits. What could cause this?
A. First, check the log files. A detailed explanation may be found there. Common causes may be:
• PI is not running on the specified host
• MAX1000+ is not running locally
• a required interface DLL is missing (see "Error! Reference source not found.")
Q. Why does it take several minutes to see new values after I add a new tag while the interface is running?
A. The interface checks for changes in the PI point database every two minutes. Any new values won’t be sent to PI until the first scan after the tag was added.
Q. Why do I constantly get a timed-out status for tags on a remote node?
A. Most likely, the remote MAX1000+ node is not running. If the node is running, check the tag configuration to make sure that the proper node, tag, and field have been specified.
Q. My PI values are not being updated, but the log files show that data is being sent to the interface.
A. Check the permissions of your PI tags. If the user of the interface doesn’t have access to read and write the given PI tags, they won’t be updated.
Message Logging
The MAX1000+ interface provides extensive run-time operation logging facilities. The logging facility provides the following capabilities:
• Multiple detail levels: low, medium, high, none, all;
• A forced writes option that, when enabled, commits all data to the drive after each write (slows the process significantly);
• A screen logging option that will echo the log entries to the console;
• Ability to append or overwrite existing log;
• Circular log file format with selectable size; and
• A common log file viewer for Windows95 and Windows NT.
Logging Configuration
These options can set or selected using a logging configuration file. The configuration file is a text file with a “loose” format, that is, only lines beginning with a minus sign (-) are treated as parameters, and all parameters are case-insensitive. Any parameters not included in the file will be set to the default values.
The following parameters are supported:
-F = forced writes, either TRUE or FALSE, default=FALSE
-D = detail level, 0 to 9 (see table later in this appendix) default=LOG_MEDIUM
-L = logfile name, required
-M = max logfile size, in bytes, default=50000
-N = start new file, either TRUE or FALSE, default=TRUE
-S = enable screen logging, either TRUE or FALSE, default=TRUE
There are no limits on the size or filename of the configuration file. A sample configuration file is shown below.
** Set log level to LOG_MEDIUM
-D2
** Set log filename
-Lc:\temp\test.log
** Enable screen logging
-Strue
** Set max logfile size to 10K
-M10240
Run Time Logging Configuration
The user has the ability to change the operation of the logging facilities at runtime by creating several Logging Tags. The logging tags provide a mechanism for changing the logging configuration during run-time. When the logging configuration needs to be changed, a value can be written to the appropriate tag. For each possible logging configuration change, there is a specific PI tag.
The following table describes the configuration changes that are permitted and the associated tags and values:
|Configuration Parameter |Tagname |Appropriate Values |
|Detail level |$LOG_LEVEL |9 = All logs |
| | |8 = No logs |
| | |3 = High detail |
| | |2 = Medium detail |
| | |1 = Low detail |
|Log to screen |$LOG_SCREEN |0 = off, 1 = log to screen |
|Enable forced writes |$LOG_FORCED |0 = off, 1 = writes committed immediately |
All logging tags must be configured as output tags of type Integer. No source point parameter is required.
Revision History
|Date |Author |Comments |
|18-May-99 |TC |First draft |
|12-Aug-99 |TC |Second draft |
|18-Oct-99 |JFZ |Updated document based on trip to test at MCS |
|04-Nov-99 |TC |Revision 2 – Draft 1 |
|05-Jul-00 |EW |Added explanation of /excmax flag |
|26-Apr-02 |CG |Formatting, TOC |
|15-Nov-02 |LNG |Updated for version 1.3. Added /subchk flag and clarified that |
| | |MaxStation software does not need to be running on the same |
| | |machine as the interface. |
|26-Nov-02 |CG |Fixed headers & footers; fixed page #s; changed some section |
| | |headings; does not conform to standard document format |
|01-Aug-03 |LNG |Added “and greater” to the version, for 1.3.0.1 release. |
| | |Added version requirement for maxAPPS. |
| | |Added supported Windows versions. |
| | |Added /pisdk option to the list of startup parameters. |
|17-May-04 |LNG |Updated version to 1.4.1.0 |
|17-May-04 |CG |1.4.1.0 Rev C: Fixed headers & footers; clarified running as a |
| | |service; used current skeleton formatting |
|19-May-04 |CG |1.4.1.0 Rev D: Fixed the part number |
| | | |
| | | |
[pic]
-----------------------
DPU
PI
PI-Max1000+Plus
Interface
DPU
Software Backplane
DPU
Status of the ICU
Status of the Interface Service
Service installed or uninstalled
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.