Metso Plug-In DLL
for OPC
Interface to the PI System
Version 1.00
iii
UniInt End-User Interface to the PI System
How to Contact Us
Phone / (510) 297-5800 (main number)(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web / http://www.osisoft.com
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrabe 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
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. 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.
OPCPluginMetso.doc
Ó 2001 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
iii
UniInt End-User Interface to the PI System
Table of Contents
Introduction 1
Principles of Operation 3
Installation Checklist 5
Plug-In Installation and Administration 7
Plug-In Directory 7
Installation Procedures 7
Define Required Digital States 7
Modify OPCINT.BAT 7
Configure PI Tags 8
Upgrading the Plug-In 9
Moving the Plug-In to a New Directory 9
Uninstalling the Plug-In 9
Error and Informational Messages 11
Message Logs 11
Troubleshooting 11
System Errors and PI Errors 11
Appendix A: Use of AddOpcPluginStates.bat 13
Appendix B: Metso.INI Configuration File 15
Revision History 17
7
Metso Plug-In DLL for OPC Interface to the PI System 7
Introduction
The PI-OPC interface will retrieve all data from an OPC server, but when data stops flowing because of an emergency, the operator needs to know that there is a problem. Without modification, the PI-OPC interface simply shows data when it is available, and ignores the reason it has stopped flowing. PI users need information about a datum’s specific error condition. PI data tags may become invalid for several reasons. A paper machine, for instance, may have a sheet break. In order to get complete information from the sensor gauge (through OPC), a plug-in DLL for the PI-OPC interface has been created by OSIsoft. For the (Valmet-Neles) Metso system, this plug-in is called OPCPluginMetso.DLL.
Note: Neither this manual nor the plug-in are stand-alone products; they are to be used in conjunction with the PI-OPC interface.
7
Metso Plug-In DLL for OPC Interface to the PI System 7
Principles of Operation
The PI-OPC interface connects OPC variables (which are defined by OPC symbols for the specific device) to a PI tag. The OPC symbol for any PI tag is saved in that tag’s ‘instrument tag’ field or ‘extended descriptor’ (see the PI-OPC interface manual for exact tag configuration details). The primary type of data retrieved from paper machines is profile data. These data are configured as array data (please see the PIOPC interface manual for proper configuration of array tags). Data is also available which indicates various statuses of the paper machine as well as the starting and ending boxes for valid profile data.
Every time array data is read, the plug-in, OPCPluginMetso.DLL, examines the statuses associated with that data. If a given status condition is in effect, the plug-in will set the values for some or all of the array data with the system digital state associated with the error condition. If no status condition exists, the array data is sent to PI with no modifications.
Profile data is the only data for which special statuses will be applied. No other tags are affected. The status conditions which may invalidate a profile tag, and the digital state value which that tag acquires in that error condition are as follows:
· OffSheetEdge:
Scanner does not normally reach that data box position. The plug-in will write the digital state, OffSheetEdge, to the profile tags that are in positions less than the start box and which are in positions greater than the end box. Tags specifying the minimum and maximum valid data boxes for each profile are required for the plug-in to perform this function.
· SheetBreak:
Sheet-break has been detected on the frame. All profile tags associated with that scanner will have the status SheetBreak written to them.
· Standardize:
Frame is in standardize mode. All profile tags associated with that scanner will have the status Standardize written to them.
· FrameOffline:
Frame is in a state which does not produce data, such as ‘Dead’, ‘Unavailable’, ‘Emergency Stop’, ‘Manual’, ‘Console Offsheet’, etc., which is not covered by the specific conditions described by other PI states.
· SinglePoint:
Gauge on the same scanner has gone into single-point mode, which disables all gauges on the scanner from normal profile sampling. The results of single-point (or ‘buffered single-point’) sampling may be accessed through other (non-profile) Metso OPC variables (instrument tags).
7
Metso Plug-In DLL for OPC Interface to the PI System 7
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps you in getting the PI-OPC Interface up and running with the OPCPluginMetso.DLL. If you are not familiar with the plug-in, you should return to this section after reading the rest of this manual in detail.
You should follow the steps in the order listed below.
- Install PI-OPC interface.
2. Define required digital states in the System Digital State table
OffSheetEdge
SheetBreak
Standardize
FrameOffline
SinglePoint
- Modify OPCINT.BAT to activate the DLL.
- Configure PI tags.
- Start the interface.
9
Metso Plug-In DLL for OPC Interface to the PI System 9
Plug-In Installation and Administration
Plug-In Directory
The OPCPluginMetso.DLL is on the CD with the PI-OPC interface. It must be copied into the plug-ins subdirectory. For instance, if the interface is installed in
PIHOME\interfaces\opcint
then the DLL should be installed in
PIHOME\interfaces\opcint\plug-ins
Installation Procedures
Although the OPCPluginMetso.DLL is on the CD with the PI-OPC interface, one must configure some things before the DLL will be activated.
Define Required Digital States
OffSheetEdge,SheetBreak, Standardize, FrameOffline, and SinglePoint digital states must be defined before the PI-OPC interface can run with the plug-in. The states are not case sensitive, but they must be spelled exactly as shown.
PI 3 Home Node
For a PI 3 home node, the DLL expects these digital states to be somewhere in the System Digital State Set. There is a program in the plug-ins directory supplied to add these states automatically. See “Appendix A: Use of AddOPCPluginStates.bat,” p13.
PI 2 Home Node
For a PI 2 home node, the expected digital states may be anywhere in the digital state table. You need to add these manually.
Modify OPCINT.BAT
The plug-in, OPCPluginMetso.DLL, is on the CD with the PI-OPC interface and must be copied into the subdirectory called plug-ins underneath the PI-OPC interface directory. The installer must activate the DLL by adding two commands to the batch file, opcint.bat, which specify its location. For example:
opcint.exe /ps=O … ^
/DLL=PIHOME\interfaces\opcint\plug-ins\OPCPluginMetso.DLL ^
/DLL_ini=PIHOME\interfaces\opcint\plug-ins\OPCPluginMetso.INI
After adding the last two lines, the PI-OPC interface will automatically load the plug-in at startup, and manifest Metso-specific behavior. If the interface is already running, you will need to restart the interface for the DLL to be activated.
Note: The “^” shown at the end of all lines in the command file, except for the last line, is a continuation character indicating that more command lines follow.
Configure PI Tags
The plug-in needs extra information from Metso to adjust the profile tags’ status. This is accomplished by creating a few more PI tags. For each Metso scanner (defined by <machine/scanner Id>s named in the IN-file. Ex: “pr:1-S1”), the following tags should be created. The OPC symbol for a Metso variable is in the instrument-tag field of the PItag that will receive its data.
Note: all OPC symbols are case-sensitive.
Starting and Ending Data Boxes
:e:<machine/scannerID>OF0S:c1
First valid box, forward-direction. This is used by the plug-in to determine valid starting data box, when the scanner is moving in the forward direction. For a forward scan, a digital state of OffSheetEdge will be written to each tag in profile array positions from one to the value sent to this tag minus one. Example instrument-tag: “:e:pr:1S1OF0S:c1”.
:e:<machine/scannerID>OF0S:c2
Last valid box, forward-direction. This is used by the plug-in to determine the last valid data box, when the scanner is moving in the forward direction. For a forward scan, a digital state of OffSheetEdge will be written to each tag in profile array positions from the value sent to this tag plus one, to the last tag in the profile.
:e:<machine/scannerID>OF0S:c3
First valid box, reverse-direction. Same information as ‘First-valid-forward-direction’, except applied to reverse-direction scans.
:e:<machine/scannerID>OF0S:c4
Last valid box, reverse-direction. Same information as ‘Last-valid-forward-direction’, except applied to reverse-direction scans.
:e:<machine/scannerID>OF0M:ev20
Forward-direction scan started. This, combined with the following two tags, tells the plug-in whether a particular profile was gathered in the forward or the reverse direction, enabling the plug-in to select the correct first/last box variables. Example instrument-tag: “:e:pr:1-S1OF0M:ev20”.
:e:<machine/scannerID>OF0M:ev21
Forward-direction scan ended. (see above)
:e:<machine/scannerID>OF0M:ev22
Reverse-direction scan started. (see above)
Standardize
:e:<machine/scannerID>OF0MODE:sz
When the scanner goes into standardize mode, the Standardize digital state will get written to each profile tag in all profiles associated with the given scanner. Example instrument-tag: “:e:pr:1-S2OF0MODE:sz” (e.g. machine 1, scanner 2).
SheetBreak
:e:<machine/scannerID>OF0M:ev6
The SheetBreak digital state will get written to each profile tag in all profiles associated with the given scanner. . Example instrument-tag: “:e:pr:2-S1OF0M:ev6” (e.g. machine 2, scanner 1).
SinglePoint
:e:<machine/scannerID>OF0MODE:fp
The SinglePoint digital state will get written to each profile tag in all profiles associated with the given scanner. . Example instrument-tag: “:e:pr:2S3OF0MODE:fp” (e.g. machine 2, scanner 3).
Offline
:e:<machine/scannerID>OF0MODE:sc
‘Scanning’ flag, which, when false, causes all profile tags on that scanner to be marked Offline. Example instrument-tag: “:e:pr:1-S3OF0MODE:sc” (e.g. machine 1, scanner 3).
Upgrading the Plug-In
If the plug-in is upgraded independent of the PI-OPC interface, install the plug-in in the appropriate directory. Then stop and restart the PI-OPC interface according to the instructions in the PI-OPC interface manual.
Moving the Plug-In to a New Directory
Although it is not recommended, it is possible to move the plug-in to a new directory. You will need to change opcint.bat to reflect the name of the new directory and then stop and restart the interface as described in the PI-OPC interface manual.
Uninstalling the Plug-In
If for some reason you want to run the interface without the plug-in, delete the /DLL and /DLL_ini command-line parameters from the batch file, opcint.bat, and stop and restart the PI-OPC interface according to the instructions in the PI-OPC interface manual.
9
Metso Plug-In DLL for OPC Interface to the PI System 9
Error and Informational Messages
Error messages that are written to the message log are pre-pended by a string NameID. Name is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /idflag on the startup command line.
Message Logs
Error and informational messages are written to the pipc.log file. The location of the pipc.log file is determined by the PIHOME entry in the pipc.ini file. The pipc.ini file should always be in the WinNT directory. For example, if the PIHOMEentry is:
C:\PIPC
then the pipc.log file will be located in the c:\PIPC\dat directory.
For version 1.3 and greater of the PI-API, a process called pilogsrv may be installed to run as a service. After the pipc.log file exceeds a user-defined maximum size, the pilogsrv process renames the pipc.log file to pipcxxxx.log, where xxxx ranges from 0000 to the maximum number of allowed log files. Both the maximum file size and the maximum number of allowed log files are configured in the pipc.ini file. Configuration of the pilogsrv process is discussed in detail in the PIAPIInstallationInstructions manual.
Note: No messages are written to the command window when the interface is run interactively. All messages are written to pipc.log.
Troubleshooting
Restarts: The Metso server must be operational before starting the PI-OPC interface.
· Removing the Ethernet cable and reconnecting it while the interface is operating recovers within about one minute and no user action is required.
· Powercycling the API data collector node starts up without user action.
System Errors and PI Errors
System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.
Error Descriptions on NT
On NT, descriptions of system and PI errors can be obtained with the pidiag utility:
\PI\adm\pidiag –e error_number
9
Metso Plug-In DLL for OPC Interface to the PI System 9
Appendix A: Use of AddOPCPluginStates.bat
This option is only available when the PI Home Node is PI 3.
The plug-in requires several new digital states in the PI System Digital State Set that can be built automatically using an application called AddOPCPluginStates. The application consists of the following four files that are located in the plug-ins directory underneath the PI-OPC interface directory:
· AddOPCPluginStates.bat
· NewStates.bat
· AddStates.exe
· MakeDumpSet.exe
All of these files must be moved to the PI\adm directory of your PI 3 home node. They will not function unless moved to the PI home node, in the PI\adm directory. Log in as an administrator, go to a DOS prompt, and move to the PI\adm directory. Make sure PI is running. Invoke:
AddOPCPluginStates
The required digital states will be added to your PI System Digital State Set.
9
Metso Plug-In DLL for OPC Interface to the PI System 9
Appendix B: OPCPluginMetso.INI Configuration File