OPCAnnotation Array Plug-In DLL for OPC DA Interface to ...
OPCAnnotationArray Plug-In
for the PI Interface for OPC DA
Version 2.4.4.x
Copyright © 2006-2013, OSIsoft, LLC
|OSIsoft, LLC | |OSIsoft Australia |
|777 Davis St., Suite 250 | |Perth, Australia |
|San Leandro, CA 94577 USA | |Auckland, New Zealand |
|(01) 510-297-5800 (main phone) | |OSI Software GmbH |
|(01) 510-357-8136 (fax) | |Altenstadt, Germany |
|(01) 510-297-5828 (support phone) | |OSIsoft Asia Pte Ltd. |
| | |Singapore |
|techsupport@ | |OSIsoft Canada ULC |
|Houston, TX | |Montreal, Canada |
|Johnson City, TN | |Calgary, Canada |
|Longview, TX | |OSIsoft, LLC Representative Office |
|Mayfield Heights, OH | |Shanghai, People’s Republic of China |
|Philadelphia, PA | |OSIsoft Japan KK |
|Phoenix, AZ | |Tokyo, Japan |
|Savannah, GA | |OSIsoft Mexico S. De R.L. De C.V. |
|Yardley, PA | |Mexico City, Mexico |
| | |OSIsoft do Brasil Sistemas Ltda. |
| | |Sao Paulo, Brazil |
| | | |
|Sales Outlets/Distributors | | |
|Middle East/North Africa | |South America/Caribbean |
|Republic of South Africa | |Southeast Asia |
|Russia/Central Asia | |South Korea Taiwan |
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 1
Principles of Operation 3
Installation and Configuration Checklist 5
Plug-In Installation and Administration 7
Plug-In Directory 7
Modifying OPCINT.BAT 7
Configuration of PI Tags 8
Upgrading the Plug-In 9
Moving the Plug-In to a New Directory 9
Uninstalling the Plug-In 9
Command Line Parameters 11
Error and Informational Messages 13
Appendix A: DLL Debugging Options 15
Revision History 17
Introduction
The OPCAnnotationArray Plug-in is an addition to the PI Interface for OPC 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.
Principles of Operation
The OPCAnnotationArrayPlugIn.DLL is 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 Messages section 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.
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.
Plug-In Installation and Administration
Plug-In Directory
The OPCAnnotationArrayPlugIn.DLL is on the CD with the PI Interface 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 PI-ICU (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 interface will 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.
[pic]
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 /DLL command-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 for OPC DA manual.
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=# |Debug level (1-15). See Appendix A: DLL Debugging Options section for more details. |
|(Default: 0) | |
|Optional | |
|/DLLDT=# |Debug tagname. This parameter is used in combination with /DLLDB. This allows you to |
|(No default) |monitor data received for one tag. |
|Optional | |
|/DLLQS=# |Data queue size. As mentioned earlier the DLL creates a data queue to improve |
|(Minimum: 20000 Default: |robustness of its operation. This queue will buffer data if the DLL loses connection |
|50000) |to PI Server. Since the queue is maintained in memory (not a file), it is important to|
|Required |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) |Source for timestamp. If “N” is used, the DLL creates a timestamp based on the |
|Optional |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. |
Error and Informational Messages
The DLL messages are written to the pipc.log file. 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 PIHOME entry is:
C:\PIPC
then the pipc.log file will be located in the c:\PIPC\dat directory.
The messages logged by the dll are pre-pended by three strings - Name, ID and DLL. Name is an OPC DA Interface identifier that is standard for all messages by the interface. ID is an interface ID, which is specified using the /ID parameter 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 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.
In normal operations, you should only see informational messages in the log. Here are a few examples:
21-Feb-07 23:57:33
OPCpi> 1> DLL> Info: OPCAnnotationArrayPlugIn Version: 1.0.0.0
21-Feb-07 23:57:33
OPCpi> 1> DLL> Info: Debug tag will be: ANNOTATION_TEST_1
21-Feb-07 23:57:35
OPCpi> 1> DLL> Info: Connected to PI Server: opctest, Version: PI 3.4.370.76
Appendix A:
DLL Debugging Options
The plug-in uses its DLL specific debugging parameters (/dlldb and /dlldt), that enables sending informational messages to the pipc.log on occurrence of specific events during DLL operation. These can assist in understanding problematic or unexplained behavior of the DLL itself or the OPC DA Interface. The /dlldb parameter is actually a bitmask, which means you can set more than one option at the same time. For example, a value of /dlldb=6 is the same as /dlldb=2 and /dlldb=4. The following describes all the possible settings and what they do:
/dlldb=1
This setting is reserved for internal testing only and is not useful to the users.
/dlldb=2
This setting is for enabling additional informational messages to be sent to the pipc.log file. The messages may include adding and deleting tags, thread states, and etc.
/dlldb=4
This setting should be used with /dllDT=TagName parameter for monitoring a specified tag. The DLL will print the array size and OPC quality when the data is received and added to the data queue.
/dlldb=8
This setting prints information about data queue size.
Revision History
|Date |Editor |Comments |
|20-Feb-2007 |AMaksumov |Draft of the document |
|26-Mar-2007 |AMaksumov |Changes to Principles of Operations, Installation and Configuration |
| | |Checklist, and Configuration of PI Tags sections. |
|19-Apr-2007 |AMaksumov |Changes to Error and Informational Messages and DLL Debugging Options |
| | |sections. |
|24-Apr-2007 |MKelly |Version 1.0.0.0, Rev A: Updated table of contents, updated screenshots |
| | |for ICU Control, fixed page setting, attached current document template, |
| | |fixed headers and footers. |
|1-Jun-2009 |LCraven |Updated version |
|03-Jun-2009 |MKelly |Version 2.3.11.0 Revision A, Fixed headers and footers, updated title and|
| | |contact pages. |
|11-Mar-13 |ALoe |Version 2.4.4.0, updated required version of OPCInt |
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related download
- understanding universal plug and play
- 1 1 2 a basic circuits
- opcannotation array plug in dll for opc da interface to
- electric fields and potential difference unit plan
- ionic and covalent bonds conductivity lab
- repower event list plug in for the pi interface for opc da
- what spark plug do i use for my austin healey
- vanderbilt university
- what is the intra business e commerce objective