OPCAnnotationArray Plug-In
for the PI Interface for OPC DA

Version 2.4.4.x

Copyright © 2006-2013,OSIsoft, LLC

OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA94577USA
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)


Houston, TX
Johnson City, TN
Longview, TX
Mayfield Heights, OH
Philadelphia, PA
Phoenix, AZ
Savannah, GA
Yardley, PA
/ OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSIsoft Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
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
Sales Outlets/Distributors
Middle East/North Africa
Republic of South Africa
Russia/Central Asia / South America/Caribbean
Southeast Asia
South KoreaTaiwan

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, 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, LLC. All other trademarks or trade names used herein are the property of their respective owners.

RESTRICTED RIGHTS LEGEND

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

Table of Contents

Introduction

Principles of Operation

Installation and Configuration Checklist

Plug-In Installation and Administration

Plug-In Directory

Modifying OPCINT.BAT

Configuration of PI Tags

Upgrading the Plug-In

Moving the Plug-In to a New Directory

Uninstalling the Plug-In

Command Line Parameters

Error and Informational Messages

Appendix A: DLL Debugging Options

Revision History

1

OPCAnnotationArray Plug-In DLL for OPC Interface to the PI System1

Introduction

The OPCAnnotationArray Plug-in is an addition to the PI Interface forOPC DA that extends its functionality for storing array values into PI Annotations. It is implemented in the OPCAnnotationArrayPlugIn.DLL1 and can only be started by the OPC DA interface. The plug-in2 supports its own command line parameters that are necessary for its proper configuration.

This manual describes how the plug-in works,configuration requirements for PI tags, and command line parameters for troubleshooting problems or getting more informational messages.

This DLL is designed to start and maintain a separate PI SDK connection to the PI System and to use this connected for sending data into PI tag annotations. While using this DLL, the interface can also send data using its normal operation. The DLL handles only the tags that are configured for it. It also maintains an internal data queue (cache) to make sure that data is not lost during short time disconnection from the PI System. All other tags are handled by the interface.

The DLL prints messages into pipc.log that can be informational messages or error messages, which indicate the exact problems during its operation. The DLL allows the user to configure whether to use timestamps provided by the OPC Server or to create its own timestamps at the time when the data was received.

The plug-in can be used with the OPC DA interface version 2.4.4.0 or greater. Please note that this plug-in has been updated to use UTC timestamps and will no longer work with older versions of the OPC DA interface.

Notes:

1. Neither this manual nor the plug-in are stand-alone products; they are to be used in conjunction with the OPC DA interface.

2. The words plug-in and DLL have the same meaning in the context of this manual and will be used interchangeably.

1

OPCAnnotationArray Plug-In DLL for OPC Interface to the PI System1

Principles of Operation

The OPCAnnotationArrayPlugIn.DLLis designed to extend the functionality of the PI Interface for OPC DA for handling array data. The DLL only works with array items (on the OPC Server). The array data are put into a PI Annotation structure and sent to PI. Here is how it works:

  1. Before starting the interface and using the DLL, PI tags that belong to the DLL should be properly configured. The configuration requires creating String PI tags with specific settings: InstrumentTag should contain an ItemID of OPC Server array item; Location2 should be set to 1024; ExDesc should have a keyword ArrayType pointing to a variant datatype of an array item (e.g. ArrayType=VT_R4);
  2. The DLL tags should be put into a separate scan class and not mixed with other interface tags. It is recommended to make those tags - Advise tags (i.e. Location3=1). This should prevent getting duplicate copies of array values in PI.
  3. When the interface starts it loads the DLL, initializes its internal objects based on command line parameters, connects to a specified PI Server, gets PI tag attributes for interface specific tags, connects to the OPC Server, and creates groups for each scan class. At this point the command line parameters and tag attributes will also be passed to the DLL. The DLL will initialize itself and store scan class and tag information in its internal cache. It will also establish a separate connection to PI Server using PI SDK. This connection is different from the connection that the interface made and is maintained by the DLL. However, the DLL does not make any connection to the OPC Server. Instead, it will rely on the interface to make required calls to the OPC Server and pass on the data it receives from the OPC Server.
  4. Once the new data is received by the OPC DA Interface and passed to the DLL, the DLL puts data into its internal data queue/cache. This data queue is designed to provide some robustness in case the connection to the PI Server is lost. In this situation all data will be stored in the data queue until a connection to the PI Server is restored. The data queue size can grow up to a specified size in /DLLQS parameter. This is a memory cache, not a file cache. So if the interface is stopped while the data queue had some data, everything will be lost. Currently, the DLL does not support buffering data into a file.
  5. The DLL creates a separate thread that is responsible for packaging data into a PI Annotation structure and sending data to PI. This thread also maintains an SDK connection to PI. If the connection is lost, the thread will keep trying to restore the connection and resume sending data.
  6. The DLL is designed to print messages about internal errors or error states of SDK objects. The messages are categorized into different types, such as informational, configuration error, internal error, and PI SDK error messages. The messages are printed in pipc.log and can be easily distinguished from the interface messages. See Error and Informational Messagessection for more details.
  7. Since the PI tags that correspond to OPC Server’s array items have a PI string datatype, the new value in the PI tag will contain a string with type, size and, variant datatype information (e.g. Annotation Data: Type=Array, Size=100, Datatype=VT_R4). The actual array data values (elements) will be stored in an annotation for this value.

