ValueToDigital Plug-In
for the PI Interface for OPC DA
Version 2.4.4.x
OSIsoft, LLC777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com
OSIsoft Australia • Perth, Australia
OSIsoft Europe GmbH • Frankfurt, Germany
OSIsoft Asia Pte Ltd. • Singapore
OSIsoft Canada ULC • Montreal & 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
ValueToDigital Plug-In for the PI Interface for OPC DA
Copyright: © 2013 OSIsoft, LLC. 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, PI Asset Framework(PI-AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, 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.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Published: 03/2013
Table of Contents
Chapter 1. Introduction 1
Chapter 2. Principles of Operation 3
Chapter 3. Installation Checklist 5
Chapter 4. Plug-In Installation and Administration 7
Plug-In Directory 7
Installation Procedures 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
Chapter 5. Command Line Parameters 11
Appendix A. Error and Informational Messages 13
Message Logs 13
Messages 13
System Errors and PI Errors 14
Appendix B. DLL Debugging Options 15
/dlldb=# 15
Debugging Messages 15
Appendix C. Technical Support and Resources 17
Before You Call or Write for Help 17
Help Desk and Telephone Support 17
Search Support 18
Email-based Technical Support 18
Online Technical Support 18
Remote Access 19
On-site Service 19
Knowledge Center 19
Upgrades 19
OSIsoft Virtual Campus (vCampus) 19
Appendix D. Revision History 21
ValueToDigital Plug-In for the PI Interface for OPC DA 19
Chapter 1. Introduction
The ValueToDigital Plug-In for the PI Interface for OPC DA is designed to allow specified values received from the OPC server to be replaced by system digital states. Each tag that is to be processed by the plug-in will have a configuration string in the ExDesc field, which will be processed from left to right; when a condition is satisfied, the corresponding system digital state will be sent to PI instead of the value. If no conditions are satisfied, the value will be sent to PI without any change.
· OPCInt Version 2.4.4.0 or greater is required.
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 OPC DA interface.
ValueToDigital Plug-In for the PI Interface for OPC DA 19
Chapter 2. Principles of Operation
The OPC ValueToDigital plug-in looks for a configuration string to be specified in the ExDesc of a tag. The configuration string will consist of one or more configuration sets, which are comprised of a condition and a system digital state number. The sets are evaluated left to right, with the first match resulting in the value from the OPC server being replaced by the specified system digital state. If no conditions are met, the value will be sent to the PI system in the normal fashion.
ValueToDigital Plug-In for the PI Interface for OPC DA 19
Chapter 3. 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 OPCPlugInValueToDigital.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 OPCPlugInValueToDigital.dll or modify OPCINT.BAT to activate the DLL.
- Configure PI tags.
- Start the interface.
ValueToDigital Plug-In for the PI Interface for OPC DA 19
Chapter 4. Plug-In Installation and Administration
Plug-In Directory
The OPCPlugInValueToDigital.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 OPCPlugInValueToDigital.DLL is on the CD with the 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\OPCPlugInValueToDigital.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\OPCPlugInValueToDigital.DLL"
Configure PI Tags
ExDesc
For each tag that is to be processed by the plug-in, configuration string must be specified in the ExDesc field. The string consists of the keyword DLLVALUE followed by one or more configuration sets. The configuration sets consist of a condition and a system digital state number. Each set is enclosed in parentheses, and the condition and number are separated by a comma. Note that spaces are not allowed, except the space following istrcmp or strcmp.
The options for the conditions fall into three categories. First is simply numeric comparison, where the available comparisons are Less Than (<), Less Than or Equal (<=), Equal (=), Greater Than or Equal (>=), and Greater Than (>). These operators may only be used with numeric tags (Int16, Int32, Int64, Float 32, and Float64).
String tags can be compared either case sensitive (strcmp), or case insensitive (istrcmp). These operators can only be used with string tags. A space follows the operator. Any characters, including spaces, are allowed within the string value.
The last category uses the keyword ZEROSPAN. This condition will be satisfied if the value received is less than the Zero for the tag, or greater than the Zero+Span for the tag. This keyword can only be used with numeric tags.
For example, if the configuration string is
/dllvalue(=35,214)
then if and only if the value is exactly 35, the plug-in will replace the value with the system digital state with index 214 (normally Sample Bad). Likewise, if the configuration string is
/dllvalue(ZEROSPAN,215)(=35,214)(>=1024,219)
then if the value received is less than the Zero for the tag, or greater than the Zero+Span, the plug-in will replace it with system state 215 (Equip Fail). Otherwise, if the value is exactly 35, state 214 will be written to the tag. If neither of those conditions is true, and the value is greater than or equal to 1024, state 219 will be sent (Bad Lab Data). If none of those conditions are met, then the value is sent to PI normally.
For numeric tags, the legal operators for the conditions are
<=
=
>=
ZEROSPAN
For string tags, the legal operators are
strcmp
istrcmp
For example, a string compare might be
/dllvalue(strcmp Cookie,215)(istrcmp Cup Cake,214)
For the above configuration set, a value of "Cookie" will be replaced by state 215, a value of "cup cake"will be replaced by state 214, and any other string will be processed normally by the interface.
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 OPC DA interface according to the instructions in the PI Interface for OPC DA manual.
ValueToDigital Plug-In for the PI Interface for OPC DA 19
Chapter 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.
DLL specific parameters:
Parameter / Description //DLLDB=#
(Default: 0)
Optional / Debug level (0-32767). See DLL Debugging Options section for more details.
ValueToDigital Plug-In for the PI Interface for OPC DA 19
Appendix A. Error and Informational Messages
A string NameID is pre-pended to error messages written to the message log. 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 parameter 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
ValueToDigital: Version #.#.#
The version of the plug-in
ValueToDigital: DebugFlag #
The /DLLDB value on the command line is greater than 0.
ValueToDigital: tag %s has ZEROSPAN twice
The specified tag has more than one configuration set that uses ZEROSPAN. Only the first will be used.
ValueToDigital: out of memory
The plug-in was unable to allocate memory to store tag configuration sets. This indicates a serious problem with the system.
ValueToDigital: tag %s has an invalid configuration string, will not be processed
The plug-in was unable to parse the configuration string for the tag. The tag will not be processed by the plug-in.
ValueToDigital: tag %s has a string compare, but is not a string tag, will not be processed
The plug-in found a numeric tag with a string compare. The tag will not be processed by the plug-in.
ValueToDigital: tag %s has a numeric compare, but is a string tag, will not be processed
The plug-in found a string tag with a numeric compare. The tag will not be processed by the plug-in.
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
ValueToDigital Plug-In for the PI Interface for OPC DA 19
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 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 configuration of tags that the dll should process, and tag edits on those tags.
16 / Logs how many values were received in the current packet.
32 / Logs processing for all values received. Note that this includes tags that are not processed by the plug-in.
ValueToDigital Plug-In for the PI Interface for OPC DA 19
Appendix C. Technical Support and Resources
You can read complete information about technical support options, and access all of the following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com (http://techsupport.osisoft.com)
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:
· Product name, version, and/or build numbers
· Computer platform (CPU type, operating system, and version number)
· The time that the difficulty started