HTML
Interface to the PI System

Version 1.0.5

1

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
Level One, 6-8 Nugent Street
Auckland 3, 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 OSI Software, 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.
pihtml.doc

 2002 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577

1

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

Additional Required Software

Microsoft DLLs

Microsoft Internet Explorer

Microsoft XML Parser

Interface Directories

The PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing the Interface as an NT Service

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Scan

Shutdown

Performance Point Configuration

I/O Rate Tag Configuration

Monitoring I/O Rates on the Interface Node

Configuring the PI Point on the PI Server

Configuration on the Interface Node

Startup Command File

Command-Line Parameters

Sample PIHTML.bat File

Configuring the PI-HTML Interface with the PI-ICU

Current Configuration File

HTML Locator Script

Markers Created on the Target HTML Page

Additional Parameters

Configuring the PI-HTML Interface Without the PI-ICU

Interface Node Clock

Security

Starting / Stopping the Interface on NT

Starting Interface as a Service

Stopping Interface Running as a Service

Buffering

Example PIClient.ini File

Appendix A Error and Informational Messages

Message Logs

Messages

System Errors and PI Errors

Revision History

1

PI-HTML Interface1

Introduction

The PI-HTML (HyperText Markup Language) Interface allows a user to collect data that is available in HTML-formatted text. This HTML text can be retrieved by the interface via HTTP (HyperText Transfer Protocol), FTP (File Transfer Protocol), Gopher, or from the interface node’s local file system.

The PI-HTML interface has the capability of storing a script describing how to get to a particular web page. This is useful for pages that require a login, or for pages that are created by filling out a form.

The interface can either provide its own timestamps for data, or it can parse timestamps from the HTML.

The PI-HTML interface runs on Windows NT 4.0 (Service Pack 4 or greater) or Windows 2000 on the Intel architecture. The only software requirements for the PIHTML interface are Microsoft Internet Explorer 5.5 or greater, the PI Interface Configuration Utility (PI-ICU), the PI-API, and the PI-SDK.

Reference Manuals

OSIsoft
  • UniInt End User Document
  • PI Data Archive Manual
  • PI-API Installation Instructions
  • Regular Expressions Tutorial
  • PI-Interface Configuration Utility User Manual

Supported Features

Feature / Support
Part Number / PI-IN-OS-HTML-NTI
Platforms / NTI
PI Point Types / PI2: real / digital / integer
PI3: float16 / float32 / float64 / int16 / int32 / string / digital
Sub-Second Timestamps / No
Sub-Second Scan Classes / No
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / No
Inputs to PI: Scan-Based / Unsolicited / Event Tags / Scan-based / Event Tags
Maximum Point Count / Unlimited
Uses PI-SDK / Yes
PINet to PI 3 String Support / No
* Source of Timestamps / HTML Page / Current Interface Node Time
History Recovery / No
Failover / No
* UniInt-Based / Yes
* Vendor Software Required on PI-API / PINet Node / Yes
Vendor Software Required on Foreign Device / No
Vendor Hardware Required / No
* Additional PI Software Included with Interface / Yes
* Device Point Types / String

* See paragraphs below for further explanation.

Source of Timestamps

Many web sites will provide timestamps with any data they have published. Some will not. The user can configure whether to read a timestamp from the web page or whether to just use the time the HTML page was read by the interface.

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-HTML 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 PI-HTML interface takes advantage of technology used in Microsoft Internet Explorer. Version 5.5 of Internet Explorer is required for the interface to function properly. It is available from Microsoft’s web site at

Also required by the PI-HTML interface is Microsoft’s XML Parser, version 3.0 or higher. The interface uses an XML file to store much of the interface configuration information. This is also available at Microsoft’s web site.

In most cases, this interface will be used to retrieve data from a web site. In that case, a web server is required to serve the data that will be used by the interface.

Additional PI Software

The PI-Interface Configuration Utility is recommended to configure the PIHTMLinterface. It is included with the interface, and it can be used to configure some other interfaces. As of this time, the PI-ICU requires a PI Server of version 3.3 or greater. For servers before version 3.3, there is another simpler configuration utility also supplied with the interface.

Device Point Types

