PI Interface for OPC XML-DA HTTP Plug-In

PI Interface for OPC XML-DA HTTP Plug-in

Version 1.5.1.x

OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web:
OSIsoftAustralia • Perth, Australia
OSIsoft Europe GmbH • Frankfurt, Germany
OSIsoft Asia Pte Ltd. • Singapore
OSIsoftCanada ULC • MontrealCalgary, Canada
OSIsoft, LLC Representative Office • Shanghai, People’s Republic of China
OSIsoftJapan KK • Tokyo, Japan
OSIsoftMexico S. De R.L. De C.V. • Mexico City, Mexico
OSIsoft do BrasilSistemas Ltda. • Sao Paulo, Brazil
PI Interface for OPC XML-DA HTTP Plug-in
Copyright: © 2002-2013OSIsoft, 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: 01/2013

Table of Contents

Chapter 1.Introduction

Reference Manuals

Plug-in Specific Features

Exception Reporting

Source of Timestamps

Output Points

Chapter 2.Principles of Operation

Chapter 3.Installation Checklist

Chapter 4.Plug-in Installation and Administration

Locating Plug-in Directory

Modifying PIXML.BAT

Configuring PI Tags

Upgrading Plug-in

Uninstalling Plug-In

Chapter 5.Startup Command File

Configuring the Interface with PI ICU

HTTP Plug-In

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

Appendix C.Terminology

Appendix D.Technical Support and Resources

Before You Call or Write for Help

Help Desk and Telephone Support

Search Support

Email-based Technical Support

Online Technical Support

Remote Access

On-site Service

Knowledge Center

Upgrades

OSIsoft Virtual Campus (vCampus)

Appendix E.Revision History

PI Interface for OPC XML-DA HTTP Plug-in1

Chapter 1.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.

Note: The value of [PIHOME] variable for the 32-bit interface will depend on whether the interface is being installed on a 32-bit operating system (C:\ProgramFiles\PIPC) or a 64bit operating system (C:\ProgramFiles(x86)\PIPC).

The value of [PIHOME64] variable for a 64-bit interface will be C:\ProgramFiles\PIPC on the 64-bit operating system.

In this documentation [PIHOME] will be used to represent the value for either [PIHOME] or [PIHOME64]. The value of [PIHOME] is the directory which is the common location for PI client applications.

Note:Throughout this manual there are references to where messages are written by the interface which is the PIPC.log. This interface has been built against a UniInt version (4.5.0.59 and later) which now writes all its messages to the local PI Message log.

Please note that any place in this manual where it references PIPC.log should now refer to the local PI message log. Please see the document UniInt Interface Message Logging.docx in the %PIHOME%\Interfaces\UniInt directory for more details on how to access these messages.

Reference Manuals

OSIsoft

PI Server manuals
PI API Installation Instructionsmanual
UniInt Interface User Manual
XML Interface to the PI System

Vendor

Extensible Markup Language (XML) 1.0 (Second Edition)
OPC XML-DA specification (version 1.01)

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.

The /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.

PI Interface for OPC XML-DA HTTP Plug-in1

Chapter 2.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="

</Items>

</Items>

</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 with 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.

PI Interface for OPC XML-DA HTTP Plug-in1

Chapter 3.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 the following:

/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.

Therefore, 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.

PI Interface for OPC XML-DA HTTP Plug-in1

Chapter 4.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 this folder

[PIHOME]\Interfaces\XML

then the DLL should be present in the corresponding plug-in folder in

[PIHOME]\Interfaces\XML\Plug-ins\http

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

Modifying PIXML.BAT

To activate the DLL, use the XML ICU ICU Control to select this Plug-In which will add the DLL for the following command-line option to the PI XML interface startup file, pixml.bat, and specify the location of the DLLFor 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 be 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 user manual. However, when using the HTTP Plug-in DLL, there are a few notable differences that should be followed. First, 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 user manual.

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 user manual. 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.

PI Interface for OPC XML-DA HTTP Plug-in1

Chapter 5.Startup Command File

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

-ps=M command-line parameters are equivalent.

For Windows, command file names have a .bat extension. The Windows continuation character (^) allows for the use of 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.

The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the interface startup command file.

Configuring the Interface 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. 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 and the module database. The procedure below describes the necessary steps for using PI ICU to configure the PI XMLinterface.

When using the XML ICU control with the HTTP plug-in, it is necessary to choose the appropriate plug-in DLL. To do this select the PIXML_http.dll in the Configuration tab of the XML ICU control as shown below.

After this is done, the HTTP Plug-In tab should appear, and the following options will be 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. Use the browse button 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 described in section Principles of Operation. (/dbdll=4)

Command-line Parameters

Plug-in Specific Parameters

Parameter / Description
/dbdll=flag
Optional / Used to print plug-in-level debug messages. See Appendix B for more information.
/dll=path\filename
Required / Specifies the path and file name 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 / Specifies where the URL to for 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 path and 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 the # is not specified, then the default event counter is 1. Also, if the /ecparameter 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 either explicitly defining an event counter other than 1 for each copy of the interface or not associating any I/O Rate points with event counter 1.