1

OPCAnnotationArray Plug-In DLL for OPC Interface to the PI System1

Installation and Configuration Checklist

This checklist provides a sequence of steps that should be followed in order to properly configure the plug-in and get it up and running. It is important that the user is familiar with the usage of the OPC DA Interface and ICU, as well as plug-in specific tag and command line parameter configuration options before following these steps.

  1. Install the PI Interface Configuration Utility (PI ICU) if it is not installed;
  2. Install the PI Interface for OPC DA (v2.4.4.0 or greater). This should also install the PI ICU Control for the interface and OPCAnnotationArrayPlugIn.DLL in …\OPCInt\Plug-ins directory;
  3. Use ICU to properly configure both the interface and DLL;
  4. Use PI_OPCClient tool or some other OPC client tool for getting ItemIDs of array items from the OPC Server. This step should also verify that the client can connect to the OPC Server and get array data;
  5. Create corresponding PI tags for each OPC Server’s array item;
  6. Make sure that PI SDK Connection Manager contains a targeted PI Server in its known servers list;
  7. Start the interface and check if pipc.log has any error messages;
  8. If there are no error messages, check the PI tags for new data. Use appropriate tools to view annotation data in PI tags.

1

OPCAnnotationArray Plug-In DLL for OPC Interface to the PI System1

Plug-In Installation and Administration

Plug-In Directory

The OPCAnnotationArrayPlugIn.DLL is on the CD with the PIInterface for OPC DA (or can be downloaded from OSIsoft’s technical support web site: ). When you install the interface, it will be copied into the plug-ins subdirectory. For instance, if the interface is installed in

PIHOME\Interfaces\OPCInt

then the DLL will be located in

PIHOME\Interfaces\OPCInt\Plug-Ins\

Modifying OPCINT.BAT

The user must activate the DLL by adding this command to the opcint.bat manually if it is not maintained by the PI Interface Configuration Utility (PI-ICU), or by using PIICU (see the PI Interface for OPC DA Manual for more details). The following is the example for adding the parameter manually:

opcint.exe /ps=O … ^

/DLL=PIHOME\Interfaces\OPCInt\Plug-Ins\OPCAnnotationArrayPlugIn.DLL

After adding this line, the OPC DA interfacewill automatically load the DLL at startup. If the interface is already running, you will need to stop and restart the interface for the DLL to be activated.

Note: The caret “^” character 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\OPCAnnotationArrayPlugIn.DLL"

If you are using PI ICU to configure the OPC DA interface, there is a selection for Plug-Ins. You should include the above path in that space. To select the DLL file, use browsing button “…” for that field.

Configuration of PI Tags

Pointtype

It is a requirement that the PI tag corresponding to an array item on the OPC Server is created as a string tag. The string tag will contain an array size and variant datatype information about that array as a value in PI Archive and the actual array will be stored as PI annotation attached to this value.

