OPCTimestampClamping Plug-In DLL for OPC DA Interface to ...



OPCTimestampClamping Plug-In DLL

for OPC DA

Interface to the PI System

Version 2.3.11.0

Revision A

Copyright © 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) | |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, Inc. 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, Inc. 

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.

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

Configuring 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 OPCTimestampClamping Plug-in is an addition to the PI OPC DA Interface that extends its functionality for clamping the data timestamp to a fixed, rounded value within an allowable time window. It is implemented in the OPCPlugInTimestampClamping.dll1 and can only be used by the PI OPC DA Interface. The plug-in2 supports its own command line parameters that are necessary for its proper configuration.

The motivation to develop this plug-in is the fact that some PI client applications (which utilize PI Server data) require the time-series data to be available at fixed, pre-determined time slots. For example, a PI application that expects data to be available at 5 minute intervals. Moreover, those time intervals should start at the top of 5 min mark without significant delays (i.e. delays outside a given tolerance). If these conditions cannot be satisfied, the PI application cannot rely on PI data and function properly.

The OPC DA Interface retrieves data from an OPC Server using asynchronous calls/operations to achieve greater performance and efficiency. However, this architecture cannot guarantee that if the data is requested at specific time intervals, the OPC Server will deliver them at those intervals or that the timestamps of data will be as expected. According to the OPC Data Access specification (v2.05a), the OPC Server can decide how to apply timestamps to values. Some OPC Servers use timestamps coming from the original data sources, (e.g. PLC, DCS), while other OPC Servers create their own timestamps at the time of data acquisition. Therefore, the OPC Client cannot expect the timestamps to be at requested time intervals. For example, when the PLC and OPC Server are in different locations, the timestamp of a data event applied by the OPC server may differ from the original timestamp (provided by the PLC) due to latency and other timing issues.

This plug-in extends the OPC DA Interface functionality and provides a solution to meet requirements when data timestamps must be at specific intervals. The plug-in is a post-processing DLL for the interface. This means that timestamps get processed after the interface receives data from the OPC Server and before the data is sent to the PI Server. During the operation, the DLL posts informational and error messages to pipc.log.

This specification describes how the plug-in works, configuration requirements for PI tags, and command line parameters for troubleshooting problems and getting more informational messages. The plug-in can only be used with PI OPC DA Interface version 2.3.11.0 or later.

Notes:

1. Neither this specification nor the plug-in are stand-alone products; they must be used in conjunction with the PI OPC DA Interface.

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

Principles of Operation

The OPCPlugInTimestampClampling.dll extends the functionality of the PI OPC DA Interface and allows rounding timestamp values to a pre-determined time period based on a specified “Deadband” window.

Assumptions

a) The OPC Server does not send out-of-order data;

b) The data does not come with significant delays and in bursts.

If these assumptions are not true, the data is considered to be “abnormal” and the plug-in does not properly process such data.

Execution

Given that the interface receives “normal” data, this is how the plug-in processes timestamps:

1. Before starting the interface and using the DLL, PI tags to be processed by the DLL must be properly configured. Configuration requires the keyword Deadband in the ExDesc attribute. The Deadband keyword signifies that the timestamp will be corrected to the nearest scan interval time if it falls within the boundaries of the Deadband for that scan interval. The Deadband is specified in seconds and applied to every scan interval. A timestamp that falls outside the Deadband will not be changed. This process is called Timestamp Clamping.

2. DLL tags (i.e., PI tags associated with the DLL) must be put into a separate scan class and not mixed with other interface tags. DLL Tags with different Deadband values can be put in the same scan class. The maximum number of scan classes the DLL tags can be assigned to is 99.

3. DLL tags can be Advise or Polled. Advise and Polled tags should not be mixed in the same Group (i.e. scan class). For other guidelines and information about tag configuration and grouping, see the OPC DA Interface to the PI System manual.

4. The PI OPC DA Interface can be configured to receive timestamps from an OPC server without clock adjustment with PI Server.2 To cope with potential differences in clock settings after adjustments, the scan interval should be larger than 5 seconds.

Note: With this setting, you must ensure that clock settings on both OPC and PI servers are appropriate (i.e. either the same or the PI Server clock is ahead) and the clocks are either automatically synchronized or are checked frequently.

