Bitmasking Plug-In DLL
for OPC
Interface to the PI System
Version 2.3.6.0
Revision A
i
UniInt End-User Interface to the PI System
How to Contact Us
OSIsoft, Inc.777 Davis St., Suite 250
San Leandro, CA 94577 USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. 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
Sales Outlets and Distributors
§ Brazil
§ Middle East/North Africa
§ Republic of South Africa
§ Russia/Central Asia / § South America/Caribbean
§ Southeast Asia
§ South Korea
§ Taiwan
WWW.OSISOFT.COM
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s products or any affiliation with such party of any kind.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Unpublished – rights reserved under the copyright laws of the United States.
© 2001-2006 OSIsoft, Inc. PI_OPCPluginBitmask.doc
i
UniInt End-User Interface to the PI System
Table of Contents
Introduction 1
Principles of Operation 3
Limits 3
Installation Checklist 5
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 11
Moving the Plug-In to a New Directory 11
Uninstalling the Plug-In 11
Error and Informational Messages 13
Message Logs 13
Troubleshooting 14
System Errors and PI Errors 14
Revision History 15
11
Bitmasking Plug-In DLL for OPC Interface to the PI System 11
Introduction
The PI OPC 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 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 interface 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 Interface. This version of the plug-in requires 2.1.45 or above of the PI OPC Interface.
11
Bitmasking Plug-In DLL for OPC Interface to the PI System 11
Principles of Operation
The PI OPC 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 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
· PI OPC interface Version 2.1 or greater is required.
· The result may be stored in a Digital or Integer PI tag.
· 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.
· 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.
· OPC Data of type VT_I4 is also supported. If sent to a Digital tag, Location2=3 is required. (See OPC Interface to the PI System manual)
· Bits from different data words can not be combined on the OPC server.
Data arrays are not supported.
11
Bitmasking Plug-In DLL for OPC Interface to the PI System 11
Installation Checklist
For those users who are familiar with running the PI OPC 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 interface, return to this section after reading the rest of this manual in detail.
Follow the steps in the order listed below.
- Install the PI OPC interface.
- Use the PI ICU to configure the OPC 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.
- Start the interface.
11
Bitmasking Plug-In DLL for OPC Interface to the PI System 11
Plug-In Installation and Administration
Plug-In Directory
The OPCPluginBitmask.DLL is on the CD with the PI OPC Interface. It will be installed by the OPC Interface and placed in the directory
PIHOME\Interfaces\OPCInt\Plug-Ins
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 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 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.
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
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.
Format - BITMASK
Bitmask=n
n may be a decimal, hexadecimal (0xnnnn) or binary (0bnnnnnnnnnnnnnnnn) number.
If combined with other keywords in exdesc (see OPC 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.
Example: BITMASK= 0Xaaaa
Leading zeros may be omitted. Spaces are allowed (but no space within numbers).
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
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.
Format – Priorty Bits
Pri_bit=n or Pri_bitz=n
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 plugin examines the bit states. The order listed must match the ordering of the associated PI digital state set.
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:
Bit Position (0-based) / Meaning, if set0 / 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
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:
Offset from Start of Set / State String / Corresponding Data source Bit0 / 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.”
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.
Upgrading the Plug-In
If the plug-in is upgraded independent of the PI OPC interface, install the plug-in in the appropriate directory. Then stop and restart the PI OPC interface according to the instructions in the OPC Interface to the PI System 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 OPC Interface to the PI System 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, and stop and restart the PI OPC interface according to the instructions in the OPC Interface to the PI System manual.
A point configuration ExDesc parameter bitbask=0xnnn is ignored without the /DLLcommand-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.
11
Bitmasking Plug-In DLL for OPC Interface to the PI System 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: