HTTP Plug-In DLL for XML Interface

HTTP Plug-in DLL for XML Interface

Version 1.4.1.0
RevisionA

OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web:
OSIsoft Australia • Perth, Australia
OSIsoft Europe GmbH • Frankfurt, Germany
OSIsoft Asia Pte Ltd. • Singapore
OSIsoft Canada ULC • MontrealCalgary, 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
HTTP Plug-in DLL for XML Interface
Copyright: © 2002-2018 OSIsoft, LLC. 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,PI Asset Framework(PI-AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, 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.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Published: 09/2010

Table of Contents

Introduction

Reference Manuals

Plug-in Specific Features

Principles of Operation

Installation Checklist

Plug-in Installation and Administration

Locating Plug-in Directory

Modifying PIXML.BAT

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

HTTP Plug-in DLL for XML Interface1

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 over the HTTP protocol, OSIsoft created the HTTP plug-in DLL, which can process XML documents that exist on a web server. In addition, the HTTP 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_http.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
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 HTTP plug-in.

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

Finally, /returnallitems command-line option that 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

If the HTTP plug-in is being used, the timestamps can be specified in the XML. However, the interface can ignore these timestamps if the /TS command-line option is specified, and instead, local timestamps will be used. For timestamps supplied in the XML, the interface calculates the offset between the PI server and the local time on the machine where the interface is being run from and applies that correction to the timestamps received from the XML server.

Output Points

The HTTP plug-in does not support outpoint points.

HTTP Plug-in DLL for XML Interface1

Principles of Operation

The HTTP plug-in provides a mechanism to read non-OPC XML DA compliant data from URLs using the HTTP transport protocol. The plug-in forces the PI XML interface to read one file from a URL that is specified through the /server 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:

The format of the transformed XML should conform to the ReadResponse extract of the OPC XML-DA schema. A sample of this format is listed below, but 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 is tested and validated before using with the HTTP plug-in.

<?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">

</Items>

</Items>

</RItemList>

</ReadResponse>

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 field 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, then the Location3 field for the tag in question should be set to 0.

The interval of this scan class will define how often the plug-in polls the URL. After the XML is retrieved, 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.

HTTP Plug-in DLL for XML Interface1

Installation Checklist

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

Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)
Verify that PI-API and PI-SDK have been installed.
Install the PI XML interface.
Modify the PIXML.BAT file to activate the DLL or edit the startup command file using the PI-ICU. The only interface-specific required parameters are:
/server=URL defines the connection.
/xsl=path defines the XSLT file to read to do transformations.
/dll=path defines the location on the plug-in DLL.
Configure PI points.
Location1 is the interface instance.
Location2 is specified whether the tag is an input or output tag.
Location3 is the buffering flag. 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.
Start the interface without buffering.
Verify data.
Stop interface, start buffering, start interface.

HTTP Plug-in DLL for XML Interface1

Plug-in Installation and Administration

Locating Plug-in Directory

The PIXML_http.dll is installed in the PI XML interface directory in the 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\http

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

Modifying PIXML.BAT

To activate the DLL, it is necessary to add the following command-line option to the PI XML interface startup file, pixml.bat, to specify the location of the DLL. For example:

/DLL=”c:\PIPC\Interfaces\XML\Plug-ins\http\PIXML_http.dll”

If the pathname contains spaces, the whole parameter must be surrounded by double quotes. In addition, the /server option should modified to point to a web server from which the XML will be read. In addition, if an XSLT file is being used to transform the XML then it is necessary to use the /xsl option to point to the location of the XSLT file.

Configuring PI Tags

A detailed description for configuring tags can be found in the XML Interface to the PI Systemmanual. However, when using the HTTP Plug-in DLL, there are a few notable differences that should be adhered to. Firstly, it is recommended that all tags support buffering by setting Location3 equal to 0. Additionally, the InstrumentTag field should correspond to 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

To run the interface without the plug-in, the default plug-in, PIXML_OPC.dll should be selected using the XML ICU control. If the ICU control is not being used, it will be necessary to delete the /DLL command-line parameter from the batch file, pixml.bat, and stop and restart the interface according to the instructions in the XML Interface to the PI Systemmanual. Note that if the HTTP plug-in is not used, the operation of the XML interface will change drastically depending on new DLL that is selected.

HTTP Plug-in DLL for XML Interface1

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.

