PI-HTML Interface

HTML
Interface to the PI System

Version 2.2.0.63
Revision B

How to Contact Us

OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA 94577 USA
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
WWW.OSISOFT.COM
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.
© 2001-2008 OSIsoft, Inc. PI_HTML.doc

Table of Contents

Terminology vii

Introduction 1

Reference Manuals 1

Supported Features 1

Diagram of Hardware Connection 4

Principles of Operation 5

Installation Checklist 9

Data Collection Steps 9

Interface Diagnostics 10

Interface Installation on Windows 11

Naming Conventions and Requirements 11

Additional Required Software 11

Microsoft Internet Explorer 11

Microsoft XML Parser 12

Microsoft .Net Framework 2.0 12

Interface Directories 12

PIHOME Directory Tree 12

Interface Installation Directory 12

Interface Installation Procedure 12

Installing the Interface as Windows Service 13

Installing Interface Service with PI Interface Configuration Utility 13

Installing Interface Service Manually 16

Digital States 17

PointSource 19

PI Point Configuration 21

Point Attributes 21

Tag 21

PointSource 21

PointType 22

Location1 22

Location2 22

Location3 22

Location4 22

Location5 22

InstrumentTag 22

ExDesc 23

Scan 25

Shutdown 25

Output Points 25

Startup Command File 27

Configuring the Interface with the PI ICU 27

html Interface page 29

Configuring the Interface Without the PI ICU 38

Command-line Parameters 39

Sample PIHTML.bat File 43

Converting Older Configuration Files 43

Interface Node Clock 45

Security 47

Windows 47

Starting / Stopping the Interface on Windows 49

Starting Interface as a Service 49

Stopping Interface Running as a Service 49

Buffering 51

Which Buffering Application to Use 51

How Buffering Works 51

Buffering and PI Server Security 52

Enabling Buffering on an Interface Node with the ICU 53

Choose Buffer Type 53

Buffering Settings 54

Buffered Servers 57

Installing Buffering as a Service 60

Interface Diagnostics Configuration 63

Scan Class Performance Points 63

Performance Counters Points 64

Interface Health Monitoring Points 68

I/O Rate Point 75

Interface Status Point 76

Appendix A: Error and Informational Messages 79

Troubleshooting Differences Between the ICU Setup and the Interface 79

Check the Proxy and HTTP Authentication Settings 79

Connecting to an FTP 79

View the HTML Source Externally 80

Look For JavaScript Include Directives 80

Message Logs 81

Messages 81

System Errors and PI Errors 82

Appendix B: PI SDK Options 83

Appendix C: Plug-in Architecture 85

Dynamic URL Generation 85

Timestamp and Value Generation 85

HTML Modification 86

Receiving Pre-Transformed Information from the Interface 86

The COM Interfaces 86

SetDocument, ReleaseDocument 88

GetURL 88

ProcessTimestamp 88

ProcessData 88

ProcessDownloadedHTML 88

Plug-in Registration and Categorization 89

Quick Registration and Categorization 89

Using the Dispatch Hourly Energy Pricing Sample Plug-in 89

Creating a Visual Basic Plug-in 90

Revision History 93

HTML Interface to the PI System 91

Terminology

In order to understand this interface manual, you should be familiar with the terminology used in this document.

Buffering

Buffering refers to an Interface Node's ability to store temporarily the data that interfaces collect and to forward these data to the appropriate PI Servers.

N-Way Buffering

If you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering. N-way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering to multiple PI Server however it does not guarantee identical archive records since point compressions specs could be different between PI Servers. With this in mind, OSIsoft recommends that you run PIBufss instead.)

ICU

ICU refers to the PI Interface Configuration Utility. The ICU is the primary application that you use in order to configure and run PI interface programs. You must install the ICU on the same computer on which an interface runs. A single copy of the ICU manages all of the interfaces on a particular computer.

You can configure and run an interface by editing a startup command file. However, OSIsoft discourages this approach. Instead, OSIsoft strongly recommends that you use the ICU for interface management tasks.

ICU Control

An ICU Control is a plug-in to the ICU. Whereas the ICU handles functionality common to all interfaces, an ICU Control implements interface-specific behavior. Most PI interfaces have an associated ICU Control.

Interface Node

An Interface Node is a computer on which

·  the PI API and/or PI SDK are installed, and

·  PI Server programs are not installed.

PI API

The PI API is a library of functions that allow applications to communicate and exchange data with the PI Server. All PI interfaces use the PI API.

PI Collective