Instrumenttag

This attribute should contain an ItemID of array item on the OPC Server. OPC arrays should have only one ItemID that uniquely identifies them. The ItemID can be found in the OPC Server address space using OPC client tools that can browse the address space. You can use PI_OPCClient tool for that purpose.

Location2

In general use of the OPC DA Interface, Location2 specifies what special handling should be done with the data, such as asking for a different datatype than would normally be requested for a given tag type. However, for the current plug-in tags Location2 should be equal to 1024(Location2=1024). This allows the plug-in to identify the tags that should be handled by it. All other tags will be handled by the interface and Location2 can still be used, but it has to be less than 1024.

Location3

It is recommended that Location3 should be set to 1 for this plug-in. This will make an Advise tag, which means that the data will be received from the OPC Server only if it changed (i.e. value or timestamp). This should prevent from having duplicate arrays in PI.

ExDesc

Each OPC item has a variant datatype. This can be viewed with PI_OPCClient tool or some other tool that can browse OPC Server address space. It is required to set ExDesc attribute with that variant datatype. You should use a keyword ArrayType to do that. For example, ArrayType=VT_R8.

Upgrading the Plug-In

If the plug-in is upgraded independent of the OPC DA interface, copy the plug-in in the appropriate directory. Then stop and restart the 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. You will need to change opcint.bat either manually (only if you configure the interface without PI ICU) or with PI ICU to reflect the name of the new directory and then stop and restart the interface as described in the PI Interface for OPC DA manual.

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 opcint.bat file directly if PI ICU is not used for interface configuration or if you are using PI ICU, delete the Post Processing DLL field, and stop and restart the OPC DA interface according to the instructions in the PI Interface forOPC DA manual.

1

OPCAnnotationArray Plug-In for the PI Interface for OPC DA1

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 (1-15). See Appendix A: DLL Debugging Options section for more details.
/DLLDT=#
(No default)
Optional / Debug tagname. This parameter is used in combination with /DLLDB. This allows you to monitor data received for one tag.
/DLLQS=#
(Minimum: 20000 Default: 50000)
Required / Data queue size. As mentioned earlier the DLL creates a data queue to improve robustness of its operation. This queue will buffer data if the DLL loses connection to PI Server. Since the queue is maintained in memory (not a file), it is important to set a reasonable limit for its size. This should be calculated based on available RAM, size of array data, data update frequency, and maximum time period for data to be buffered. If the queue gets full, all subsequent data coming from the OPC Server will be lost. When the connection to PI Server is restored, the DLL will try to empty the queue as fast as possible.
/DLLTS=Y or N(Default: N)
Optional / Source for timestamp. If “N” is used, the DLL creates a timestamp based on the current time of the local node. If “Y” is used, the DLL uses the timestamp from the OPC Server. In both cases the timestamp is not adjusted to PI Server time (as the case with OPC DA Interface). Therefore, make sure that the PI Server time and local node time are synchronized.

1

OPCAnnotationArray Plug-In for the PI Interface for OPC DA1

Error and Informational Messages

The DLL messages are written to thepipc.logfile. The location of the pipc.log 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.

The messages logged by the dll are pre-pended by three strings -Name, IDand DLL. Name is anOPC DA Interfaceidentifier that is standard for all messages by the interface.IDis an interface ID, which is specified using the /IDparameter on the startup command line. DLL is just a constant string which indicates that the message came from DLL. Here is an example:

OPCpi> 1> DLL> Info: Connected to PI Server: opctest, Version: PI 3.4.370.76

The messages can indicate errors or can be just informational messages. This should be identified by the message type string. The following message types are defined:

  • Info – informational messages, these messages report an internal state of the plug-in;
  • Error – internal error or error coming from PI SDK or COM, these errors can be critical and cause abnormal behavior;
  • Exception – this indicates that exception is thrown by PI SDK or COM, or internal exception, this can be critical and cause abnormal behavior;
  • Config Error – configuration error, this implies that command line argument is not properly set.

For version 1.3 and greater of the PIAPI, 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.