File Reader Plug-in DLL
for XML
Interface to the PI System

Version 1.2.1.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.
© 2002-2007 OSIsoft, Inc.PI_XML_FileReader_Plug-in.doc

Table of Contents

Introduction

Reference Manuals

Plug-in Specific Features

Principles of Operation

Installation Checklist

Plug-in Installation and Administration

Locating Plug-in Directory

Configuring PI Tags

Upgrading Plug-in

Uninstalling Plug-in

Startup Command File

Configuring the Plug-in with PI ICU

Command-line Parameters

Plug-in Specific Parameters

General PI XML Interface Parameters

Sample PIXML.bat File

Appendix A: Error and Informational Messages

Message Logs

System Errors and PI Errors

Appendix B: Debugging

Revision History

1

File Reader Plug-in for XML Interface to the PI System1

Introduction

The PI XML interface is able to read XML data that conforms to the OPC XML-DA specification that is transported using the SOAP protocol. In order to handle other XML schemas and transport mechanisms, the PI XML interface was designed to allow for the development of custom plug-in DLLs. To obtain XML data that exists as XML files, OSIsoft created the File Reader plug-in DLL, which can process XML documents that exist locally on the hard drive. In addition, the File Reader plug-in DLL can do XSL transformations after reading the XML documents. Therefore, it is possible to use XML documents that do not conform to the OPC XML-DA schema, provided an XSLT document is written that does appropriate transformations (i.e. that transforms the source XML into an XML document that is compliant to the OPC XML-DA schema). This plug-in is in a file called PIXML_FileReader.DLL.

Note: Neither this manual nor the plug-in are stand-alone products; they are to be used in conjunction with the PI XML interface. This version of the plug-in requires 1.1.0.0 or above versions of the PI XML Interface.

Reference Manuals

OSIsoft
  • PI Server manuals
  • PI-API manual
  • PI XML Interface to the PI System
Vendor
  • Extensible Markup Language (XML) 1.0 (Second Edition)
  • OPC XML-DA specification (version 1.0)

Plug-in Specific Features

Several features of this product are unique to this plug-in. These features are detailed below.

Exception Reporting

It is not possible to request that exception reporting be performed by the XML server through the use of the /sn command-line option when using the File Reader plug-in, because the data is independently written to the files.

If the /sn command-line option is specified, the PI XML interface will not do any exception reporting.

The /returnallitems command-line option, which typically can be used to force the XML server to return data after each scan, has no effect when this plug-in is being used.

Source of Timestamps

When the File Reader plug-in is being used, the timestamps must be specified in the XML files being read. However, the interface can ignore these timestamps if the /TS command-line option is specified, in which case the local timestamps will be used. For timestamps supplied in the XML files, the interface calculates the offset between the PI server and the local time on the machine where the XML files are being read and applies that correction to the timestamps received in the XML files.

Output Points

The File Reader plug-in supports output points. Data from PI output points will be written to a file corresponding to the WriteResponse extract of the OPC XML DA specification. The file is written to the path that is specified with the /output=path command-line option and the filename will correspond to the timestamp of the output in order to guarantee uniqueness. If no path is specified, the plug-in will use the directory where the interface executable is found. In addition, the /xslout=path command-line option can be used to transform the output so that it conforms to any schema.

1

File Reader Plug-in for XML Interface to the PI System1

Principles of Operation

The File Reader plug-in essentially provides a mechanism to read raw XML files, including XML files that are not compliant to the OPC XML DA schema. The plug-in forces the PI XML Interface to read files from a directory that is specified in the /server command-line option. The oldest file in the directory will be read during each scan and after the data is read, the file is renamed with a .old extension. By default, only files with an .xml extension will be read, although it is possible to override this through the use of the /mask command-line option. After reading the raw XML, it is possible to do an XSL transformation by specifying the path to an XSLT file through the use of the /xsl command-line option. The transformed XML is then passed on to the interface and it must be compliant with the OPC XML DA schema. A diagram outlining this process is shown below:

Output points can also be configured to write data to XML files in a directory that is specified by the /output command-line option. The output files conform to the WriteResponse extract of the OPC XML-DA schema.

The format of the transformed XML files should conform to the ReadResponse extract of the OPC XML-DA schema, which is listed below.

<?xml version="1.0"?>

<ReadResponse xmlns="

<RItemList>

<Items ItemName="file/testA" Timestamp="2004-06-20T06:16:31.6718750-07:00">

<Value>14.467</Value>