When using the XML ICU control with the HTTP plug-in, it is necessary to choose the appropriate plug-in DLL. This is done by selecting the PIXML_http.dll in the Configuration tab of the XML ICU control as shown below.

Once this is complete, the HTTP Plug-In tab should appear, and the following options will available for selection.

HTTP Plug-in

Username

Choose a user for authentication. (/user)

Password

Supply a password associated with the user for authentication. (/password)

XSLT Trans. Filespec (.xsl)

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

XML Schema Filespec (.xsd)

This specifies the path and filename of the schema file that is used to validate the XML that is 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)

Log message when XML files are found

This setting will cause messages to be written to the pipc.log file when XML files are found. (/dbdll=1)

Write content of XSLT file during initialization

This setting will force the HTTP plug-in to output 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)

Log XML being read after being transformed

This setting will cause the HTTP 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 inputs. 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 arguments can begin with a / or with a -. For example, the /ps=M and
–ps=M command-line arguments are equivalent.

For Windows, command file names have a .bat extension. The Windows 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 flags is unlimited, and the maximum length of each flag 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 End User Document includes details about other command-line parameters, which may be useful.

Plug-in Specific Parameters

Parameter / Description
/dbdll=flag
Optional / Debugging flag used to print plug-in-level debug messages. See Appendix B for more information.
/dll=path\filename
Required / This specifies the path and filename for the plug-in DLL and should point to the HTTP plug-in. The default for this location is:
<interface directory>\Plug-Ins\http\PIXML_http.dll
/password=<pwd>
Optional / Specifies the password to be used if the web server hosting the XML supports authentication.
/server=path
Required / The parameter tells the interface the URL to where one XML file exists. For example, the path could be specified as:

For other plug-in DLLs, this option could be used differently and the corresponding plug-in manual should be consulted.
/user=<username>
Optional / Specifies the user to be used if the web server hosting the XML supports authentication.
/xsl=path\filename
Optional / Specifies the path and filename for the XSLT file that is used to transform the raw XML into OPC XML-DA compliant XML. If this argument is not specified then no XSLT transformation will be done.
/xsd=path\filename
Optional / Specifies the pathand filename for the XML schema file that is used to validate the XML that is read from the files. If this argument is not specified then no validation will be done.

General PI-XML Interface Parameters

Parameter / Description
/ec=#
Optional / The first instance of the /ec parameter on the command line is used to specify a counter number, #, for an I/O Rate point. If # is not specified, then the default event counter is 1. Also, if the /ec parameter is not specified at all, there is still a default event counter of 1 associated with the interface. If there is an I/O Rate point that is associated with an event counter of 1, each copy of the interface that is running without /ec=# explicitly defined will write to the same I/O Rate point. This means that one should either explicitly define an event counter other than 1 for each copy of the interface or one should not associate any I/O Rate points with event counter 1. Configuration of I/O Rate points is discussed in the section called “I/O Rate Tag Configuration.”
For interfaces that run on Windows nodes, subsequent instances of the /ecparameter may be used by specific interfaces to keep track of various input or output operations. One must consult the interface-specific documentation to see whether subsequent instances of the /ec parameter have any effect. Subsequent instances of the/ecparameter can be of the form /ec*, where * is any ASCII character sequence. For example, /ecinput=10, /ecoutput=11, and /ec=12 are legitimate choices for the second, third, and fourth event counter strings.
/f=SS
or
/f=SS,SS
or
/f=HH:MM:SS
or
/f=HH:MM:SS,hh:mm:ss
Required / Note that for the File Reader Plug-In DLL, it is required that only ONE scan class be defined.
The /f parameter defines the time period between scans in terms of hours (HH), minutes (MM), and seconds (SS). The scans can be scheduled to occur at discrete moments in time with an optional time offset specified in terms of hours (hh), minutes (mm), and seconds (ss). If HH and MM are omitted, then the time period that is specified is assumed to be in seconds.
Each instance of the /f parameter on the command line defines a scan class for the interface. There is no limit to the number of scan classes that can be defined. The first occurrence of the /f parameter on the command line defines the first scan class of the interface; the second occurrence defines the second scan class, and so on. PI Points are associated with a particular scan class via the Location4 PI Point attribute. For example, all PI Points that have Location4 set to 1 will receive input values at the frequency defined by the first scan class. Similarly, all points that have Location4 set to 2 will receive input values at the frequency specified by the second scan class, and so on.