Generic Plug-In DLL for OPC DA Interface to the PI System
Total Page：16
File Type：pdf, Size：1020Kb
Generic Plug-In DLL for OPC Interface to the PI System
Version 2.3.11.0 Revision A
Copyright © 2001-2009 OSIsoft, Inc. OSIsoft, Inc. OSIsoft Australia 777 Davis St., Suite 250 Perth, Australia San Leandro, CA 94577 USA Auckland, New Zealand (01) 510-297-5800 (main phone) OSI Software GmbH (01) 510-357-8136 (fax) (01) 510-297-5828 (support phone) Altenstadt, Germany http://techsupport.osisoft.com OSIsoft Asia Pte Ltd. [email protected] Singapore Houston, TX Johnson City, TN OSIsoft Canada ULC Longview, TX Montreal, Canada Mayfield Heights, OH Calgary, Canada Philadelphia, PA Phoenix, AZ OSIsoft, Inc. Representative Office Savannah, GA Shanghai, People’s Republic of China Yardley, PA OSIsoft Japan KK Tokyo, Japan OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico OSIsoft do Brasil Sistemas Ltda. Sao Paulo, Brazil
Sales Outlets/Distributors Middle East/North Africa South America/Caribbean Republic of South Africa Southeast Asia Russia/Central Asia South Korea Taiwan
www.osisoft.com
All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, Inc.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, PI Datalink, IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI ManualLogger, PI ProfileView, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, Inc. All other trademarks or trade names used herein are the property of their respective owners. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph I(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
iii OSI Software Inc. Table of Contents
Introduction...... 1 Principles of Operation...... 3 Plug-In Installation and Administration...... 5 Plug-In Directory...... 5 Installation Procedures...... 5 Define Required Digital States...... 5 Modify OPCInt.BAT...... 5 Configure PI Tags...... 6 Upgrading the Plug-In...... 6 Moving the Plug-In to a New Directory...... 6 Uninstalling the Plug-In...... 6 Command Line Parameters...... 7 Error and Informational Messages...... 9 Message Logs...... 9 Troubleshooting...... 9 System Errors and PI Errors...... 9 Appendix A: The Configuration File...... 11 Appendix B: DLL Debugging Options...... 13 dlldb=#...... 13 Debugging Messages...... 13 Revision History...... 15
Generic Plug-In DLL for OPC DA Interface to the PI System iii Introduction
The PI OPC DA 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, an OPC DA 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 DA Interface has been created by OSIsoft, Inc. For systems in which the status condition for a particular data item may be determined by a single input tag, the plug-in is called “OPCPlugInGeneric.DLL”. Note: Neither this manual nor the plug-in are stand-alone products; they are to be used in conjunction with the PI OPC DA Interface. This version of the plug-in requires 2.3.11 or above versions of the PI OPC DA Interface.
Generic Plug-In DLL for OPC DA Interface to the PI System 1 Principles of Operation
The PI OPC DA Interface connects OPC variables (which are defined by OPC symbols for the specific device) to a PI tag. Various configuration options are stored in the PI tag’s ‘ExDesc’ attribute, the Extended Descriptor. The Generic plug-in DLL requires an additional equate in the Extended Descriptor, indicating that PI tag belongs to a data- group, which is defined in a configuration file on the interface machine. For example, consider a fabrication line with many data inputs all flowing into PI. The fabrication line occasionally goes down for maintenance. It is desirable to have all data tags reflect MAINTENANCE status while the line is down. There is a DCS variable called SYS-STAT_01 available to OPC whose value is usually zero, but which becomes 77 during maintenance mode. To reflect this in Generic.INI, declare a group (as an ini-file section) called [FAB01]. Under this section, declare two equates; one for the error input condition, and another to indicate the PI status to use when this occurs. The ini-file equates would be: [FAB01] inputErrXX = 77 digStateXX = MAINTENANCE Any number of status condition/digital states may be defined for a status tag, as long as XX is unique for each pair. All ini-file symbols are case-INsensitive. Note that this example is one of two logical ways for a status tag to be used. The other is: A status tag may have one unique value which indicates good, anything else being an error. From the above example, a flag value of zero is good, whereas any other value indicates some problem. The special equate-pair: inputGood=0, and digStateBad=INVALID, may be added to the list above. In the extended descriptor of each data tag, the equate “… ,Grp=fab01, …” is added. The status tag which receives data from SYS-STAT_01 requires the equate “… GrpStat=fab01 …”, to identify it as the status tag for group FAB01. Every time data is read, the plug-in, OPCPlugInGeneric.DLL, examines the status tag associated with that data group. If a given status condition is in effect, the plug-in will set the values for the data with the system digital state associated with the error condition. If no status condition exists, the data is sent to PI with no modifications. Any data flowing into PI through OPC may belong to a data-group, and thus be modified by a status condition. If the tag does not belong to a data-group, then its status will never be affected. Status conditions which may invalidate a tag and the digital state value which that tag acquires in that error condition are defined in the configuration file as described in Appendix A: “The Configuration File”.
Generic Plug-In DLL for OPC DA Interface to the PI System 2 Plug-In Installation and Administration Plug-In Directory
The OPCPlugInGeneric.DLL is installed as part of the PI OPC DA Interface installation into the Plug-in subdirectory. For instance, if the interface is installed in D:\pipc\Interfaces\OPCInt then the DLL will be installed in D:\pipc\Interfaces\OPCInt\Plug-Ins Installation Procedures
Although the OPCPlugInGeneric.DLL is included with the PI OPC DA Interface installation, one must configure some things before the DLL will be activated. Define Required Digital States The PI administrator may define various error conditions, and the digital states which result from those conditions, in the initialization file (see Appendix A). The digital states thus defined must be present in the PI archive’s state table before the PI OPC DA Interface can run with the plug-in. The states are not case sensitive, but they must be spelled exactly as shown in the ini-file. The DLL expects these digital states to be somewhere in the System Digital State Set. Modify OPCInt.BAT OSIsoft recommends using the PI Interface Configuration Utility for making changes to the interface batch file. Under the opcint tab there is a Plug-Ins item that is used to configure the DLL which a instance of the OPCInt interface will use. This will add the /DLL= command line parameter to the batch file. For Example” /DLL=C:\PIPC\Interfaces\OPCInt\Plug-Ins\OPCPlugInGeneric.DLL
This plug-in requires a configuration file. Once this DLL is added to the PI ICU another text box will open and allow for the configuration file to be picked. Use the browse button on the left to search for the directory and name of the configuration file. This will add another command line parameter to the batch file. This also can be added to the batch file manually. /DLLConfig=c:\pipc\interfaces\opcint\plug-ins\Generic.INI
Once this has been added to the batch file either manually or by using the PI ICU the PI OPC DA Interface will automatically load the plug-in at startup. If the interface is already running, the interface must be restarted 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. If the path name contains spaces, the whole /DLL startup parameter has to be surrounded by double quotes. Example:
Generic Plug-In DLL for OPC DA Interface to the PI System 3 Plug-In Installation and Administration
/DLL=”C:\PIPC\Interfaces\OPCInt\Plug-Ins\OPCPlugInGeneric.DLL”
Configure PI Tags The plug-in needs to know which PI tags will be modified, and which tags will serve as status inputs. Note: all OPC symbols are case-sensitive. Upgrading the Plug-In
If the plug-in is upgraded independently of the PI OPC DA Interface, install the plug-in in the appropriate directory. Then stop and restart the PI OPC DA Interface according to the instructions in the PI OPC DA 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. Opcint.bat must be updated to reflect the name of the new directory, and the interface must be restarted as described in the PI OPC DA Interface manual. Uninstalling the Plug-In
To run the interface without the plug-in, run the PI ICU and remove the entry in the Post Processing DLL text box or delete the /DLL= command-line parameter from the batch file, and stop and restart the PI OPC DA Interface according to the instructions in the OPC DA Interface to the PI System manual.
4 Command Line Parameters
The DLL supports a few command-line parameters that are specific to this DLL. These parameters are different from interface specific parameters. When the DLL is loaded by the interface, the interface passes all command-line parameters. Some of the parameters that the interface uses are also used by the DLL. For example, /ID and /HOST. DLL specific parameters:
Parameter Description /DLLConfig=
Generic Plug-In DLL for OPC DA Interface to the PI System 5 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 /id flag 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 %windir% directory. For example, if the PIHOME entry 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 PI API Installation Instructions manual. Troubleshooting
Restarts: The OPC server must be operational before starting the PI OPC DA 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 Windows On Windows, descriptions of system and PI errors can be obtained with the pidiag utility: \PI\adm\pidiag –e error_number
Generic Plug-In DLL for OPC DA Interface to the PI System 6 Appendix A: The Configuration File
The plug-in requires a configuration file, which is supplied as a command-line parameter in the startup batch file for the PI OPC DA Interface; for example: /DLLConfig=c:\pipc\interfaces\opcint\plug-ins\Generic.ini This file defines how the interface recognizes data tags and the status tags which are applied to them. Here is an example Generic.ini file, for an interface taking OPC data from two machines, M1, and M4. Both machines have an associated status tag. Machine M1 has specific error conditions, and a single good status. Data from Machine M4 is assumed good as long as its status tag updates at least every five minutes. [M1] ; ; normal data group ; ; data tags will have .. ,Grp=m1, .. in the ex_desc ; the status tag will have .. , GrpStat=m1 , .. ; ; In this example, only the status value ; 3267 (decimal) yields a good status in PI. ; ; Status input 299 will result in all PI tags ; with ‘Grp=M1’ in their extended descriptors ; showing a status of “OFFLINE”. ; ; Status input 0xfe will result in all PI tags ; with ‘Grp=M1’ in their extended descriptors ; showing a status of “MAINTENANCE”. ; ; Any other status input will result in PI tags ; with ‘Grp=M1’ in their extended descriptors ; showing a status of “OTHER_PROBLEM”. ; inputErr_0 = 299 digState_0 = OFFLINE inputErr_32 = 0xfe
Generic Plug-In DLL for OPC DA Interface to the PI System 7 Appendix A: The Configuration File digState_32 = MAINTENANCE inputGood = 3267 digStateBad = OTHER_PROBLEM ; ; ;
The numeric values returned from a status tag may be given in decimal, hexadecimal, or octal bases. Octal is determined by a number beginning with zero, and containing only octal numerals (e.g. 0-7). Thus, “77” will convert to 7*10 + 7 = decimal 77, whereas “077” converts to 7*8+7 = decimal 63. Hexadecimal is determined either by any uniquely hexadecimal numerals (e.g. “A” through “F”), or any number beginning with “x”, or “0x”. For example, “x77” converts to 7*16+7 = decimal 119. Any strings may be used for PI digital states. Spaces will be preserved without the use of quotes. If a digital state named in this file is not found in the PI archive state table, then the interface will terminate with an error, and all missing states will be shown in PIPC.LOG. All equates must appear in matched pairs, associating an OPC input value with a particular PI digital state. If either equate statement of the matched pair is missing, then that error condition will not function. The matching pairs are: InputErr
8 Appendix B: DLL Debugging Options /dlldb=#
# is the number corresponding to the debug messages to print (see the table below). Debugging Messages
The debug flag is a value representing the type of message to print.. The message sets are:
/ Description dlldb =# 1 Logs Configuration messages 6 Logs Operation messages 8 Verbose messages
Generic Plug-In DLL for OPC DA Interface to the PI System 9 Revision History
Date Author Comments 12 Mar 01 WIsaacs Version 1.00 19 Feb 02 BYoung Version 1.0.2 9-Jul-02 CGoodell Version 1.03; formatting; headers & footers 1-Nov-05 Janelle Version 1.2.0.0 Rev A: fixed headers and footers, made final, fixed copyright. 24-Mar-06 Janelle Version 2.2.3.0 Rev A: fixed headers and footers, applied formatting template, removed first person references 28-Mar-06 MKelly Version 2.2.3.0 Rev B: fixed the installation section by adding PI ICU to the configuration of the DLL. 29-Jun-06 MKelly Version 2.3.2.0; version number changed to match interface version, DLL rebuilt with UniInt 4.2.3. 12-Dec-07 MGrace Appendix A got lost back in 2002, put back in 17-Dec-07 MGrace inputErrGood should be inputGood 1-Jun-2009 LCraven Updated version and copyright date 1-Jun-009 LCraven Removed heartbeat sections, since HB is inoperable. 4-Jun-2009 MKelly Version 2.3.11.0 Revision A, Updated the title and contact pages, fixed headers, footers and section breaks.
Generic Plug-In DLL for OPC DA Interface to the PI System 10