CircularBuffer Plug-In
for the PI Interface for OPC DA
Version 2.4.4.x
Copyright © 2009-2013, OSIsoft, LLC
OSIsoft, LLC777 Davis St., Suite 250
San Leandro, CA 94577 USA
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
http://techsupport.osisoft.com
Houston, TX
Johnson City, TN
Longview, TX
Mayfield Heights, OH
Philadelphia, PA
Phoenix, AZ
Savannah, GA
Yardley, PA
/ OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSIsoft Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
Calgary, Canada
OSIsoft, LLC Representative Office
Shanghai, People’s Republic of China
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
Republic of South Africa
Russia/Central Asia / South America/Caribbean
Southeast 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, LLC.
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, LLC. 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
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
11
Introduction
The CircularBuffer Plug-In for the PI Interface for OPC DA is designed to allow the use of one OPC array Item as the source of the values stored in PI, and another OPC array Item as the source of the timestamps used to store those values, with a third OPC Item used as the index into those arrays. After the first index value is read, any change to the index value will result in the array elements from the value and timestamp arrays being paired together and sent to PI, for all array elements from OldIndexValue+1 to NewIndexValue.
· PI Interface for OPC DA Version 2.4.4.0 or greater is required.
· The OPCPlugInCircularBuffer.dll will work only with v2.0 OPC servers. Version 1.0a of the OPC DA interface is not supported by this plug-in.
Note: Neither this manual nor the plug-in are stand-alone products; they are to be used in conjunction with the PI Interface for OPC DA. This version of the plug-in requires 2.4.4.0 or above versions of the PI Interface for OPC DA.
11
Principles of Operation
The CircularBuffer plug-in looks for a timestamp ItemID to be specified in the ExDesc of a tag, and also an Index PI tag. If the timestamp ItemID is found, the plug-in will add the timestamp ItemID to the scan class so that it will receive data when the value tag receives data. Then whenever the value in the index tag changes, the plug-in will pair up the elements from the timestamp array and the elements from the value array, and send these to PI as timestamp-value pairs. The elements that will be sent are all the elements from the old index value plus one to the new index value, with the index value wrapping back over to zero when it reaches the array size specified for that index tag. If there is an error acquiring the timestamp array, or if the quality of the timestamp array is not Good, no values will be sent to PI, as we cannot store time series data without timestamps. Likewise, if there is an error acquiring the index tag value, or if the quality of the value is not Good, no values will be sent to PI, nor will the old index value be changed.
11
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps get the OPC DA interface up and running with the OPCPlugInCircularBuffer.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.
- Install the PI ICU which will install the PI SDK and PI API
- Install the PI Interface for OPC DA.
- Define digital states
- Use the PI ICU to configure the OPC DA interface and use the Plug-Ins configuration to add the support for the OPCPlugInCircularBuffer.dll or modify OPCINT.BAT to activate the DLL.
- Configure PI tags.
- Start the interface.
11
Plug-In Installation and Administration
Plug-In Directory
The OPCPlugInCircularBuffer.DLL is installed as part of the OPC DA interface installation into the Plug-Ins 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 OPCPlugInCircularBuffer.DLL is on the CD with the PI Interface for OPC DA, 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 OPC DA interface will use. This will add the /DLL= command line parameter to the batch file.
For Example:
/DLL=C:\PIPC\Interfaces\OPCInt\Plug-Ins\OPCPlugInCircularBuffer.DLL
Once this has been added to the batch file either manually or by using the PI ICU the 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\OPCPlugInCircularBuffer.DLL”
Configure PI Tags
ExDesc
For each value tag, the OPC ItemID of the corresponding timestamp array must be specified in the ExDesc field. The keyword used depends on the datatype of the timestamp Item; the datatypes which the plug-in can read are VT_DATE, VT_BSTR, and VT_I4.
For timestamps read as strings, the keyword is TIM:.
TIM=/AC405/FRAME1/Whiteness/Timestamp042
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 PI Interface for OPC DA 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 VT_DATE, the keyword is DAT:
DAT=/AC405/FRAME1/Whiteness/Timestamp047
For timestamps read as VT_I4, the keyword is VTIM:
VTIM=/AC405/FRAME1/Whiteness/Timestamp042
Timestamps read as VT_I4 are expected to be UTC1970 time, which is the number of seconds since 1 Jan, 1970.
The PI tag which will read the value of the index into the arrays must also be specified in the ExDesc of the value tag. The keyword for this is DLLIndex:
DLLINDEX=MyIndexTag
Note that the Index tag must be configured as a normal input tag in the same scan class as the value tag, and it must be an integer tag. Also, the index tag itself must specify the size of the arrays which it indexes, again using the keyword DLLIndex.
DLLINDEX=200
Upgrading the Plug-In
If the plug-in is upgraded independent of the OPC DA interface, install the plug-in in the appropriate directory. Then stop and restart the OPC DA interface according to the instructions in the PI Interface for OPC DA 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 Interface for OPC DA 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 PI Interface for OPC DA manual.
11
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 //DLLDB=#
(Default: 0)
Optional / Debug level (0-32767). See DLL Debugging Options section for more details.
/DLLDebugTag=<tagname / Debug Level setting with a <tagname> value. This parameter allows the user to turn on or off debugging and set the level of debugging at runtime by changing the value of the <tagname>. See the DLL Debugging Options section for more details.
11
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 %windir% 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 PI APIInstallationInstructions manual.
Note: No messages are written to the command window when the interface is run interactively. All messages are written to pipc.log.
Messages
CircularBuffer: Version #.#.#
The version of the plug-in
CircularBuffer: Debug tag <tagname> found
If a debug tag is defined, that is confirmed.
CircularBuffer: Unable to find debug tag <tagname>, no debug tag set
No debug tag was found.
CircularBuffer: DebugFlag #
The debug tag value is greater than 0 or the /DLLDB value on the command line is greater than 0.
CircularBuffer: Time format too long:
The format for the string timestamps, specified on the command line, exceeds 80 characters. This generally indicates an error in the .bat file.
CircularBuffer: Error getting debug tag value
When using a debug flag tag, the debug settings are changed by setting the value in the tag, then editing the tag so that the interface and dll will be informed that the tag has changed. If the dll cannot then read the value in the snapshot for that tag, it will write this error message and leave the current debug setting as is.
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
11
Appendix A:DLL Debugging Options
The CircularBuffer 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
CircularBuffer: 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.
/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:
/dlldb=# / Description2 / Logs the recognition and matching of tags that the dll should process. Logs the timestamp format, if specified.
4 / Logs initial value for indexes, or lack of index value found for value tag.
8 / Logs bad quality for index tag, timestamp Item. Logs a message for each value sent to PI.
16 / Verbose logs for index values, number of values received.
32 / Logs values received, values skipped.
11