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

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

Version 2.2.3.0

Rev B

How to Contact Us

OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA94577USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)

Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors

• Brazil
• Middle East/North Africa
• Republic of South Africa
• Russia/Central Asia

/

• South America/Caribbean
• Southeast Asia
• South Korea
• Taiwan

OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s products or any affiliation with such party of any kind.
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
Unpublished – rights reserved under the copyright laws of the United States.
© 2001-2006 OSIsoft, Inc. PI_OPCPluginTimeArray.doc

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. This version of the plug-in requires 2.1.45 or above versions of 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 get the PI OPC Interface up and running with the OPCPluginMetso.DLL. If not familiar with the plug-in, return to this section after reading the rest of this manual in detail.

Follow the steps in the order listed below.

1. Install the PI ICU which will install the PI SDK and PI API
2. Install PI OPC Interface.
3. Define digital states
4. Use the PI ICU to configure the OPC interface and use the Plug-Ins configuration to add the support for the OPCPluginTimeArray.dll or modify OPCINT.BAT to activate the DLL.
5. Configure PI tags.
6. 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 installed as part of the PI OPC Interface installation into the Plug-in subdirectory. For instance, if the interface is installed in

D:\pipc\Interfaces\OPCInt

then the DLL will be installed in

D:\pipc\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

OSIsoft recommends using the PI Interface Configuration Utility for making changes to the interface batch file. Under the opcint tab there is a Plug-Ins item that is used to configure the DLL which an instance of the OPCInt interface will use. This will add the /DLL= command line parameter to the batch file.

For Example”

/DLL=C:\PIPC\Interfaces\OPCInt\Plug-Ins\OPCPluginTimeArray.DLL

Once this has been added to the batch file either manually or by using the PI ICU the PI OPC interface will automatically load the plug-in at startup. If the interface is already running, the interface must be restarted 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.

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

/DLL=”C:\PIPC\Interfaces\OPCInt\Plug-Ins\OPCPluginTimeArray.DLL”

Configure PI Tags

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

Location2

In general use of the OPC interface, the Location2 tag attribute 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, add 1024 to whatever value Location2 would already have. This allows most standard functionality of the interface to be maintained. Thus if the tag is a Float32, but the OPC server can only provide the data if it as a VT_R8 (64-bit floating point number), Location2 would ordinarily be set to 5. To do the same thing for a tag that will receive an array of time-series data, set Location2 = 5 + 1024 = 1029.

ExDesc

When the values are written to PI, the interval between values must also be specified in the tag. The keyword of ARRAYINTshould be specified in theExDesc tag attribute. So, if the array of data coming from the OPC server contains values that should be stored 100 milliseconds apart, specify
ARRAYINT=100
as part of the ExDesc. Any of the other values normally found in the ExDesc attribute may also be used.These values should be separated by a comma.

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. Opcint.batmust be updated to reflect the name of the new directory and the interface must be restarted as described in the PI OPC Interface manual.

Uninstalling the Plug-In

To run the interface without the plug-in, run the PI ICU and remove the entry in the Post Processing DLL text box or delete the /DLL= command-line parameter from the batch file, then stop and restart the PI OPC interface according to the instructions in the OPC Interface to the PI System 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 %windir%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. Talk to the OPC server vendor for more information.

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 was retrieved from the OPC server, but it is unknown, or unreadable.

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 data is dropped if it can not be processed after logging the error message. The interface then goes on to take care of the data that it can process.

Problem in TimeArray.dll, HRESULT = 0x80040335

This error says that the interface got something from the server, but it can't read any of it. This is a bad error, and it probably means that there's really serious problem with either the OPC server or the DLL or both. Call OSIsoft 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, no further messages will appear until it goes out of error, or gets a different error.Once an error is encountered, no data will go to PI for that tag until another message appears 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 Windows

On Windows, 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, 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, the following messages are displayed 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 the debug tag is edited (which will happen every time the debug value is changed), those last two messages will appear in the pipc.log file.

/dlldb=#

# is the number corresponding to the debug messages to print (see the table below).

Debugging Messages

The debug flag is a bitmask, so more than one set of messages can be turned on 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, set debugging to 1 + 8 = 9 . The message sets are:

/dlldb=# / Description / Messages
1 / Messages show that data was received, but none of it passed the exception parameters, so nothing was sent to PI for this tag. / Timearray: No data to send, skipping ArrayTag
2 / Messages show values that won’t be processed. The PI OPC Interface passes all data (after applying some minimal checks); values for tags that don’t belong to the interface are ignored and then the datais validated. If the tag has been deleted, the interface will have set the dev struct to zero, so that will be skipped. If the tag has been marked for deletion, the data will be dumped, and that tag will be skipped as well. Finally, if the quality sent with the array isn't GOOD, the tag will be skipped and the OPC interface will 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 that shouldn’t be processed. / 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 / CGoodell / Reformatted manual for version 1.1.2
2-Nov-05 / Janelle / Version 1.2.0.0 Rev A: fixed headers and footers, fixed copyright, made final
24-Mar-06 / Janelle / Version 2.2.3.0 Rev A: fixed headers and footers, applied latest template, removed first person references, updated How to Contact Us page.
28-Mar-06 / MKelly / Version 2.2.3.0 Rev B: fixed the configuration section using the PI ICU to configure the dll as part of the interface.

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