Bitmasking Plug-In DLL
for OPC
Interface to the PI System

Version 1.2.0.0

1

UniInt End-User Interface to the PI System

How to Contact Us

Phone / (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web /
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721

Unpublished -- rights reserved under the copyright laws of the United States.
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

Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HPUX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
OPCPluginBitmask.doc

 2000-2001 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577

1

UniInt End-User Interface to the PI System

Table of Contents

Introduction

Principles of Operation

Limits

Installation Checklist

Plug-In Installation and Administration

Plug-In Directory

Modify OPCINT.BAT

Configure PI Tags

Format

Upgrading the Plug-In

Moving the Plug-In to a New Directory

Uninstalling the Plug-In

Error and Informational Messages

Message Logs

Troubleshooting

System Errors and PI Errors

Revision History

1

The Title of the Interface Manual1

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 PIOPC). The OPCPluginBitMask.DLL allows for selecting specific bits out of a data word received from an OPC server and store 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 versions of the PI-OPC Interface.

1

The Title of the Interface Manual1

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 ‘instrument tag’ field or ‘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 supported, too. If sending them to a Digital tag, Location2=3 is required. (See OPC Interface to the PI System manual)
  • You cannot combine bits from different data words on the OPC server.
    Data arrays are not supported.

1

The Title of the Interface Manual1

Installation Checklist

For those users who are familiar with running the PI-OPC interface with the Bitmasking Plug-in DLL, this checklist helps you in getting the Bitmasking Plug-in DLL up and running. If you are not familiar with the Bitmasking Plug-in DLL for the PI-OPC interface, you should return to this section after reading the rest of this manual in detail.

You should follow the steps in the order listed below.

  1. Install PI-OPC interface.
  2. Modify OPCINT.BAT to activate the DLL.
  3. Configure PI tags.
  4. Start the interface.

1

The Title of the Interface Manual1

Plug-In Installation and Administration

Plug-In Directory

The OPCPluginBitmask.DLL is on the CD with the PI-OPC interface. It must be copied into the plug-in subdirectory. For instance, if the interface is installed in

PIHOME\interfaces\opcint

then the DLL should be installed in

PIHOME\interfaces\opcint\plug-ins

Modify OPCINT.BAT

The plug-in, OPCPluginBitmask.DLL, is on the CD with the PI-OPC interface and must be copied into the subdirectory called plug-ins underneath the PI-OPC interface directory. The installer must activate the DLL by adding this command to the batch file, opcint.bat, which specify its location. For example:

opcint.exe /ps=O … ^

/DLL=PIHOME\interfaces\opcint\plug-ins\OPCPluginBitMask.DLL

After adding the last two lines, the PI-OPC interface will automatically load the plug-in at startup, and manifest bit masking. If the interface is already running, you will need to restart the interface 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=PIHOME\interfaces\opcint\plug-ins\OPCPluginBitMask.DLL"

Configure PI Tags

The OPCPluginBitMask.DLL uses the keyword Bitmask in the ExDesc point attribute to determine the masking. You cannot combine bits from different data words on the OPC server. Data arrays are not supported.

Format

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.

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. You will need to change opcint.bat to reflect the name of the new directory and then stop and restart the interface as described in the OPC Interface to the PI Systemmanual.

Uninstalling the Plug-In

If for some reason you want to run the interface without the plug-in, delete the /DLLcommand-line parameter from the batch file, opcint.bat, and stop and restart the PIOPC 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 you might not need to remove the /DLL command-line parameter.

1

The Title of the Interface Manual1

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. IDis 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 WinNT 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 pilogsrvprocess 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 PIAPIInstallationInstructions 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.

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 expected)
    Bit mask is ignored.

Errors are repeated after a point edit.

Other errors should be handled by the PI-OPC interface itself.

Troubleshooting

The /DB startup parameter is used by OPCPluginBitMask.DLL, too. 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.

  • /DB=1 or greater documents relevant startup information (Actually, here this is just the /DB level itself)
  • /DB=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

System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.

Error Descriptions on NT

On NT, descriptions of system and PI errors can be obtained with the pidiag utility:

\PI\adm\pidiag –e error_number

1

The Title of the Interface Manual1

Revision History

Date / Editor / Comments
05-Apr-01 / CG / Formatting
05-apr-01 / JML / Beautification
09-Apr-01 / MHES / Version 1.0.1: Added specific information
17-Apr-01 / CG / JML / Formatting
18-Apr-01 / MHES / Added example for decimal format,
Message logs
19-Apr-01 / CG / Formatting

1

The Title of the Interface Manual1