ValueToDigital Plug-In for OPC DA Interface
Version 2.3.14.0
Revision A
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web:
OSIsoft Australia • Perth, Australia
OSIsoft Europe GmbH • Frankfurt, Germany
OSIsoft Asia Pte Ltd. • Singapore
OSIsoft Canada ULC • MontrealCalgary, 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 OPC DA Interface
Copyright: © 2011 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: 12/2011
Table of Contents
Chapter 1.Introduction
Chapter 2.Principles of Operation
Chapter 3.Installation Checklist
Chapter 4.Plug-In Installation and Administration
Plug-In Directory
Installation Procedures
Modify OPCInt.BAT
Configure PI Tags
Upgrading the Plug-In
Moving the Plug-In to a New Directory
Uninstalling the Plug-In
Chapter 5.Command Line Parameters
Appendix A.Error and Informational Messages
Message Logs
Messages
System Errors and PI Errors
Appendix B.DLL Debugging Options
/dlldb=#
Debugging Messages
Appendix C.Technical Support and Resources
Before You Call or Write for Help
Help Desk and Telephone Support
Search Support
Email-based Technical Support
Online Technical Support
Remote Access
On-site Service
Knowledge Center
Upgrades
OSIsoft Virtual Campus (vCampus)
Appendix D.Revision History
ValueToDigital Plug-In for OPC DA Interface1
Chapter 1.Introduction
The OPC ValueToDigital Plug-In for the PI OPC DA Interface 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.3.14 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 OPC DA Interface. This version of the plug-in requires 2.3.14 or above versions of the PI OPC DA Interface.
ValueToDigital Plug-In for OPC DA Interface1
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 OPC DA Interface1
Chapter 3.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 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 PI OPC DA Interface.
- 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 OPC DA Interface1
Chapter 4.Plug-In Installation and Administration
Plug-In Directory
The OPCPlugInValueToDigital.DLL is installed as part of the PI 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 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\OPCPlugInValueToDigital.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\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 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.
ValueToDigital Plug-In for OPC DA Interface1
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 OPC DA Interface1
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.logfile will be located in the c:\PIPC\dat directory.
For version 1.3 and greater of the PI API, a process called pilogsrvmay 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 OPC DA Interface1
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 OPC DA Interface1
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:
(
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
- The log file(s) at that time
Help Desk and Telephone Support
You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table below to find the most appropriate number for your area. Dialing any of these numbers will route your call into our global support queue to be answered by engineers stationed around the world.
Office Location / Access Number / Local Language OptionsSan Leandro, CA, USA / 1 510 297 5828 / English
Philadelphia, PA, USA / 1 215 606 0705 / English
Johnson City, TN, USA / 1 423 610 3800 / English
Montreal, QC, Canada / 1 514 493 0663 / English, French
Sao Paulo, Brazil / 55 11 3053 5040 / English, Portuguese
Frankfurt, Germany / 49 6047 989 333 / English, German
Manama, Bahrain / 973 1758 4429 / English, Arabic
Singapore / 65 6391 1811
86 021 2327 8686 / English, Mandarin
Mandarin
Perth, WA, Australia / 61 8 9282 9220 / English
Support may be provided in languages other than English in certain centers (listed above) based on availability of attendants. If you select a local language option, we will make best efforts to connect you with an available Technical Support Engineer (TSE) with that language skill. If no local language TSE is available to assist you, you will be routed to the first available attendant.
If all available TSEs are busy assisting other customers when you call, you will be prompted to remain on the line to wait for the next available TSE or else leave a voicemail message. If you choose to leave a message, you will not lose your place in the queue. Your voicemail will be treated as a regular phone call and will be directed to the first TSE who becomes available.
If you are calling about an ongoing case, be sure to reference your case number when you call so we can connect you to the engineer currently assigned to your case. If that engineer is not available, another engineer will attempt to assist you.
Search Support
From the OSIsoft Technical Support Web site, click Search Support.
Quickly and easily search the OSIsoft Technical Support Web site’s Support Solutions, Documentation, and Support Bulletins using the advanced MS SharePoint search engine.
Email-based Technical Support
When contacting OSIsoft Technical Support by email, it is helpful to send the following information:
- Description of issue: Short description of issue, symptoms, informational or error messages, history of issue
- Log files: See the product documentation for information on obtaining logs pertinent to the situation.
Online Technical Support
From the OSIsoft Technical Support Web site, click Contact us > My Support > My Calls.
Using OSIsoft’s Online Technical Support, you can:
- Enter a new call directly into OSIsoft’s database (monitored 24 hours a day)
- View or edit existing OSIsoft calls that you entered
- View any of the calls entered by your organization or site, if enabled
- See your licensed software and dates of your Service Reliance Program agreements
Remote Access
From the OSIsoft Technical Support Web site, click Contact Us > Remote Support Options.
OSIsoft Support Engineers may remotely access your server in order to provide hands-on troubleshooting and assistance. See the Remote Access page for details on the various methods you can use.
On-site Service
From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service Visit.
OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more information.
Knowledge Center
From the OSIsoft Technical Support Web site, click Knowledge Center.
The Knowledge Center provides a searchable library of documentation and technical data, as well as a special collection of resources for system managers. For these options, click Knowledge Center on the Technical Support Web site.
- The Search feature allows you to search Support Solutions, Bulletins, Support Pages, Known Issues, Enhancements, and Documentation (including user manuals, release notes, and white papers).
- System Manager Resources include tools and instructions that help you manage: Archive sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server security, PI System sizing and configuration, PI trusts for Interface Nodes, and more.
Upgrades
From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.