</Items>

<Items ItemName="file/testB" Timestamp="2004-06-20T06:16:31.6718750-07:00">

<Value>15.467</Value>

</Items>

<Items ItemName="file/testA" Timestamp="2004-06-21T06:16:31.6718750-07:00">

<Value>17.467</Value>

</Items>

<Items ItemName="file/testC" Timestamp="2004-06-20T06:16:31.6718750-07:00">

<Value>16.467</Value>

</Items>

</RItemList>

</ReadResponse>

A more detailed description, including the schema definition, can be found at If XSLT files are being used to transform the raw XML, it is highly recommended that the transformation be tested and validated before using with the File Reader plug-in.

The format of the transformed XML is fairly straightforward. Each item below the RItemList node corresponds to one data value. It is necessary to specify the ItemName attribute which should match to the InstrumentTag attribute of the corresponding PI tag. The Timestamp attribute is specified in the ISO8601 timestamp format. Note that multiple values for the same ItemName can be specified as long as a separate Items node is defined. In the above example, it can be seen that two values are specified for the “file/testA” ItemName. When multiple values are specified for the same ItemName, they should appear in chronological order to improve performance, although it is not necessary to group the nodes together. If multiple values are being sent, the Location3 field for the tag in question should be set to 0.

When using the File Reader plug-in, there should only be one scan class defined in the interface startup file. Moreover, it is necessary to configure all tags to use only one scan class. The interval of this scan class will define how often the plug-in polls the directory. After the file is read, the plug-in will compare the InstrumentTag fields for all the tags in the scan class to each ItemName attribute for all Items nodes in the transformed XML and will discard any Items nodes which have ItemName attributes that do not have a corresponding match. Further internal processing of the transformed XML will occur in order to conform to the SubscribeResponse and the SubscribePolledRefreshResponse extracts of the OPC XML-DA schema.

Note: XML is case sensitive, so make sure your element names have the correct case. For example, RItemListworks while ritemlist will fail.

1

File Reader Plug-in for XML Interface to the PI System1

Installation Checklist

For those users who are familiar with running PI XML interface with the File Reader Plug-in DLL, this checklist helps you get the PI XML interface running. If you are not familiar with the File Reader Plug-in DLL for the PI XML Interface, you should return to this section after reading the rest of the manual in detail.

  1. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)
  2. Verify that PI-API and PI-SDK have been installed.
  3. Install the PI XML interface.
  4. Configure the PI XML Interface using the PI-Interface Configuration Utility, which is the recommended way to configure the interface. The only interface-specific, required parameters are:
    /server=URL defines the connection.
    /xsl=path defines the XSLT file to read to do transformations.
    /output=path defines the location where outputs should be written.
    /dll=path defines the location of the plug-in DLL.
  5. Configure PI points.
    Location1 is the interface instance.
    Location2 specifies whether the tag is an input (0) or output (1) tag.
    Location3 is the buffering setting. If multiple values are being sent, this value should be 0.
    Location4 is the scan class and only one scan class should be used. Hence, this should equal 1 for all input points.
    Location5 is not used.
    ExDesc is not used.
    InstrumentTag is the item name.
  6. Start the interface without buffering.
  7. Verify data.
  8. Stop interface, start buffering, start interface.

1

File Reader Plug-in for XML Interface to the PI System1

Plug-in Installation and Administration

Locating Plug-in Directory

The PIXML_FileReader.dll is installed in the PI XML interface directory in the File Reader plug-ins sub-directory. For instance if the interface is installed in

PIHOME\Interfaces\XML

then the DLL should be present in the corresponding plug-in directory in:

PIHOME\Interfaces\XML\Plug-ins\File Reader

The other plug-in DLLs are installed in their own separate sub-directories.

Configuring PI Tags

A detailed description for configuring tags can be found in the XML Interface to the PI Systemmanual. However, when using the File Reader Plug-in DLL, there are a few notable differences that should be adhered to.

  • All tags MUST have Location4=1 to be in the only scan class.
  • All tags should support buffering by setting Location3= 0.
  • The InstrumentTag attribute should correspond to the ItemName attribute for the appropriate Items node in the transformed XML.

Upgrading Plug-in

If the plug-in is upgraded independent of the PI XML interface, it will be necessary to stop the PI XML interface, install the plug-in in the appropriate directory and then restart the interface according to the instructions in the XML Interface to the PI Systemmanual.

Uninstalling Plug-in

