Timestamp Plug-In for OPC DA Interface to the PI System
Total Page：16
File Type：pdf, Size：1020Kb
Timestamp Plug-In for OPC DA Interface to the PI System
Version 2.3.11.0 Revision A
Copyright © 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
iv 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 Modify OPCInt.BAT...... 7 Configure PI Tags...... 7 Upgrading the Plug-In...... 8 Moving the Plug-In to a New Directory...... 8 Uninstalling the Plug-In...... 8 Command Line Parameters...... 9 Error and Informational Messages...... 11 Message Logs...... 11 Messages...... 11 System Errors and PI Errors...... 12 Appendix A: DLL Debugging Options...... 13 DLLDebugTag=tagname...... 13 DLLDB=#...... 14 Debugging Messages...... 14 Revision History...... 15
Timestamp Plug-In for OPC DA Interface to the PI System iii Introduction
The OPC Timestamp Plug-In for the PI OPC DA Interface is designed to allow the use of one OPC Item as the source of the value stored in PI, and another OPC Item as the source of the timestamp used to store that value. Optionally, an output tag may also be configured to send a response back to the OPC server once the value and timestamp have been sent to PI. OPCInt Version 2.3.11 or greater is required. The OPCPluginTimestamp dll will work with both v1.0a and v2.0 OPC servers. 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.
Timestamp Plug-In for OPC DA Interface to the PI System 1 Principles of Operation
The OPCPluginTimestamp.dll looks for a timestamp ItemID to be specified in the ExDesc of a tag, and possibly also an Acknowledgement (ACK) PI tag. If a timestamp ItemID is found, the dll will add that Item to the same scan class as the value tag that it will be used with, and when a value is received it will use the value in the timestamp Item (either a timestamp string or a VT_DATE) as the timestamp for the value in the value Item, and send that pair to PI. If an ACK tag is specified for that value tag, it will then write the specified value to the ACK OPC Item. If the quality of the timestamp is not good, an error will be written to the logfile but no value sent to PI, as without a timestamp we cannot store a value to a time series archive. If an ACK is specified, the ACK will be sent even if the timestamp is not usable. If the quality of the value tag is not good, the appropriate digital state will be sent to PI, with the timestamp from the timestamp Item. All normal processing will be done to the value tag, as all the plug-in does is replace the timestamp on the value with the value from the timestamp Item, and optionally send an ACK value back to the OPC server.
Timestamp Plug-In for OPC DA Interface to the PI System 2 Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps get the PI OPC DA Interface up and running with the OPCPluginTimestamp.DLL. If not familiar with the plug-in, return to this section after reading the rest of this manual in detail. Follow the steps in the order listed below. 1. Install the PI ICU which will install the PI SDK and PI API 2. Install PI OPC DA Interface. 3. Define digital states 4. Use the PI ICU to configure the OPC DA Interface and use the Plug-Ins configuration to add the support for the OPCPluginTimestamp.dll or modify OPCInt.bat to activate the DLL. 5. Configure PI tags. 6. Start the interface.
Timestamp Plug-In for OPC DA Interface to the PI System 3 Plug-In Installation and Administration Plug-In Directory
The OPCPluginTimestamp.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 OPCPluginTimestamp.DLL is on the CD with the PI OPC DA Interface, one must configure some things before the DLL will be activated. 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 an 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\OPCPluginTimestamp.DLL
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: /DLL=”C:\PIPC\Interfaces\OPCInt\Plug-Ins\OPCPluginTimestamp.DLL” Configure PI Tags ExDesc For each value tag that requires the timestamp to be taken from another OPC Item, the OPC ItemID of that item must be specified in the ExDesc field. The keyword used depends on the datatype of the timestamp Item. If the timestamp is a string value, the format of the timestamp string must be specified in the startup parameters to the interface, using the /TF parameter. This parameter is documented in the OPC DA Interface User Manual. The same format must be used for all timestamp strings to be read or written by this instance of the interface. For timestamps read as strings, the keyword is TIM=ItemId. TIM=/AC405/FRAME1/Whiteness/Timestamp042
Timestamp Plug-In for OPC DA Interface to the PI System 4 For timestamps read as VT_DATE, the keyword is DAT=ItemId. DAT=/AC405/FRAME1/Whiteness/Timestamp047 If an Acknowledgement value should be sent to the OPC server when the value is read and sent to PI, the output tag which is configured for that ItemID should also be specified using the keyword DLL_ACK. DLL_ACK=MyAckTag Note that the ACK tag must be configured as a normal output tag belonging to this instance of the interface. Additionally, in the ExDesc of the ACK tag, the value to be sent to the OPC server must be specified, also the keyword DLL_ACK. DLL_ACK=7 Upgrading the Plug-In
If the plug-in is upgraded independent 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, then stop and restart the PI OPC DA Interface according to the instructions in the OPC DA Interface to the PI System manual.
5 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. For information about these parameters, see the PI OPC DA Interface Manual. DLL specific parameters:
Parameter Description /DLLDB=# Debug level (2-58). See Appendix A: DLL Debugging Options (Default: 0) section for more details. Optional /DLLDebugTag=
Timestamp Plug-In for OPC DA Interface to the PI System 6 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. Note: No messages are written to the command window when the interface is run interactively. All messages are written to pipc.log. Messages Timestamp: Version #.#.# The version of the plug-in Timestamp: Debug tag
Timestamp Plug-In for OPC DA Interface to the PI System 7 Error and Informational Messages
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
8 Appendix A: DLL Debugging Options
The Timestamp DLL has the capability to use a debug tag, and to have the value of the debug flag set on the command line. To set the value of the debug flag on the command line, use /DLLDebugTag=tagname
The preferred way to set the debug flag is to define an Int32 tag in PI, configure it as a simple input tag with Location2 = 1024 (so the DLL will recognize it), and put any dummy value into the InstrumentTag. Make sure that the Location1 attribute of the tag has the correct value for this interface. Then give the tagname in the command line. Before starting the interface, set the value of the debug tag. Then to turn debugging on or off, or to change the level of debugging, change the value of the tag, and then edit the tag. When the DLL gets the tag as an edit or a new tag, it reads the value from the PI snapshot, but does not include the tag in the list of tags for the OPC server to service. In the pipc.log file, the following messages are displayed to indicate that the debug tag has been found and read: 01-Nov-01 11:58:37 Timestamp: Debug tag TIMESTAMPDEBUG found
01-Nov-01 11:58:41 OPCpi> 2> Removed Tag TIMESTAMPDEBUG
01-Nov-01 11:58:41 OPCpi> 2> Developer load structure failure, TIMESTAMPDEBUG , 1177 Every time the debug tag is edited (which will happen every time the debug value is changed), those last two messages will appear in the pipc.log file.
Timestamp Plug-In for OPC DA Interface to the PI System 9 Appendix A: 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 bit mask, so more than one set of messages can be turned on by adding the set numbers together and setting the debug flag to that value. So, to turn on messages for the array timestamps and for values that we would process but none passed the exception parameters, set debugging to 2 + 8 = 10 . The message sets are:
/ Description dlldb =# 2 Logs the recognition of input and output tags that the dll should process. Logs the timestamp format, if specified. 8 Logs minimal messages for data received and processed. 16 Verbose messages for data received and processed. 32 Logs individual tags processed, ACKs processed.
10 Revision History
Date Author Comment 1-Jun-2009 LCraven Initial version. 4-Jun-2009 MKelly Version 2.3.11.0 Revision A, Updated the title and contact pages, fixed headers, footers and section breaks. Updated TOC.
Timestamp Plug-In for OPC DA Interface to the PI System 11