opc sniffer manual(1)

Solutions for

Industrial Agility

Matrikon OPC Sniffer

Matrikon OPC Sniffer

Prepared For: Matrikon Inc. #1800, 10405 Jasper Avenue Edmonton, Alberta T5J 3N4 Canada Phone: (780) 448-1010 x4024 Fax: (780) 448-9191 Email: [email protected]

Revision History: Date Version Description Author

2000-02-17 1.0 Initial document JC 2003-03-18 1.1 Changed name to OPC Logger DB 2004-03-17 1.2 Changed name to OPC Sniffer CV

© Copyright 2003, Matrikon Inc.

CONFIDENTIAL

The information contained herein is confidential and proprietary to Matrikon Inc. It may not be disclosed or transferred, directly or indirectly, to any third party without the explicit written permission of Matrikon Inc. All rights reserved. No part of this document may be reproduced, stored in a retrieval system, translated, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission of Matrikon Inc.

Matrikon OPC Sniffer 4/22/2004

i

Table of Contents

1 Introduction .................................................................................................................................................................... 1

1.1 Overview .................................................................................................................................................................... 1

1.2 Standard System Requirements ................................................................................................................................. 2

2 Installation ..................................................................................................................................................................... 3

3 Usage ............................................................................................................................................................................. 4

3.1 Connecting ................................................................................................................................................................. 4

3.2 Session Logging ......................................................................................................................................................... 4

3.3 Configuration ............................................................................................................................................................. 5

3.4 Snapshots................................................................................................................................................................... 5

4 Known Issues and Limitations ......................................................................................................................................... 6

4.1 COM Identities............................................................................................................................................................ 6

4.2 Enumerated Connections............................................................................................................................................ 6

4.3 Target Server Registry Entries.................................................................................................................................... 6

5 Troubleshooting.............................................................................................................................................................. 7

Appendix A - OPC Compliance ................................................................................................................................................. 8

A.1 OPC Server Object ............................................................................................................................................................. 8

A.2 OPC Group Object.............................................................................................................................................................. 8

A.3 Enumeration Objects ......................................................................................................................................................... 9

A.4 Client ObjectS .................................................................................................................................................................... 9

Appendix B - Log Configuration File...................................................................................................................................... 10

Appendix C - Log Levels......................................................................................................................................................... 11


ii

1 Introduction The Matrikon OPC Sniffer is an invaluable tool for troubleshooting OPC client/server interoperability issues. The Sniffer, a drop-in component that supports both OPC DA 2.0 and 1.0a specifications, transparently logs all client/server activity on standard OPC interfaces. This information is key to diagnosing, pinpointing, and resolving OPC compliance, compatibility, and interoperability issues.

1.1 Overview OLE for Process Control (OPC™ ) is a technology designed to bridge Windows based applications and process control hardware. It is an open standard that permits a consistent method of accessing field data from plant floor devices. This method remains the same regardless of the type and source of data.

OPC servers provide a method for many different software packages to access data from a process control device, such as a PLC. Traditionally, any time a package needed access to a device’s data, a custom interface, or driver, needed to be written. The purpose of OPC is to define a common interface that is written once, then reused by any business, SCADA, MMI, or customs software packages.

Once an OPC server is written for a particular device, it can be reused by any application that is able to act as an OPC client. OPC servers use Microsoft’s OLE technology (also known as the Common Object Model, or COM) to communicate with clients. COM technology permits a standard for real-time information exchange between software applications and process hardware to be defined.

Sometimes, however, small differences in the interpretation of the OPC specification can lead to problems with interoperability between clients and servers. Even with compliance testing and certification, a number of issues may still arise.

The OPC Sniffer acts as a “data scope” into the communication between OPC clients and servers, outputting a “script” of the activities of both components. The resulting information is invaluable for determining where a problem exists in a non-biased and objective way.


1

1.2 Standard System Requirements The Matrikon OPC Sniffer has the following minimum system requirements.

Intel Pentium II 200MHz Processor

64 MB RAM

25 MB hard drive space

Microsoft Windows NT 4.0 Service Pack 5 (or higher)


2

2 Installation The installation program for the Matrikon OPC Sniffer comes on either CD-ROM or 3½” floppy disks. Insert the media in the drive and choose Add/Remove Programs from the Control Panel. Click Install and follow the instructions from the Installation Wizard.

The installation program copies all necessary file to the target computer, registers the various software components, and creates short-cut icons in the Start menu. These components include the following and are installed in MATRIKON\OPC\COMMON under the Program Files folder by default.

Filename Description

OPCSNIFFER.DLL Matrikon OPC Sniffer

OPCDLGCOREPRJ1.DLL Graphics Package (dialog box)

SYSMATLOGEX.DLL Matrikon Logging Component

OPCSNIFFERLOGCONFIG.TXT Sample log configuration file.

The installation program does not install any of the standard OPC components, such as the proxy/stub DLL's or the server browser. It is assumed that these components have already been installed on the target machine along with the OPC client or server being tested. These components are readily available from the common downloads area on the OPC Foundation web site.


