Time Array Plug-In
for OPC
Interface to the PI System

Version 1.1.2

OSI Software, Inc

How to Contact Us

Phone / (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web /
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
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. HPUX 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

OSI Software, Inc

Table of Contents

Introduction

Principles of Operation

Installation Checklist

Plug-In Installation and Administration

Plug-In Directory

Installation Procedures

Modify OPCINT.BAT

Configure PI Tags

Upgrading the Plug-In

Moving the Plug-In to a New Directory

Uninstalling the Plug-In

Error and Informational Messages

Message Logs

Messages

System Errors and PI Errors

Appendix A: Debugging

/dlldebugtag=tagname

/dlldb=#

Debugging Messages

Revision History

Time Array Plug-In for OPC Interface to the PI System1

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.

Time Array Plug-In for OPC Interface to the PI System1

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.

Time Array Plug-In for OPC Interface to the PI System1

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.

Time Array Plug-In for OPC Interface to the PI System1

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 datatype than would normally be requested for a given tag type. For the TimeArray 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.

Time Array Plug-In for OPC Interface to the PI System1

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. IDis a configurable identifier that is no longer than 9 characters and is specified using the /idflag 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 PIHOMEentry is:

C:\PIPC

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

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

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

Time Array Plug-In for OPC Interface to the PI System1

Appendix A: Debugging

The TimeArray 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 bitmask, 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 passed the exception parameters, so we didn't send anything to PI for this tag. / Timearray: No data to send, skipping ArrayTag
2 / Messages show values that we're not going to process. The OPC interface passes all data to us (after applying some minimal checks); we ignore values for tags that aren't ours and then validate 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. / Timearray: No dev struct, skipping
Timearray: Tag waiting for deletion, skipping ArrayTag
Timearray: Bad quality, skipping ArrayTag
4 / Messages show values for tags we're not supposed to process, / Timearray: Not an array tag, skipping FloatTag
Timearray: Not our array tag, skipping OtherArray
8 / Print the timestamp sent with the array. This is to verify what the OPC server is sending. / Timearray: Tag ArrayTag time 1004551257.2541676
16 / Print the index and timestamp for each value sent to PI. This can be a lot of output, so use it carefully. / Timearray: Tag ArrayTag index 67 time 0:57.254180908203125

Time Array Plug-In for OPC Interface to the PI System1

Revision History

Date / Author / Comment
10-Jul-02 / CG / Reformatted manual for version 1.1.2

Time Array Plug-In for OPC Interface to the PI System1