XML Interface to the PI System

XML
Interface to the PI System

Version 1.1.0.0
Rev B

UniInt End-User Interface to the PI System

How to Contact Us

Phone / (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web /
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Ltd
P O Box 8256
Symonds Street
Auckland 1035 New Zealand
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721

Unpublished – rights reserved under the copyright laws of the United States.
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

Trademark statement—PI is a registered trademark of OSIsoft, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HPUX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PI_XML.doc

2004-2005 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577

UniInt End-User Interface to the PI System

Table of Contents

Introduction

Reference Manuals

Supported Features

Diagram of Hardware Connection

Principles of Operation

Installation Checklist

Interface Installation

Naming Conventions and Requirements

Interface Directories

The PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing the Interface as an NT Service

Installing the Interface Service with PI-Interface Configuration Utility

Installing the Interface Service Manually

PI-XMLTool

Digital States

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Scan

Exception Processing

Shutdown

Output Points

Trigger Method 1 (Recommended)

Trigger Method 2

Performance Point Configuration

Configuring Performance Points with PI-ICU (NT-Intel)

Configuring Performance Points Manually

I/O Rate Tag Configuration

Monitoring I/O Rates on the Interface Node

Configuring I/O Rate Tags with PI-ICU (NT-Intel)

Configuring I/O Rate Tags Manually

Configuring the PI Point on the PI Server

Configuration on the Interface Node

Startup Command File

Configuring the Interface with PI-ICU

XML Interface Tab

Command-line Parameters

Sample PIXML.bat File

Interface Node Clock

Security

Starting / Stopping the Interface

Starting Interface as a Service

Stopping Interface Running as a Service

Buffering

Configuring Buffering with PI-ICU (NT-Intel)

Configuring Buffering Manually

Example piclient.ini File

Appendix A: Error and Informational Messages

Message Logs

Messages

System Errors and PI Errors

Appendix B: Debugging

Revision History

XML Interface to the PI System1

Introduction

The PI-XML Interface is an XML custom interface to OSIsoft’s PI system. Extensible Markup Language (XML) is a text-based markup language, derived from SGML that provides a mechanism for describing and exchanging structured information. Unlike HTML, it does not have a fixed format, but rather is an extensible language for designing customized markup languages. XML has the flexibility that allows for the development of user-defined document types, while providing a robust, non-proprietary, and verifiable file format for the storage and communication of data on or off the web.

Since data can be described by a large variety of customized XML documents, a standard specification needs to be used in order to facilitate communication to OSIsoft’s Plant Information (PI) system. The OPC (OLE for Process Control) foundation has defined an OPC XML-DA standard that adopts XML to facilitate the exchange of plant data across the internet into the enterprise domain. Previous standards defined by the OPC foundation, such as interfaces to Data Access Servers, Event Servers, etc., have communicated via Microsoft COM interfaces or through OLE Automation. The rapid adoption of previous OPC standards makes the OPC-XML-DA specification a suitable XML standard to use. However, the design of the PI-XML interface allows for the development of custom plug-in DLLs that can be used to process and transform XML documents that do not conform to the OPC XML-DA specification using various methods of transport.

Due to the variety of data sources that can be used with this interface through the use of plug-in DLLs, this document will define the data source as an “XML server” to which the interface will establish a connection.

The interface is supported on Windows NT Service Pack 3 or higher, Windows 2000, or Windows XP. It requires both the PI-API and the PI-SDK.

Reference Manuals

OSIsoft

PI Server manuals
PI-API manual
UniInt End User Document

Vendor

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

Supported Features

Feature / Support
Part Number / PI-IN-OS-XML
Platforms / NTI (4, 2000, XP)
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / Float16 / Float32 / Float64 / Int16 / Int32 / Digital / String
Sub-second Timestamps / Yes
Sub-second Scan Classes / Yes
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting* / Yes
Outputs from PI / Yes
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based
Maximum Point Count / 2000 per scan class
Uses PI-SDK / Yes
PINet to PI 3 String Support / N/A
* Source of Timestamps / XML server / PI Server
History Recovery / No
Failover / No
* UniInt-based / Yes
Vendor Software Required on PI-API / PINet Node / No
* Vendor Software Required on Foreign Device / Yes
Vendor Hardware Required / No
* Additional PI Software Included with Interface / Yes
* Device Point Types / No

* See paragraphs below for further explanation.

Exception Reporting

For the default plug-in, the PI-XML Interface handles exception reporting if the /sn command-line option is NOT specified. If it is specified, the interface will request that the XMLserver does the exception reporting by using the excdev attribute for each tag. If the excdev attribute is set to 0, then neither the interface nor the XML server will do any exception reporting. Additionally, /returnallitems can be used to force the XML server to return data after each scan. Other plug-in may exhibit different behavior and the corresponding manual should be consulted.

Source of Timestamps

The interface uses timestamps from the XML server, but if the /TS option is specified, local timestamps are used. For timestamps supplied by the XML server, the interface calculates the offset between the PI server and XML server and applies that correction to timestamps received from the XML server.

UniInt-based

UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by our developers, and is integrated into many interfaces, such as the PI-XML interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniIntsupplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

The UniInt End User Document is a supplement to this manual.

Vendor Software Required

The XML Server may run on the same system as the interface, or it may run on another system.

Additional PI Software

The PI-XMLTool is an OSIsoft product that ships with the interface and assists in configuring and troubleshooting the interface.

Diagram of Hardware Connection

Configuration 1: Preferred Configuration

This configuration allows for data buffering on the interface node.

Configuration 2: Common Configuration

This configuration allows for data buffering on the interface node.

Configuration 3: Alternate Configuration

This configuration is possible, but not the preferred configuration. It does not allow data buffering on interface node.

XML Interface to the PI System1

Principles of Operation

The PI-XML interface is aclient that allows data to be passed between an XML server and a PI server. The interface will connect to one XML server, and multiple instances of the interface need to be run simultaneously in order to connect to multiple XML servers. More than one interface may be configured to connect to the same XML server.

The interface uses plug-in DLLswhich transform the data sources to the OPC XML-DA specification (version 1.0). In addition, the plug-in DLLs can define the method of connectivity and transport of the XML data. The name and location of the plug-in DLL is specified on the command line using the /dll parameter. If this parameter is not specified, the interface will load the default plug-in DLL,
<interface directory>\Plug-ins\OPC\PIXML_OPC.dll, to establish communication between the interface and anOPC XML-DA compliant server via SOAP messages that conform to the OPC XML-DA specification (version 1.0).

Once the plug-in DLL is loaded, the PI-XML interface tries to establish a connection to the PI server and check the status of the XML server. If a successful response is received, the interface will then initiate requests to get data from the XML server. If the connection is not successful, the interface will try to establish a connection periodically.

Note: The connection with the XML server is not persistent. However, if a connection is lost, data can be buffered by the XML server if supported by that server. Upon successful reconnection to the XML server, all historical values can be retrieved if the tag is configured to do so. The amount of data buffered is dependent on the XML server.

While running, the interface will identify its tags based on PointSource and Location1 point attributes. Tag configurations can be edited while the interface is running and these changes will be picked up by the interface automatically. In general, the interface will check for tag edits every 2 minutes. However, if it finds that at least 25 tags have been edited, it will check again in 30 seconds, otherwise it will wait another 2 minutes before checking again. All tag edits are performed in the following way: old versions of edited tags are deleted from the interface; new versions are added in. With some servers, this operation can require more time and more system resources. Therefore, it is more efficient to stop and restart the interface if a large number of tags are edited.

The PI-XML Interface is designed to constantly send messages about its operation to the pipc.log file. This file will contain the following information about the PI-XML Interface:

Informational messages on interface startup and shutdown;
The scan rate for each scan class and the actual update rate provided by the XMLServer.
Error messages for points rejected by the PI server, or error messages sent from the XML server;
Notification for all connections and disconnections from the server (e.g. when the connection with the XMLserveris lost and the interface attempts to reconnect)

The interface obtains timestamps from the XML server if the /ts option is not specified. By default, the XML server will do its own exception-based processing using the excdevattribute for each tag if supported by the XML server. This can be turned off by using /returnallitemscommand-line parameter, in which case the XML server will return all values at the specified scan rate. For XML servers that do not support exception processing, the /returnallitemscommand-line parameter does nothing. Further information regarding XML server exception processing can be found in the plug-in DLL manual. In addition to specifying the excdevattribute to the XML server, the interface can support multiple values being sent per scan through the use of location3., which can be useful if the XML server supports buffering. In this case, the XML server will buffer data if communication to the interface fails. Each buffered value will have a timestamp provided by the XML server. More detailed documentation regarding how the XML server supports buffering can be found in the corresponding plug-in DLL manual.

Plug-In DLLs

The PI-XML interface uses plug-in DLLs, which are libraries of routines that tell the interface how to get the XML data. The default plug-in is for XML servers that use SOAP over HTTP/S as outlined in the OPC XML-DA specification (version 1.0) given by the OPC Foundation. With this architecture, the interface can use additional plug-ins to access and transform XML data that doesn’t conform to the OPC XML-DA specification and define different methods of connectivity and transport of the XML data from the server to the interface. This gives the interface the ability to read generic XML documents and communicate with other web services provided a custom DLL is written. Since a lot of configuration settings only apply when connecting to an OPC XML-DA server, it is necessary to consult the plug-in documentation. Each of the plug-ins has its own documentation including the PIXML_OPC.dll plug-in which is the default plug-in.

Communication to an XML Server

Communication to an XML server is highly dependent on the plug-in being used. Typically, the PI-XML interface will check whether the server is available on startup, and if not, it will periodically recheck until the server responds. If the interface loses the connection to the PI Server after initial connection, it will continue to gather data from the XML Server. To avoid losing data in this situation, the use of the API buffering program, bufserv that buffers data on the interface node, is strongly recommended. Further information about communication to the XML server can be found in the plug-in documentation.

XML Interface to the PI System1

Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI-XML interface running. If you are not familiar with PI interfaces, 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 interface.
Test the connection between the interface node and the foreign device using the PI-XMLTool.
Define digital states.
Choose a point source.
Configure PI points.
Location1 is the interface instance.
Location2is specifies input/output points.
Location3 is the buffering flag.
Location4 is the scan class.
Location5 is not used.
ExDesc is not used.
InstrumentTag is the item name.
Configure performance points.
Configure I/O Rate tag.
Edit startup command file using the PI-ICU. The only interface-specific required parameter is:
/server=URL defines the connection.
See the plug-in manual for other required parameters.
Set interface node clock.
Set up security.
Start the interface without buffering.
Verify data.
Stop interface, start buffering, start interface.

XML Interface to the PI System1

Interface Installation

OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PIServer node. A PI Interface Node is any node other than the PI Server node where the PIApplication Programming Interface (PI-API) has been installed (see the PIAPImanual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PIServer is to archive data and to service clients that request data.

After the interface has been installed and tested, Bufserv should be enabled on the PI Interface Node (once again, see the PI-API manual). Bufserv is distributed with the PI-API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.

In most cases, interfaces on PI Interface Nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.

The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and interfaces as manual services that are launched by site-specific command files when the PI Server is started. Interfaces that are started as manual services are also stopped in conjunction with the PI Server by site-specific command files. Bufserv can be enabled on the PI Server node so that interfaces on the PI Server node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI Server node. See the UniInt End User Document for special procedural information.

Naming Conventions and Requirements

In the installation procedure below, it is assumed that the name of the interface executable is PIXML.exe and that the startup command file is called PIXML.bat.

It is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, one would typically use PIXML1.exe and PIXML1.bat for interface number 1, PIXML2.exe and PIXML2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line arguments in a file that has the same root name.

Interface Directories

The PIHOME Directory Tree

The PIHOME directory tree is defined by the PIHOME entry in the pipc.iniconfiguration file. This pipc.ini file is an ASCII text file, which is located in the WinNT directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on the C: drive. OSIsoft recommends using \pipc as the root directory name. The PIHOMEdirectory does not need to be on the C: drive.