<p> Bitmasking Plug-In DLL for OPC DA Interface to the PI System</p><p>Version 2.3.11.0 Revision A</p><p>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) (01) 510-357-8136 (fax) OSI Software GmbH (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 Philadelphia, PA Calgary, Canada Phoenix, AZ Savannah, GA OSIsoft, Inc. Representative Office Yardley, PA 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 </p><p>Sales Outlets/Distributors Middle East/North Africa South America/Caribbean Republic of South Africa Southeast Asia Russia/Central Asia South Korea Taiwan </p><p> www.osisoft.com</p><p>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. </p><p>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.</p><p>RESTRICTED RIGHTS LEGEND</p><p>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</p><p> iii OSI Software Inc. Table of Contents</p><p>Introduction...... 1</p><p>Principles of Operation...... 3 Limits...... 3</p><p>Installation Checklist...... 5</p><p>Plug-In Installation and Administration...... 7 Plug-In Directory...... 7 Modify OPCINT.BAT...... 7 Configure PI Tags...... 7 Format - BITMASK...... 7 Format – Priorty Bits...... 8 Upgrading the Plug-In...... 10 Moving the Plug-In to a New Directory...... 10 Uninstalling the Plug-In...... 11</p><p>Command Line Parameters...... 13</p><p>Error and Informational Messages...... 15 Message Logs...... 15 Troubleshooting...... 16 System Errors and PI Errors...... 16</p><p>Revision History...... 17</p><p>Bitmasking Plug-in DLL for OPC DA Interface to the PI System iii Introduction</p><p>The PI OPC DA Interface is generic in that it does not interpret words that it retrieves from an OPC server. Sometimes the words are packed with multiple values such that each bit or group of bits are a distinct value. A plug-in DLL for the PI OPC DA Interface was written by OSIsoft in order to get complete information from the bits (through PI OPC). The OPCPlugInBitMask.DLL allows for selecting specific bits out of a data word received from an OPC server and stores that value in a PI tag. Version 2.1 or greater of the PI OPC DA Interface is required.</p><p>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 of the PI OPC DA Interface.</p><p>Bitmasking Plug-in DLL for OPC DA Interface to the PI System 1 Principles of Operation</p><p>The PI OPC DA Interface connects OPC variables (which are defined by OPC symbols for the specific device) to a PI tag. The OPC symbol for any PI tag is saved in that tag’s ‘InstrumentTag’ attribute or ‘ExDesc’ (Extended Descriptor) (See the OPC DA Interface to the PI System manual for exact tag configuration details.) To use the bit-masking capability, the PI tag must indicate the bit mask in the Extended Descriptor. Limits</p><p> PI OPC DA Interface Version 2.1 or greater is required.</p><p> The result may be stored in a Digital or Integer PI tag.</p><p> A Digital Tag must use a Digital State Set with a sufficient number of states. 2n Digital States are required, with n being the number of set bits in the bit mask.</p><p> Write direction is not supported. For an output tag (PI  OPC server) the bit mask is ignored. The PI Value is sent directly to the OPC tag specified.</p><p> OPC Data of type VT_I4 is also supported. If sent to a Digital tag, Location2=3 is required. (See OPC DA Interface to the PI System manual) </p><p> Bits from different data words can not be combined on the OPC server. Data arrays are not supported.</p><p>Bitmasking Plug-in DLL for OPC DA Interface to the PI System 2 Installation Checklist</p><p>For those users who are familiar with running the PI OPC DA Interface with the Bitmasking Plug-in DLL, this checklist helps get the Bitmasking Plug-in DLL up and running. If not familiar with the Bitmasking Plug-in DLL for the PI OPC DA Interface, 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 OPC DA Interface. 2. Use the PI ICU to configure the OPC DA Interface and use the Plug-Ins configuration to add the support for the OPCPlugInBitmask.dll or modify OPCINT.BAT to activate the DLL. 3. Configure PI tags. 4. Start the interface.</p><p>Bitmasking Plug-in DLL for OPC DA Interface to the PI System 3 Plug-In Installation and Administration</p><p>Plug-In Directory</p><p>The OPCPlugInBitmask.DLL is on the CD with the PI OPC DA Interface. It will be installed by the OPC DA Interface and placed in the directory PIHOME\Interfaces\OPCInt\Plug-Ins Modify OPCINT.BAT</p><p>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\OPCPlugInBitMask.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, and manifest bit masking. If the interface is already running, the interface must be restarted for the DLL to be activated.</p><p>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\OPCPlugInBitMask.DLL” Configure PI Tags </p><p>The OPCPlugInBitMask.DLL uses the keyword Bitmask, PRI_BIT or PRI_BITZ in the ExDesc point attribute to determine the masking. Bits cannot be combined from different data words on the OPC server. Data arrays are not supported.</p><p>Format - BITMASK Bitmask=n n may be a decimal, hexadecimal (0xnnnn) or binary (0bnnnnnnnnnnnnnnnn) number. If combined with other keywords in exdesc (see OPC DA Interface to the PI System manual), they have to be separated by commas. Keywords may appear in any order. Example: Event=pi-event.tag , Instr=OPCTag.xyz.name, Bitmask=0x0040 Keyword and number are case insensitive. </p><p>Example: BITMASK= 0Xaaaa Leading zeros may be omitted. Spaces are allowed (but no space within numbers).</p><p>Bitmasking Plug-in DLL for OPC DA Interface to the PI System 4 Decimal Bit Mask A decimal number is assumed (1, 2, 4, 8, ... etc to indicate single bits.) Example: Bitmask = 3 (mask the last two bits) OPC Value (VT_I2) = 68 (= 64 + 4) Result = 0 </p><p>Hexadecimal Bit Mask If bitmask= is followed by 0x, the rest is interpreted as a hexadecimal number. Example: Bitmask = 0x16 OPC Value (VT_I2) = 68 = 0x44 Result 0x02 = 2 Binary Bit Mask If bitmask= is followed by 0b, the rest is interpreted as a bit pattern. The only valid characters are 0 or 1. Example: Bitmask = 0b0100000000000111 OPC Value (VT_I2) = 17476 = 0b0100010001000100 Result 0b 1 100 = 0x0C = 12 Several bits in Bitmask may be set. They will be pushed together.</p><p>Format – Priorty Bits Pri_bit=n or Pri_bitz=n</p><p>1. List up to 32 bits of the data quality, formatting all bit positions to two places and using 0-based notation (e.g., 00, 01, 03…32). 2. Prioritize the bit positions. The priority will indicate the order in which the plug-in examines the bit states. The order listed must match the ordering of the associated PI digital state set.</p><p>Bitmasking Plug-in DLL for OPC DA Interface to the PI System 5 Plug-In Installation and Administration</p><p>The following is an explicit example. Assume the meanings of the bit positions of the data are as follows, where bit numbering uses traditional zero-based indexing:</p><p>Bit Position (0-based) Meaning, if set 0 Uninitialized 1 Stale 2 Bad 3 Reserved 4 Unreasonable 5 Commanded 6 Remote suspect 7 Remote replaced 8 Manual replaced 9 Reserved 10 Not in service 11 Tfail 12 Genrep 13 Testmode 14 Delayed 15 Unacknowledged 16 Abnormal 17 Inhibit 18 Notag 19 Reserved 20 Reserved 21 Reserved 22 Reserved 23 Reserved 24 Reserved 25 Reserved 26 Scan pending 27 Garbage 28 Suspect 29 Replaced 30 Good</p><p>6 Assume a PI digital state set named PRIORITY_BITS that is configured to capture some of the bits. The order of the state strings could be as follows:</p><p>Offset from Start of State String Corresponding Data Set source Bit 0 Good 30 1 Old 1 2 Bad 2 3 Unreasonable 4 4 RemSusp 6 5 RemRepl 7 6 ManRepl 8 7 Delayed 14 8 Abnormal 16 9 Suspect 28 10 Replaced 29 11 Garbage 27 The order of the strings in the digital set is significant, since this must correspond to the priority in which the user wishes the data quality to be examined. The first bit that is set will be used as the value. In this example, bit 30 representing the Good bit must be examined first, then bit 1, etc. If bit 30 is set, then the value 0 is saved to PI and the data quality value is examined no further. The value 0 is correlated with the state string “Good.”</p><p>Note: If a “Good” bit exists, it makes sense that it would be given the highest priority since this will usually decrease time spent examining data quality bits. If bit 30 is not set, then if bit 1 is set, the value 1 is saved to PI, which corresponds to state string “Old.” The algorithm proceeds in similar fashion through all bits. If none of the specified bits is set then: If pri_bit is used, then BAD INPUT will be saved to the PI tag. If pri_bitz is used then the 0 state will be saved to the PI tag. The configuration of PRI_BIT for this example would be as follows: PRI_BIT=30010204060708141628 The formatting of the bit positions is 0-based and two digits per bit. The bits are ordered from most significant to least significant. Configuration of PRI_BIT is actually a bit more complex than shown above. The meanings of the bit states may be specific to a particular site. In many cases, when one bit state is set, other related bit states are set simultaneously. For example, a BAD bit may be set if any of ABNORMAL, DELAYED, OLD, SUSPECT, or GARBAGE is set. Therefore, it would make little sense to place the BAD bit at a higher priority than the other more specific qualities. Thus, the value that is saved to the PI tag is dependent upon the user’s judgment of priorities.</p><p>Bitmasking Plug-in DLL for OPC DA Interface to the PI System 7 Plug-In Installation and Administration</p><p>Upgrading the Plug-In</p><p>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 OPC DA Interface to the PI System manual. Moving the Plug-In to a New Directory</p><p>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 OPC DA Interface to the PI System manual. Uninstalling the Plug-In</p><p>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. A point configuration ExDesc parameter bitbask=0xnnn is ignored without the /DLL command-line parameter. Alternatively, points without bitmask= in ExDesc are handled the standard way, so the /DLL= command-line parameter might not need to be removed.</p><p>8 Command Line Parameters</p><p>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:</p><p>Parameter Description /DLLDB=# Debug level (0-32767). See the Troubleshooting section for (Default: 0) more details. Optional</p><p>Bitmasking Plug-in DLL for OPC DA Interface to the PI System 9 Error and Informational Messages</p><p>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</p><p>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. If run interactively, messages are written to the screen in parallel (without timestamp line). All messages coming from the OPCPlugInBitMask.DLL start with the identifier BITMASK. In normal operations, only the version of the OPCPlugInBitMask.DLL is logged on startup.</p><p>Possible Errors  Wrong bit mask: If the mask cannot be converted to a numeric value, the bit mask is ignored No error is logged.  Wrong OPC data type results in BITMASK on Tag tagname not supported (VT_I2 / VT_I4 / VT_UI2 expected) Bit mask is ignored. Errors are repeated after a point edit. Other errors should be handled by the PI OPC DA Interface itself.</p><p>Bitmasking Plug-in DLL for OPC DA Interface to the PI System 10 Troubleshooting</p><p>The /DLLDB startup parameter is also used by OPCPlugInBitMask.DLL. Debug output is written to PIPC.LOG. If the interface is run as a console application, output is sent to the application window, too. Online switching of the debug level (/DF parameter) is NOT supported.  /DLLDB=1 or greater documents relevant startup information (Actually, here this is just the /DB level itself)  /DLLDB=32 or greater prints out every conversion performed. This is only recommended for few tags over a short period of time. System Errors and PI Errors</p><p>System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers. </p><p>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</p><p>Bitmasking Plug-in DLL for OPC DA Interface to the PI System 11 Revision History</p><p>Date Editor Comments 05-Apr-01 CGoodell Formatting 05-apr-01 Janelle Beautification 09-Apr-01 MHesselbach Version 1.0.1: Added specific information 17-Apr-01 CGoodell / Formatting Janell 18-Apr-01 MHesselbach Added example for decimal format, Message logs 19-Apr-01 CGoodell Formatting 1-Nov-05 Janelle Rev A: fixed copyright; made final. 22-Mar-06 PSluder Added support for VT_UI2 tag datatype. 24-Mar-06 Janelle Version 2.2.3.0 Rev C: updated template, fixed headers and footers, removed first person references, changed “NT” to “Windows”, updated How to Contact us page 28-Mar-06 MKelly Version 2.2.3.0 Rev D: updated the section on how to use the DLL using the PI ICU program to configure it. 29-Jun-06 MKelly Version 2.3.2.0; version number changed to match interface version, DLL rebuilt with UniInt 4.2.3. 23-Feb-07 Janelle Version 2.3.2.0, Revision A: turned off tracking, accepted all changes, made final 29-Mar-07 MGrace Add documentation for the pri_bit and pri_bitz (priority bits) 03-Feb-09 EKuwana Edit the error message (due to wrong OPC data type) in Error and Informational Messages section, by adding VT_UI2 in the error message 1-Jun-2009 LCraven Updated to use dlldb, updated version.</p><p>Bitmasking Plug-in DLL for OPC DA Interface to the PI System 12</p>