3

3 Usage The Matrikon OPC Sniffer is intended to be as simple as possible, both in terms of design and use. Conceptually, the component "shims" in between the OPC client and the OPC server to generate a log of detailed information about the interactions between the two pieces of software. The uncomplicated design of the Sniffer allows it to perform this function transparently without influencing the system’s behavior or introducing new errors.

3.1 Connecting Simply connect to the Sniffer as to any other OPC server. The program ID should appear as "Matrikon.OPC.OPCSniffer" in a listing of available servers on the machine where it is installed. When the connection is made, the Sniffer displays a dialog box asking for the program ID and machine name for the target server:

In the dialog box, use the drop-down boxes to select a target server and (optionally) a remote machine name. Click the Continue button and the Sniffer will launch the target server, beginning the OPC session. If a selection is not made within fifteen seconds, then the Sniffer will use the previous selection (if there was one) in order to avoid a COM time out.

3.2 Session Logging During the session, the Sniffer logs all COM calls between the client and the server, including "call-backs" to methods on client objects. Whenever a call to the server involves the creation of a new object, such as an OPC group or an enumerator, the Sniffer creates another "shim" object to log information for it. Again, this functionality should be transparent to the client provided the server follows the OPC specification for the implementation of these methods.

Depending on configuration settings, the Sniffer logs information to a text file using a specified filter. The log may also appear in a console window "attached" to the client process. Be careful not to close the console window when it is displayed, as this will likely cause the client process to shut down. Other settings help to customize the exact behavior of the log.


4

3.3 Configuration Configure the Matrikon OPC Sniffer by editing a simple text file located in the same directory as OPCSNIFFER.DLL. This file must have the name OPCSNIFFERLOGCONFIG.TXT. It contains settings for the behavior of the log file. The Sniffer reads these settings when the client first connects to it and creates an OPC Server Object. The client must be restarted or the Sniffer must be unloaded and reloaded in order for changes to the configuration file to take effect.

Edit the file using a plain text editor such as NOTEPAD. The contents of a configuration file might look like the following. -LC:\Program Files\Matrikon\OPC\Common\OPCSniffer.log -D7 -M2097152 -STRUE

These settings will generate a log file with the name OPCSNIFFER.LOG in MATRIKON\OPC\COMMON under the Program Files folder. No statements will be filtered out, the log file may achieve a maximum size of 2MB, and the log will also appear in a console window. Default values will be used for the other settings.

See the appendix for a complete list of available settings and log levels.

3.4 Snapshots When the contents of a log file reaches its maximum limit (as specified with the -M parameter in the configuration file), it "wraps around", overwriting the old messages starting at the beginning of the file. This prevents the file from growing indefinitely while keeping as much information in the log file as possible.

However, log statements generated by transient errors may be overwritten before anyone has a chance to spot them, particularly at high-detail log levels. The snapshot feature helps to prevent this scenario by creating a copy of the entire log file after a "trigger" level is reached. When a message is logged at a level equal to or lower (more critical) than the trigger level, the log file will continue recording messages for the specified number of statements before copying the log file.

For example, a setting of -T1 and -C100 will cause the program to initiate a snapshot once an error message is logged. It will continue logging up to 100 additional messages after the triggering message before creating a copy of the log file. The copy's file name is derived from the original log file name, with "-Snapshot" and an incrementing number appended after the extension (i.e. "OPCSNIFFER.LOG-SNAPSHOT1234).


5

4 Known Issues and Limitations The Matrikon OPC Sniffer has the following known issues and limitations.

4.1 COM Identities The Sniffer currently does not maintain COM identities for objects returned via the Sniffer. This may cause problems for clients that depend on COM identity to confirm object instance equality.

Consider the case where a client performs an AddGroup on an OPC Server object, yielding a Group object A with identity X. If the client were to call CreateGroupEnumerator to retrieve the group via an enumerator, the client would receive a reference to the Group object A with identity Y.

Future versions of the Sniffer will be upgraded to preserve COM identity.

4.2 Enumerated Connections The Sniffer does not delegate Connections returned via Next calls on a Connections Enumerator (implementing IEnumConnections). Most clients do not use this mechanism. This limitation should not cause runtime problems except that the Sniffer will not be able to log activity raised to objects returned via this enumeration.

4.3 Target Server Registry Entries The Sniffer does not currently use the OPC Server Browser and requires that all server information be present in the local registry. Most server vendors can provide a .REG file that may be used to insert server registry entries into the local registry.


6

5 Troubleshooting The OPC Sniffer is provided free-of-charge for the benefit of the OPC community. As such, Matrikon is only able to provide email support for the product. Issues related to the OPC Sniffer will be handled with a lower priority. If your issue requires high priority attention, Matrikon offers pay-per-issue support. Contact [email protected] for email support, or [email protected] for pay-per-issue support options.

The following items address some of the most common problems encountered while using the Matrikon OPC Sniffer.