A PI Collective is two or more replicated PI Servers that collect data concurrently. Collectives are part of the High Availability environment. When the primary PI Server in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your PI clients.

PIHOME

PIHOME refers to the directory that is the common location for PI client applications. A typical PIHOME is C:\Program Files\PIPC. PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME. For example, files for the Modbus Ethernet Interface are in C:\Program Files\PIPC\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME directory. For example, ICU files in [PIHOME]\ICU.

PI SDK

The PI SDK is a library of functions that allow applications to communicate and exchange data with the PI Server. Some PI interfaces, in addition to using the PI API, require the use of the PI SDK.

PI Server Node

A PI Server Node is a computer on which PI Server programs are installed. The PI Server runs on the PI Server Node.

PI SMT

PI SMT refers to PI System Management Tools. PI SMT is the program that you use for configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT runs on either a PI Server Node or a PI Interface Node.

pipc.log

The pipc.log file is the file to which OSIsoft applications write informational and error messages. While a PI interface runs, it writes to the pipc.log file. The ICU allows easy access to the pipc.log.

Point

The PI point is the basic building block for controlling data flow to and from the PI Server. For a given timestamp, a PI point holds a single value.

A PI point does not necessarily correspond to a "point" on the foreign device. For example, a single "point" on the foreign device can consist of a set point, a process value, an alarm limit, and a discrete value. These four pieces of information require four separate PI points.

Service

A Service is a Windows program that runs without user interaction. A Service continues to run after you have logged off from Windows. It has the ability to start up when the computer itself starts up.

The ICU allows you to configure a PI interface to run as a Service.

Tag (Input Tag and Output Tag)

The tag attribute of a PI point is the name of the PI point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms "tag" and "point" interchangeably.

Interfaces read values from a device and write these values to an Input Tag. Interfaces use an Output Tag to write a value to the device.

HTML Interface to the PI System 91

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. Timestamps should be in a format that can be understood by the Visual Basic function CDate.

Starting with version 1.1.0, the HTML interface supports user-developed plug-ins for dynamically generating URLs, and for post-processing timestamps and values. Starting with version 1.2.0.4, the HTML interface supports one more plug-in routine for modifying the downloaded HTML before parsing it.

The PI HTML interface runs on Windows 2000, XP or 2003 on the Intel architecture. The software requirements for the PI HTML interface are Microsoft Internet Explorer 5.5 or greater, the PI Interface Configuration Utility (PI ICU), the PI SDK (which installs the PI API and Visual C++ 8.0 runtime libraries), and the .Net Framework 2.0.

Reference Manuals

OSIsoft

·  PI Server Manuals

·  PI API Installation Instructions

·  UniInt Interface User Manual

·  Regular Expressions Tutorial

·  PI Interface Configuration Utility User Manual

Supported Features

Feature / Support /
Part Number / PI-IN-OS-HTML-NTI
* Platforms / Windows (2000, XP, 2003)
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / 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
Supports Questionable Bit / No
Supports Multi-character PointSource / Yes
Maximum Point Count / Unlimited
* Uses PI SDK / Yes
PINet String Support / No
* Source of Timestamps / HTML Page / Current Interface Node Time
History Recovery / No
* UniInt-Based
* Disconnected Startup
* SetDeviceStatus / Yes
No
Yes
Failover / No
* Vendor Software Required on PI Interface Node / 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
Serial-Based Interface / No

* See paragraphs below for further explanation.

Platforms

The Interface is designed to run on the above mentioned Microsoft Windows operating systems and their associated service packs.

Uses PI SDK

The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface does not specifically make PI SDK calls.

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 Interface User Manual is a supplement to this manual.

SetDeviceStatus

For a Health Tag whose Extended Descriptor attribute contains [UI_DEVSTAT], the Interface writes the following values:

a)  "1 | Could not read web page.” – If the Interface can not connect to the web site this message is written to the Health tag.

Please refer to the UniInt Interface User Manual.doc file for more information on how to configure Health Tags.

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 http://www.microsoft.com.

Also required by the PI HTML interface is Microsoft’s XML Parser, version 6.0 or higher. The interface uses an XML file to store much of the interface configuration information. This is available at Microsoft’s web site, and is installed by the interface install kit as well as the PI SDK version 1.3.1 or higher.

Since version 2.2.0.61, the PI HTML interface requires version 8 of the Microsoft C Runtime library. This is installed automatically with the PI SDK.

Since version 2.2.0.61, the PI HTML interface requires the .Net Framework 2.0. This is available for download either from Microsoft’s web site or by using Windows Update.

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