In order to run the interface without this plug-in, use the PI ICU program to change the plug-in DLL to use. Or, alternately, delete the /DLL command-line parameter from the batch file, pixml.bat. Doing so will cause the PI XML Interface to use the PIXML_OPC.dll instead. Stop and restart the interface according to the instructions in the XML Interface to the PI Systemmanual. Note that if the File Reader plug-in is not used, the operation of the XML interface will change drastically depending on the new Plug-in DLL that is selected.

1

File Reader Plug-in for XML Interface to the PI System1

Startup Command File

Configuring the Plug-in with PI ICU

Note:PI ICU requires PI 3.3 or greater.

The PI Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. By configuring the interface with PI ICU, the user makes it possible to recognize the interface, edit configurations, run and stop the interface. If the interface is configured by the PI ICU, the batch file of the interface (pixml.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file. The procedure describing the necessary steps for using PI ICU to configure the PI XML Interface is described in XML Interface to the PI Systemmanual.

Configuration Tab

XML Server:

Enter the path to the files that the interface will process. (/server)

Pre-Processing DLL:

Select the path and name of the PIXML_FileReader.dll from the drop-down list. (/dll)

File Reader Plug-in Tab

Once the plug-in path and name has been selected, the File Reader Plug-In tab should appear and the following options will be available for selection.

Purge timelimit for *.OLD files:

Any *.old files older than the time specified in the text box are deleted on each scan. The format of the time string should be a number followed by a one-digit letter, which can be either h for hours, m for minutes, s for seconds, or d for days. For example, all files that are older than 2 days would be deleted if 2dwas used (/purge=2d).

FileName Mask:

Specify the mask to be used when reading files from the directory location specified in the XML Server field on the Configuration tab. For example, in order to read all files with .XMLas the filename extension, enter*.XMLin this field. (/mask)

XSLT Trans. Filespec (.xsl):

Enter the path and filename for the XSLT file that is used to transform the raw XML into OPC XML-DA compliant XML for the interface to read. The browse button can be used to locate the XSLT file. (/xsl=path\filename)

XSLT Output Trans. Filespec:

Specify the path and filename of the XSLT file that is used to transform output data from OPC XML-DA compliant XML format into any XML format. If this parameter is not specified, no XSLT transformation will be performed. The browse button can be used to locate the XSLT file. (/xslout=path\filename)

XSLT Output File Path:

Specify the path where the output files should be written. This parameter is used in conjunction with output points. The browse button can be used to locate the folder. (/output=path)

XML Schema Filespec (.xsd):

This specifies the path and filename of the schema file that is used to validate the XML format read from the files. If this argument is not specified, no validation will be performed. The browse button can be used to locate the XML schema file. (/xsd=path\filename)

Debug Settings -- Log message when XML files are found:

Selecting this check-box will cause messages to be written to the pipc.log file when XML files are found. (/dbdll=1)

Debug Settings -- Write content of XSLT file during initialization:

Selecting this check-box will force the File Reader plug-in to send the entire contents of the XSLT file being read during initialization of the DLL to the pipc.log file. Long XSLT files could be truncated. (/dbdll=2)

Debug Settings -- Log XML being read after being transformed:

Selecting this check-box will cause the File Reader plug-in to log the XML being read from input files after being transformed with an XSLT file, which can be helpful in creating and debugging XSLT files for input. The XML that is written to the pipc.log file should conform to the ReadResponse extract of the OPC XML-DA schema as discussed in the “Principles of Operation” section. (/dbdll=4)

Command-line Parameters

Command-line parameters can begin with a / or with a -. For example, the /ps=M and
–ps=M command-line parameters are equivalent.

For NT, command file names have a .bat extension. The NT continuation character (^) allows one to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters.

Not all the options available to the PI XML interface are used and only the ones listed below are relevant when using this plug-in.

Note:The UniInt Interface User Manual includes details about other command-line parameters, which may be useful.

Plug-in Specific Parameters

Parameter / Description
/dbdll=flag
Optional
Default: No plug-in debugging / Debugging flag used to print plug-in-level debug messages. See Appendix B for more information.
/dll=path\filename
Optional
Default: ==> / This specifies the path and filename for the plug-in DLL and should point to the File Reader plug-in. The default for this location is:
<interface directory>\Plug-ins\File Reader\PIXML_FileReader.dll
/ignore_offset
Optional
Default: Use time offsets / This option will force the interface to ignore any offsets between the PI home node and the interface node.
/mask=file.ext