DLL operation is illustrated in the following figure:

[pic]

Timestamps of data inside the DeadBand (DBd) will be rounded to the nearest clamping periods (tn-1, tn, or tn+1). Data with timestamps equal to or outside the specified DeadBand between two scan periods will be returned with the original timestamp.

Note: The length between two timestamp clamping periods (between tn-1 and tn or between tn and tn+1) is an evenly divided interval (a multiple of the interface scan interval, independent of the offset) since UTC1970. Consequently, the period (tn-1, tn, or tn+1) evenly divides an hour, e.g. for a 4 min scan interval, the timestamp clamping periods will be:

…, 12:04:00, 12:08:00, 12:12:00,…

Not …, 12:01:00, 12:05:00, 12:09:00,…

Not …, 12:02:00, 12:06:00, 12:10:00,…

Not …, 12:03:00, 12:07:00, 12:11:00,…

Installation and Configuration Checklist

This is the sequence of steps that must be followed to properly configure and run the plug-in. You should be familiar with 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 OPC DA Interface (v2.3.11.0 or later). This also installs the PI ICU Control for the interface and OPCPlugInTimestampClampling.dll in …\OPCInt\Plug-Ins.

3. Use the ICU to configure both the interface and DLL.

4. Use PI_OPCClient tool (or an equivalent OPC client tool) to get ItemIDs from the OPC Server. Use this step to also verify that the client can connect to the OPC Server and get array data.

5. Create PI tags (that correspond to the ItemIDs obtained in step 4) where timestamp clamping is to be applied.

6. Verify that PI SDK Connection Manager contains a targeted PI Server in its known servers list.

7. Start the interface and check pipc.log for error messages.

8. If there are no error messages, check the PI tags for new data. Use appropriate tools to view timestamp clamped data in PI tags.

Plug-In Installation and Administration

Plug-In Directory

The OPCPlugInTimestampClampling.dll is on the PI OPC DA Interface CD. You can also download the DLL from the OSIsoft Ttechnical Support website: ). When you install the interface, the DLL is copied into the plug–ins subdirectory. For instance, if the interface is installed in

PIHOME\Interfaces\OPCInt

the DLL is located in

PIHOME\Interfaces\OPCInt\Plug-Ins\

Modifying OPCINT.BAT

Specify the DLL path

You must activate the DLL by adding the following command to the opcint.bat file either manually or by using the PI Interface Configuration Utility (PI-ICU). For more information, see the PI OPC DA Interface Manual. The following is an example of the command line you add manually to the opcint.bat file:

OPCInt.exe /ps=O … ^

/DLL=PIHOME\Interfaces\OPCInt\Plug-Ins\OPCPlugInTimestampClampling.dll

Note: The caret (“^”) at the end of all lines in the command file, except for the last line, is a continuation character indicating that more command text follows.

After adding this line, the PI OPC DA Interface automatically loads the DLL at startup. If the interface is already running, you must stop and restart the interface for the DLL to be activated.

If the path name contains spaces, the whole /DLL startup parameter must be surrounded by double quotes. Example:

/DLL="PIHOME\interfaces\OPCInt\Plug-Ins\OPCPlugInTimestampClampling.dll"

If you use PI ICU to configure the PI OPC DA Interface, there is a field for Plug-Ins. Include the DLL path specificed above in that space. To select the DLL file, use the browsing button (indicated by “…”) for that field.

Recommended setting for /TS and /IT parameters

|/TS=U |Specifies that the timestamps from OPC Server are not adjusted to PI Server time. |

| |Note: With this setting, you must ensure that PI Server time and local node time are synchronized. |

| |/TS=Y or /TS=N may also be used, however time adjustments and additional latency may affect timestamp |

| |clamping effects (e.g. if you specify /TS=N and where the interface and OPC servers are at different |

| |locations). |

|/IT=Y |discards the sub-second portion of the timestamps. |

[pic]

Configuring PI Tags

Location3

Setting Location3 to 0 makes a polled tag. This means that the interface sends an Asynchronous Refresh call for the Group. Setting Location3 to 1 makes an advise tag. This means that the OPC Server sends data whenever a new value is read into the server cache.