Problem: The OPC client indicates that the server has timed out.

Solution: A COM timeout occurred when you were selecting the target server and remote machine. You should select the appropriate parameters within approximately 1 minute to avoid this timeout.

Problem: The Sniffer’s popup appears numerous times, repeatedly, sometimes too quickly to click Continue.

Solution: Some clients make multiple connections to an OPC server. Because of this behavior, the Sniffer will automatically continue within 15 seconds of client connection. When multiple popups appear, simply wait for the 15 seconds timeout.

Problem: The Sniffer doesn’t log properly.

Solution: Confirm that the Sniffer is able to find its log configuration file, and that the config file is located appropriately.


7

Appendix A - OPC Compliance The Matrikon OPC Sniffer logs information for the following interfaces. Calls to unlisted interfaces are simply delegated to the target server and no information is logged. See the OPC Custom Data Access Standard Version 2.03 for more information.

A.1 OPC Server Object

Interface Notes

IUnknown

IOPCCommon

IOPCServer

IOPCServerPublicGroups No information logged for public groups.

IOPCBrowseServerAddressSpace

IOPCItemProperties

IPersistFile No information logged for file persistence.

IConnectionPointContainer

IConnectionPoint(IOPCShutdown)

A.2 OPC Group Object

Interface Notes

IUnknown

IOPCItemMgt

IOPCGroupStateMgt

IOPCPublicGroupStateMgt No information logged for public groups.

IOPCSyncIO

IOPCAsyncIO2

IOPCAsyncIO (1.0a)

IConnectionPointContainer

IConnectionPoint(IOPCDataCallback)

IDataObject (1.0a) Information logged for OPCSTMFORMATDATA, OPCSTMFORMATDATATIME, and OPCSTMFORMATWRITECOMPLETE streams.


8

A.3 Enumeration Objects

Interface Notes

IUnknown

IEnumUnknown

IEnumString

IEnumConnectionPoints

IEnumConnections

IEnumOPCItemAttributes

A.4 Client ObjectS

Interface Notes

IOPCShutdown

IOPCDataCallback

IAdviseSink Information logged for OPCSTMFORMATDATA, OPCSTMFORMATDATATIME, and OPCSTMFORMATWRITECOMPLETE streams.


9

Appendix B - Log Configuration File In the configuration file, all log settings are preceded by a hyphen (-), may not be preceded by white space, and must be followed by a carriage-return. Each setting is identified by a single letter, and followed immediately by its new value. Log settings include the following:

Setting Description Default Value

-Lfilename Log file name, which must appear in the configuration file. Otherwise, default settings are assumed.

C:\TEMP\OPCSNIFFER.LOG

-Dlevel The log filter level. Note that the greater the quantity of information logged to the file, the greater the impact on program performance.

7 (Debug)

-Msize Maximum log file size, in bytes, after which the file will “wrap”. 1048576 (10MB)

-Noverwrite TRUE: Any pre-existing log file is overwritten. FALSE: New log statements are appended to any pre-existing log file.

TRUE

-Fforcedwrites

TRUE: Ensures that all statements are written to file, even in the even of hardware failure, by repeatedly flushing the file buffer. Decreases program performance at higher log levels. FALSE: Writes are buffered as normal.

TRUE

-Slogtoscreen TRUE: Messages appear on the console screen as they are logged. Decreases program performance at higher log levels. FALSE: Messages are only logged to file.

TRUE

-Tlevel The log snapshot trigger level. When a message is logged at this level, a snapshot of the file will be initiated. 9 (Never)

-Clines The number of additional messages to log prior to generating a snapshot log file once the trigger level has been reached.

100


10


11

Appendix C - Log Levels The following is a comprehensive list of possible log levels. Please note that the levels have a different meaning when they appear in a log statement as opposed to when they are used to set the filter level. In general, a filter level excludes anything logged at a higher level. In other words, a filter level of 3 excludes all statements from the file that are logged at a level of 4 or higher.

Value Level Description

0 Always The statement always appears in the log file regardless of the set filter level. Messages of this type include "Log file opened", etc. Not useful as a filter level.

1 Error The statement is an error over which the user should take corrective action.

2 Warning The statement is a warning over which the user does not need to take corrective action, but may affect the functioning of the software.

3 Advisory The statement is informational. The user does not need to take any corrective action, nor will it affect the functioning of the software.

4 Low The statement is an internal (debug-level) error that does not directly affect the user but may affect other portions of the software that will generate user-level errors. The program may be able to recover from these errors on its own.

5 Medium Additional information regarding internal (debug-level) errors. Used to provide activity logging for critical areas of code.

6 High Full activity and error detail.

7 Debug Complete debugging detail, including function entries and exits.

9 Never No statements are logged at this level. Only use as the trigger level to disable log snapshots.

opc sniffer manual(1)

Documents

opc sniffer cv copyright

opc logger db

retrieval system

standard system requirements

initial document jc

alberta t5j 3n4 canada

jasper avenue edmonton

revision history