Although there are many point types that can be read from a web page, in their native form as text on the page, they are text strings. The PI-HTML interface parses data into the appropriate data types before sending them to PI.

Diagram of Hardware Connection

1

HTML Interface to the PI System1

Principles of Operation

MSHTML

The PI-HTML interface builds on Microsoft’s Internet Explorer (MSIE) components. MSIE is not a monolithic application. It is composed of several components. The component of interest is the MSHTML component. This is responsible for making the network calls to retrieve an HTML page and for parsing the page. The page is parsed into a hierarchy of objects that are then used by MSHTML to efficiently draw the page in the browser window.

Microsoft makes these components available for reuse by developers who are developing web-browsing applications. The PI-HTML interface uses MSHTML to get the text from the target HTML page. It also uses the hierarchical object model of the HTML page provided by MSHTML to get the data out of the page.

Configuration

The PI Interface Configuration Utility (PI-ICU) is used to configure the PIHTMLinterface. The configuration for this interface is done graphically. The user browses to the target web page in a custom browser window, selects (using the mouse) where the data is on that page, and saves that information into a configuration file. That configuration file is read by the interface to figure out where specific data is located on the page.

The PI-ICU is a separate product, but it is included with the distribution package of the PI-HTML interface. The PI-ICU can be used to configure several other PI interfaces as of the writing of this manual. Since many of our interfaces are UniInt-based, the PI-ICU has a constant set of configuration parameters it can configure. However, since each of those interfaces also has its own interface-specific parameters, there are plug-ins available for the interfaces that are compatible with the PI-ICU that allow configuration of those interface-specific parameters.

Please refer to the PI-Interface Configuration Utility User Manual for more information.

If the target PI server is not at least version 3.3, the PI-ICU will not work with that PI server. This is because the PI-ICU makes extensive use of the PI Module Database, which was added in PI 3.3. In this case, there is also a simpler configuration tool provided specifically for configuring the HTML interface.

Interface Operation

The PI-HTML interface uses the configuration settings created by the PI-ICU to find data on the specified HTML page. There is a series of steps to dig through the HTML to get to the correct location on the page where the data is.

First, the interface downloads the correct page. In the process of configuring the interface using the PI-ICU (or with the simpler configuration tool), the ICU will have recorded a series of steps the user took to find the right target HTML page. The PIHTML interface follows those steps that were recorded to get to the same page.

Next, the interface uses the MSIE components to parse the HTML page into an object model. The important thing about this step is that the HTML text is converted into a hierarchical object model. This hierarchical view of the web page may be queried for a particular node. During the configuration process, the PI-ICU records the exact node that the user selected. Then, after the MSIE components have parsed the page and presented the interface with this hierarchical model, the interface navigates to the same node in the object model and extracts whatever data is there.

Timestamps as well as data can be extracted from a web page. It is possible to associate timestamps with data from a web page to form a complete timestamp-value pair.

For those systems that do not support the PI-ICU, a simpler configuration tool is available.

Pattern Matching

The PI-HTML interface uses regular expression (regexp) pattern matching in order to allow you to do some more advanced searching in the HTML page for data. In some cases, to select exactly the correct data, regexp is required. Take the following snippet of HTML code:

<TABLE>

<TR VALIGN=”BOTTOM”>

<TD COLSPAN=3>Weather data for December 12, 2001 12:32

pm</TD>

</TR>

<TR>

<TH>Temperature</TH>

<TH>Humidity</TH>

<TH>Barometric pressure</TH>

</TR>

<TR>

<TD<B>51</B> ºF</TD>

<TD<B>72</B> %</TD>

<TD<B>29.97</B> inHg</TD>

</TR>

</TABLE>

The data we are interested in is the timestamp, and the three values. The way data is retrieved from MSHTML, the timestamp would actually be returned to the interface as “Weather data for December 12, 2001 12:32 pm”. This is because MSHTML uses the HTML tags as delimiters for the text. In this case, there are no HTML tags separating the “Weather data for” and the actual date part. When the interface tries to parse that into a date, as error will occur, because of the leading text. Pattern matching and substitution can be used to search through this text and select only the data you are interested in.