Some OPC servers send different timestamps for Refresh than for Advise. For Advise, the server sends the timestamp when the value changes. For Refresh, the timestamp is sent when the server accesses the cache. If time-correlation between the clamped timestamp and the original timestamp (provided by PLC) is important, then creating Advise tags may be preferable.

However, depending upon the OPC server’s update rate, it may be more likely to get data archived at every scan interval for Refresh rather than Advise. In this case, creating Refresh tags may be preferable.

ExDesc

Deadband is specified in the extended descriptor for tags using timestampclamping. The Deadband is specified in seconds and applied to every scan interval. For example, DEADBAND=100 signifies that any timestamp that falls within 100 second of a scan interval, will be corrected to that scan interval.

The value of DeadBand should be less than 10 mins and less than ½ the scan period. This restriction is verified at startup. If the Deadband does not meet these restrictions, the DLL writes an error message in pipc.log:

OPCpi> 1> DLL> Config Error: dll Tag: TSCLAMP_TEST_1 DeadBand should be less than 1/2 ScanRate...

When this occurs, the dll tag is not loaded in the interface.

Upgrading the Plug-In

To upgrade the plug-in independently from the PI OPC DA Interface, copy the plug-in to the appropriate directory. You must then stop and restart the interface according to the instructions in the PI OPC DA Interface manual.

Moving the Plug-In to a New Directory

It is possible to move the plug-in to a new directory. You must change opcint.bat either manually or with PI ICU to reflect the name of the new directory. You must then and then stop and restart the interface as described in the PI OPC DA Interface Manual.

Note: OSIsoft does not recommend moving the plug-in to a different directory.

Uninstalling the Plug-In

To run the interface without the plug-in, manually delete the /DLL command-line parameter from the opcint.bat file or clear the Post Processing DLL field in PI ICU. You must then stop and restart the PI OPC DA Interface according to the instructions in the PI OPC DA Interface 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. For information about these parameters, see the PI OPC DA Interface Manual.

DLL specific parameters:

|Parameter |Description |

|/DLLDB=# |Debug level (2-58). See Appendix A: DLL Debugging Options section for more |

|(Default: 0) |details. |

|Optional | |

|/DLLDT= |Debug tagname. This allows you to monitor data received for one tag. |

|(No default) | |

|Optional | |

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.

Messages logged by the dll are pre-pended by three strings - Name, ID, and DLL Name. These three strings comprise the OPC DA Interface identifier that is standard for all interface messages. ID is an interface ID specified by the /ID parameter on the startup command line. DLL is a constant string that indicates that the message came from DLL. Here is an example:

OPCpi> 1> DLL> Info: dll Tag: TIMECLAMP_TEST_1 is successfully loaded...

Messages can indicate errors or just be informational. This is 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 an exception is thrown by PI SDK, COM, or an internal exception. These can be critical and cause abnormal behavior;

• Config Error – configuration error. These messages specify that a 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. If 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 see only informational messages in the log.

Message Examples:

09-Mar-09 23:57:33

OPCpi> 1> DLL> Info: OPCTimestampClamping Version: 2.3.11.0

09-Mar-09 23:57:33

OPCpi> 1> DLL> Info: Debug tag will be: TIMECLAMP_TEST_1

Appendix A:

DLL Debugging Options

The plug-in uses specific debugging parameters (/dlldb and /dlldt) that enable sending informational messages to the pipc.log when specific events occur during DLL operation. These messages assist in understanding problematic or unexplained behavior of the DLL or the PI OPC DA Interface. The /dlldb parameter is a bitmask. This means that 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 the /dlldb settings.

/dlldb=1

This setting is reserved for internal testing only and is not useful to the users.

/dlldb=2

This setting enables sending additional informational messages to the pipc.log file. For example, these messages may include adding and deleting tags, thread states.

/dlldb=4

When used with /dllDT=”TagName” parameter this setting enables monitoring for a specified tag. The DLL posts the name of the tag, its scan period, its deadband, and its timestamps (UTC) before and after clamping.

Revision History

|Date |Editor |Comments |

|10-Mar-2009 |EKuwana |Draft of the document |

|4-Jun-2009 |MKelly |Version 2.3.11.0 Revision A, Updated the title and contact pages, fixed |

| | |headers, footers and section breaks. Added TOC. |

| | | |

| | | |

| | | |

| | | |

| | | |

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download