Time Array Plug-In
for the PI Interface for OPC DA
Version 2.4.4.x
Copyright © 2001-2013, OSIsoft, LLC
OSIsoft, LLC777 Davis St., Suite 250
San Leandro, CA94577USA
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
Houston, TX
Johnson City, TN
Longview, TX
Mayfield Heights, OH
Philadelphia, PA
Phoenix, AZ
Savannah, GA
Yardley, PA
/ OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSIsoft Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
Calgary, Canada
OSIsoft, LLC 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
OSIsoft do Brasil Sistemas Ltda.
Sao Paulo, Brazil
Sales Outlets/Distributors
Middle East/North Africa
Republic of South Africa
Russia/Central Asia / South America/Caribbean
Southeast Asia
South KoreaTaiwan
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, LLC.
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, LLC. 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
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
Command Line Parameters......
Error and Informational Messages
Message Logs
Messages
System Errors and PI Errors
Appendix A: DLL Debugging Options
DLLDebugTag=tagname
DLLDB=#
Debugging Messages
Revision History
Time Array Plug-In for the PI Interface for OPC DA1
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.
- PI Interface for OPC DA Version 2.4.4.0 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 Interface for OPC DA. This version of the plug-in requires 2.4.4.0 or above versions of the OPC DA interface.
Time Array Plug-In for the PI Interface for OPC DA1
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 PI Interface for OPC DA 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 the PI Interface for OPC DA1
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps get the OPC DA interface up and running with the OPCPlugInTimeArray.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.
- Install the PI ICU which will install the PI SDK and PI API
- Install the PI Interface for OPC DA.
- Define digital states
- Use the PI ICU to configure the OPC DA interface and use the Plug-Ins configuration to add the support for the OPCPlugInTimeArray.dll or modify OPCInt.bat to activate the DLL.
- Configure PI tags.
- Start the interface.
Time Array Plug-In for the PI Interface for OPC DA1
Plug-In Installation and Administration
Plug-In Directory
The OPCPlugInTimeArray.DLL is installed as part of the OPC DA 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 OPC DA 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 OPC DA 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 DA 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 OPC DA interface, install the plug-in in the appropriate directory. Then stop and restart the OPC DA interface according to the instructions in the PI Interface for OPC DAmanual.
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 Interface for OPC DA 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 OPC DA interface according to the instructions in the PI Interface for OPC DA manual.
Time Array Plug-In for the PI Interface for OPC DA1
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.
DLL specific parameters:
Parameter / Description/DLLDB=#
(Default: 0)
Optional / Debug level (1-31). See Appendix A: DLL Debugging Optionssection for more details.
/DLLDebugTag=<tagname
Optional / Debug Level setting with a <tagname> value. This parameter allows the user to turn on or off debugging and set the level of debugging at runtime by changing the value of the <tagname>. See the Appendix A: DLL Debugging Options section for more details.
Time Array Plug-In for the PI Interface for OPC DA1
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 DA 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 DA 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 the PI Interface for OPC DA1
Appendix A: DLL Debugging Options
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 / Messages1 / 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 OPC DA interface passes all data (after applying some minimal checks); values for tags that don’t belong to the interface are ignored and then the data is 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 DA interfacewill 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 the PI Interface for OPC DA1