The values would be read fine without having to use pattern matching, because the numbers themselves are stored inside the bold (<B>) tags. So even though there is text right next to the numbers when viewed in the web browser, in the HTML code, the digits are delimited from the units of measure by HTML tags.

This topic is described in more detail in the Regular Expressions Tutorial. There are techniques and examples for many common situations where pattern matching may be required to have the interface correctly gather the data you want to gather.

1

HTML 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-HTML interface running. If you are not familiar with PIinterfaces, you should return to this section after reading the rest of the manual in detail. These sections are described in detail later.

  1. Verify that the PI-API has been installed.
  2. Verify that the PI-SDK has been installed.
  3. If you will be using the PI-ICU, make sure that is installed.
  4. Install Microsoft Internet Explorer version 5.5 or higher (
  5. Install the PI-HTML Interface and PI-HTML Interface ICU Control using the two .msi files included in the distribution kit, or by running the html_x_x_x.exe WinZip Self-extracting setup kit.
  6. Test the connection between the interface node and the target web page by bringing that page up in Internet Explorer.
  7. Use the PI-ICU or the simpler HTML Interface configuration utility to set up timestamp and data markers. Save those into an XML configuration file.
  8. Choose a point source. If PI 2 home node, create the point source.
  9. Configure PI points.
    location1 is the interface instance.
    location2 is not used.
    location3 is not used.
    location4 is the scan class.
    location5 is not used.
    exdesc is not used.
    instrumenttag is the data marker (or markers) associated with the PI point. Delimit data markers with a semicolon (;).
  10. Configure performance points.
  11. Configure I/O Rate tag, if you did not configure that using the PI-ICU.
  12. If you are not using the PI-ICU to control the startup .bat file, configure that now.
    /htmlconfigfile=”c:\path\to\your\config.xml”
    /db=debuglevel (see debugging section)
    /dltimeout=debuglevel (see startup parameters section)
  13. Set interface node clock.
  14. Set up security on the PI server.
  15. If this is being installed as a service, make sure to set the service to Log On as a user in the administrators group. Also, use dcomcnfg to set the DCOM Default Security/Default Access Permissions and Default Launch Permissions
  16. Start the interface without buffering.
  17. Verify data.
  18. Stop interface (and all PI-API applications), start buffering, restart interface.

1

HTML Interface to the PI System1

Interface Installation

OSIsoft recommends that interfaces be installed on PI-API nodes instead of directly on the PIServer node. A PI-API node is any node other than the PI Server node where the PIApplication Programming Interface (PI-API) has been installed (see the PIAPIInstallation Instructions manual). 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 PIAPInode (once again, see the PI-API Installation Instructions 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-API 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. This typical scenario assumes that Bufserv is not enabled on the PI Server node. 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.

In addition to the PI-API, the PI-SDK is required for the HTML interface to function properly. This is due to the PI-API’s 32-character limit on the instrumenttag point attribute

Naming Conventions and Requirements

In the installation procedure below, it is assumed that the name of the interface executable is pihtml.exe and that the startup command file is called pihtml.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, you would typically use pihtml.exe and pihtml.bat (or pihtml1.exe and pihtml1.bat) for interface number 1, pihtml2.exe and pihtml2.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.

Additional Required Software

Microsoft DLLs

The following Microsoft DLLs are distributed on the installation CD-ROM. Copy these files to the winnt\system32 directory only if the files in the winnt\system32directory are older than the files on the CD-ROM.

MSVCIRT.DLL
MSVCRT.DLL
MSVCRT40.DLL
MSVCP50.DLL
MSVCP60.DLL

The following additional Microsoft DLLs are also distributed on the CD-ROM. These DLLs are only used by a debug version of the interface. Copy these files to the Winnt\system32 directory only if the files in the winnt\system32 directory are older than the files on the CD-ROM.

MSVCIRTD.DLL
MSVCRTD.DLL
MSVCP50D.DLL
MSVCP60D.DLL

Microsoft Internet Explorer

Microsoft Internet Explorer version 5.5 or higher is required for the PI-HTML interface. Its browsing and parsing functionality is used by the interface. This should be installed before the interface is configured or started. The updater software is available on Microsoft’s web site at