Time Array OPC data



Time Array Plug-In

for OPC

Interface to the PI System

Version 1.1.2

How to Contact Us

|Phone |(510) 297-5800 (main number) |

| |(510) 297-5828 (technical support) |

|Fax |(510) 357-8136 |

|E-mail |techsupport@ |

|World Wide Web | |

|Mail |OSIsoft |OSI Software, Ltd |

| |P.O. Box 727 |P. O. Box 8256 |

| |San Leandro, CA 94577-0427 |Level One, 6-8 Nugent Street |

| |USA |Auckland 3, New Zealand |

| | | |

| |OSI Software GmbH |OSI Software, Asia Pte Ltd |

| |Hauptstra(e 30 |152 Beach Road |

| |D-63674 Altenstadt 1 |#09-06 Gateway East |

| |Deutschland |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. HP-UX 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.

PI_OPCPluginTimeArray.doc

( 2001- 2002 OSI Software, Inc. All rights reserved

777 Davis Street, Suite 250, San Leandro, CA 94577

Table of Contents

Introduction 1

Principles of Operation 3

Installation Checklist 5

Plug-In Installation and Administration 7

Plug-In Directory 7

Installation Procedures 7

Modify OPCINT.BAT 7

Configure PI Tags 7

Upgrading the Plug-In 8

Moving the Plug-In to a New Directory 8

Uninstalling the Plug-In 8

Error and Informational Messages 9

Message Logs 9

Messages 9

System Errors and PI Errors 11

Appendix A: Debugging 13

/dlldebugtag=tagname 13

/dlldb=# 13

Debugging Messages 14

Revision History 15

Introduction

This paper contains information about the OPCPluginTimeArray.DLL. This DLL allows the transposition of an array of values into a series of successive values for a single tag. When a tag is configured as a Time Array tag, the interface will ask for the tag as an array of values. For instance, if the tag is a Float32 PI tag, the interface will ask the OPC server for an array of VT_R4 values. The interface does not specify how many values should be in the array, and it will pass the data on to the DLL directly.

• OPCINT Version 2.1.32 or greater is required.

• The OPCPluginTimeArray dll will not process string tags. All numeric or digital tags are allowed. String values from the OPC server will be accepted.

• The OPCPluginTimeArray dll will work with both v1.0a and v2.0 OPC servers.

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

Principles of Operation

The OPCPluginTimeArray.dll will accept the array and, if the quality of the data is good, it will store the array of values in PI as successive data values, incrementing the timestamp given with the array by a configured interval for each value, such that the first value has timestamp T, the second value has timestamp T + (1 * Interval), the third value has timestamp T + (2 * Interval), etc., where T is the timestamp that was sent with the array. All the values will have the same quality, since the quality is sent from the OPC server as the quality for the entire array. If the quality is not GOOD (see the OPC interface manual for more on quality), the DLL will pass the array back to the interface, which will process it normally, and store one entry in PI with the appropriate digital state corresponding to the quality.

Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps you in getting the PI-OPC Interface up and running with the OPCPluginMetso.DLL. If you are not familiar with the plug-in, 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. Define digital states

3. Modify OPCINT.BAT to activate the DLL.

4. Configure PI tags.

5. Start the interface.

Plug-In Installation and Administration

Plug-In Directory

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

PIHOME\interfaces\opcint

then the DLL should be installed in

PIHOME\interfaces\opcint\plug-ins

Installation Procedures

Although the OPCPluginTimeArray.DLL is on the CD with the PI-OPC interface, one must configure some things before the DLL will be activated.

Modify OPCINT.BAT

The plug-in, OPCPluginTimeArray.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 two commands to the batch file, opcint.bat, which specify its location. For example:

opcint.exe /ps=O … ^

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

After adding the last line, the PI-OPC interface will automatically load the plug-in at startup, and manifest TimeArray-specific behavior. 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.

Configure PI Tags

Two factors define a tag which will use the Time Array plug-in.

Location2

In general use of the OPC interface, Location2 specifies what special handling should be done with the data, such as asking for a different data type than would normally be requested for a given tag type. For the Time Array plug-in, you should add 1024 to whatever value Location2 would already have. This allows most standard functionality of the interface to be maintained. Thus if your tag is a Float32, but your OPC server can only provide the data if you ask for it as a VT_R8 (64-bit floating point number), you would ordinarily set Location2 = 5. To do the same thing for a tag that will receive an array of time-series data, you would set Location2 = 5 + 1024 = 1029.

ExDesc

The interval between values, when the values are written to PI, must also be specified in the tag. We use ExDesc for this, and use a keyword of ARRAYINT. So, if the array of data coming from the OPC server contains values that should be stored 100 milliseconds apart, your tag should have

ARRAYINT=100

as part of the ExDesc. You can also have any of the other values you would otherwise have in ExDesc, separating them with commas as usual.

If you want to reverse the order of the data, set the ARRAYINT value to be negative.

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 PI-OPC interface 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 PI-OPC interface manual.

Uninstalling the Plug-In

If for some reason you want to run the interface without the plug-in, delete the /DLL and /DLL_ini command-line parameters from the batch file, opcint.bat, and stop and restart the PI-OPC interface according to the instructions in the PI-OPC interface manual.

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. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id flag 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 PIHOME entry is:

C:\PIPC

then the pipc.log file will be located in the c:\PIPC\dat directory.

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.

Note: No messages are written to the command window when the interface is run interactively. All messages are written to pipc.log.

Messages

Timearray: Version #.#.#

The version of the plug-in

Timearray: Debug tag TIMEARRAYDEBUG found

If a debug tag is defined, that is confirmed.

Timearray: Unable to find debug tag TIMEARRAYDEBUG, no debug tag set

No debug tag was found.

Timearray: DebugFlag #

The debug tag is greater than 0 or a debug flag on the command line is greater than 0.

TimeArray: Invalid point type 12

Timearray: Invalid array type 12

Timearray: Array has dimension > 1, skipping ArrayTag

TimeArray: Array not one-dimensional

When data arrives from the OPC interface, the dll may print error messages if it is unable to process the data :

Any of those messages indicates a serious problem with the data received from the OPC server, and you'll probably need to talk to your server vendor.

TimeArray: Invalid timestamp for tag: ArrayTag, 100479844 and 0.27

The timestamp we get from the OPC server cannot be interpreted.

TimeArray: ArrayTag: Can't translate date to seconds

The two numbers are the whole seconds of the PI timestamp, and the fractional part of a second.

This indicates that the VT_DATE value from the OPC server, and couldn't be translated into a number of seconds (this is one of the Location2 options for opcint). This indicates a serious problem with the data.

TimeArray: Unrecoverable error, data type unknown 37

Data retrieved from the OPC server, but we have no idea what it is or how to read it.

Note: For all "bad data" messages, that particular value will be dropped (or the entire array, if the timestamp itself is bad), but the interface and the DLL will continue to collect data. So the effect is that we'll drop what we can't process, after logging the error message, and go on to take care of the data that we can process.

Problem in TimeArray.dll, HRESULT = 0x80040335

This error says that we got something from the server, but we can't read any of it. This is a bad error, and it probably means that there's really serious problem with either your server or the DLL or both. Call OSI Tech Support.

Timearray: Putsnap error state changed, was #, now #, tag, pt, index, cstat

TimeArray: Putsnap no longer in error #, tag, pt, cstat

TimeArray: Putsnap system error #

These errors indicate a problem in communicating with PI (system error), or an error in writing to PI (error state changed), or recovery from an error writing to PI (no longer in error). These are just like the same error messages seen with the OPC interface. Use pidiag.exe to see what an error number means when there's an error writing to PI (pidiag.exe -e -109, for example, to see what a -109 is). Remember that once a tag goes into error, you won't see any more messages until it goes out of error, or gets a different error, so once you get an error, you won't have data going to PI for that tag until you see another message that the error has cleared.

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

Appendix A:

Debugging

The Time Array DLL has the capability to use a debug tag, and to have the value of the debug flag set on the command line. To set the value of the debug flag on the command line, you would use

/dlldebugtag=tagname

The preferred way to set the debug flag is to define an Int32 tag in PI, configure it as a simple input tag with Location2 = 1024 (so the DLL will recognize it), and put any dummy value into the InstrumentTag. Make sure that the Location1 attribute of the tag has the correct value for this interface. Then give the tagname in the command line.

Before starting the interface, set the value of the debug tag. Then to turn debugging on or off, or to change the level of debugging, change the value of the tag, and then edit the tag. When the DLL gets the tag as an edit or a new tag, it reads the value from the PI snapshot, but does not include the tag in the list of tags for the OPC server to service.

In the pipc.log file, you will see the following messages to indicate that the debug tag has been found and read:

01-Nov-01 11:58:37

Timearray: Debug tag TIMEARRAYDEBUG found

01-Nov-01 11:58:41

OPCpi> 2> Removed Tag TimeArrayDebug

01-Nov-01 11:58:41

OPCpi> 2> Developer load structure failure, TimeArrayDebug, 1177

Every time you edit the debug tag (which you will do every time you need to change the value), you will see those last two messages in the pipc.log file.

/dlldb=#

# is the number corresponding to the debug messages you want to have printed (see the table below).

Debugging Messages

The debug flag is a bit mask, so you can turn on more than one set of messages by adding the set numbers together and setting the debug flag to that value. So, to turn on messages for the array timestamps and for values that we would process but none passed the exception parameters, you would set debugging to 1 + 8 = 9 . The message sets are:

|/dlldb=# |Description |Messages |

|1 |Messages show that we got data, but none of it |Timearray: No data to send, skipping |

| |passed the exception parameters, so we didn't send |ArrayTag |

| |anything to PI for this tag. | |

|2 |Messages show values that we're not going to |Timearray: No dev struct, skipping |

| |process. The OPC interface passes all data to us |Timearray: Tag waiting for deletion, |

| |(after applying some minimal checks); we ignore |skipping ArrayTag |

| |values for tags that aren't ours and then validate |Timearray: Bad quality, skipping ArrayTag |

| |the data. If the tag has been deleted, the | |

| |interface will have set the dev struct to zero, so | |

| |we'll skip that one. If the tag has been marked for| |

| |deletion, we will just dump data, so we'll skip | |

| |those too. And finally, if the quality sent with | |

| |the array isn't GOOD, we'll skip the tag and let the| |

| |OPC interface store one status value to the tag, | |

| |showing the quality that the OPC server sent. | |

|4 |Messages show values for tags we're not supposed to |Timearray: Not an array tag, skipping |

| |process, |FloatTag |

| | |Timearray: Not our array tag, skipping |

| | |OtherArray |

|8 |Print the timestamp sent with the array. This is to|Timearray: Tag ArrayTag time |

| |verify what the OPC server is sending. |1004551257.2541676 |

|16 |Print the index and timestamp for each value sent to|Timearray: Tag ArrayTag index 67 time |

| |PI. This can be a lot of output, so use it |0:57.254180908203125 |

| |carefully. | |

Revision History

|Date |Author |Comment |

|10-Jul-02 |CG |Reformatted manual for version 1.1.2 |

| | | |

| | | |

| | | |

| | | |

| | | |

| | | |

| | | |

| | | |

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

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

Google Online Preview   Download