Table of Contents

PI-ActiveView Developer’s Guide

Published April 2000

Version 2.1

OSI Software, Inc.

777 Davis Street, Suite 250, San Leandro, CA 94577
States.
Unpublished -- rights reserved under the copyright laws of the United

PI-ActiveView Developer’s Guide iii

How to Contact Us

Phone
(510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax (510) 357-8136
Internet
[email protected]
World Wide
Web http://www.osisoft.com
Mail
OSI Software, Inc. OSI Software, Ltd
P.O. Box 727 P. O. Box 8256
San Leandro, CA Level One, 6-8 Nugent Street
94577-0427 Auckland 3, New Zealand
USA

OSI Software GmbH OSI Software, Asia Pte. Ltd.

Hauptstrae 30 152 Beach Road
D-63674 Altenstadt 1 #09-06 Gateway East
Deutschland Singapore, 189721

 2000 OSI Software, Inc. All rights reserved

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.
376789024.doc
 Table of Contents

Chapter 1. Introduction to PI-ActiveView 1

Producing a Web Site.....................................................................................1
PI-ActiveView Installation Options..................................................................2
Security............................................................................................................. 2
Training Users................................................................................................. 2
Glossary of Terms........................................................................................... 2
What the Product Package Includes...............................................................3
Chapter 2. Information for End-Users 5
How to View PI Data with PI-ActiveView.........................................................5
Content of a PI Display Document..................................................................6
Trace Types.............................................................................................. 7
Updates to Data in a Display..........................................................................7
Refresh Button in the Browser..................................................................7
User Interaction with the PI Display Document...............................................8
Expand a Trend........................................................................................ 8
Trend Cursors to Display Values..............................................................8
Shift Time Range......................................................................................9
Alter Trend Scale....................................................................................12
Other Features.......................................................................................12
Chapter 3. Software Installation 13
Software Installation......................................................................................13
Minimum Software Requirements..........................................................13
Installation Procedures.................................................................................14
Developer Installation.............................................................................14
Automated User Installation...................................................................15
User Installation via Setup.exe...............................................................15
Uninstalling PI-ActiveView............................................................................16
Installs from Setup.exe...........................................................................16
Installs from Web Sites...........................................................................16
Chapter 4. Technical Overview 17
Flow of Information.......................................................................................17
PI-ActiveView Control...................................................................................19
PI-ActiveView Executable.............................................................................20
Cabinet Files and Digital Signatures.............................................................20
User Interface of PI-ActiveView....................................................................20
Refresh Button (IE Only)........................................................................21
Back and Forward Buttons (IE Only)......................................................21
Expiration (IE Only)................................................................................21
Chapter 5. Planning to Use PI-ActiveView 23
Developer's Kit..............................................................................................23
Installation Considerations............................................................................23
Security Choices........................................................................................... 24
Access to PI Data...................................................................................24
Access to Web Sites...............................................................................24

PI-ActiveView Developer’s Guide iii

 Chapter 6. Creating PI Display Documents 25
Creating PI Display Documents....................................................................25
Sizing the ActiveView Control and the PI Display Document..................25
Embedded Objects.................................................................................25
Fonts...................................................................................................... 25
ADO........................................................................................................ 25
Commands.............................................................................................25
Help Buttons for Users...........................................................................26
Buttons to Other Displays or Applications...............................................26
Converting Existing Displays........................................................................26
Chapter 7. Building Cabinet Files 27
Building Cabinet Files...................................................................................27
Additional Components.................................................................................27
Using the Cabinet Wizard.............................................................................28
If You Have a Firewall...................................................................................33
Chapter 8. Developing the Web Page 35
Developing the Web Page............................................................................35
Resizing Displays.......................................................................................... 35
Using Netscape Navigator............................................................................36
Downloading New PI Server Information......................................................36
Adding a Component with an .inf File...........................................................37
Embedding a Display into an HTML Page Using FrontPage2000.................37
Chapter 9. Automation 41
Automation Interface.....................................................................................41
Control Characteristics...........................................................................41
Container Requirements.........................................................................41
Internet Requirements............................................................................42
Properties, Methods, and Events..................................................................42
IE Supported Events...............................................................................42
AboutBox Method...................................................................................42
BeforeConnection Event.........................................................................43
BCParam................................................................................................44
BuildDateStamp Property.......................................................................45
ConnectionFailed Event.........................................................................45
CFParam................................................................................................ 47
Display Property.....................................................................................47
DisplayURL Property..............................................................................48
ReadyState Property..............................................................................49
ReadyStateChange Event......................................................................49
ServerIniURL Property...........................................................................50
Chapter 10. Using Other Containers 55
Embedding PI Display Documents in Other Containers................................55
Embedding a Display in a Spreadsheet........................................................55
Chapter 11. Troubleshooting 57
Before You Call OSI Tech Support................................................................57
Browser Security...........................................................................................57
Accessing PI Data......................................................................................... 58
Web Installs on NT Machines.......................................................................58
Viewing a Revised HTML Page....................................................................58
Changing the IE Specification for Checking for New Versions......................58
How to Refresh a Particular Stored HTML Page or Display on a Page........58
How to Delete Stored HTML Pages..............................................................58
Digital Signature Problems in the CabWizard...............................................59

PI-ActiveView Developer’s Guide iv

Table of Contents
Chapter 12. Glossary 61

PI-ActiveView Developer’s Guide v

 Chapter 1.
Introduction to PI-ActiveView
PI-ActiveView allows users to browse displays of live data from the PI Data Archive as
well as from ODBC sources (via ADO or VBA) on the Internet or on a corporate Intranet.
These displays of live data, called PI Display Documents, are derived from displays built
in the PI-ProcessBook application.

Figure 1 What the User Sees in the Browser

While a user is viewing a PI Display Document in the browser, the display will
automatically update with new data that reaches the PI Data Archive. Dynamic symbols
such as trends, bars, or values, will update just as they would in PI-ProcessBook.
Users can obtain specific data values from a trend image, change the size of a trend, or
shift the time period being displayed in a trend.
Chapter 2 describes PI-ActiveView in non-technical terms and explains how to use it
from the user perspective.

Producing a Web Site

To produce a Web site, a Web developer saves a PI-ProcessBook display as an
independent file (.PDI File) and incorporates it within a page written in Hypertext
Markup Language (HTML). A developer may also choose to use ASP (Active Server
Pages) with Microsoft Internet Information Server (IIS). The PI Display Document may
be fully integrated with other content stored on the Web site.

PI-ActiveView Developer’s Guide 1

 In addition to basic PI-ProcessBook displays, developers may use displays built with the
PI-BatchView and PI-SQC add-ins to PI-ProcessBook. However, if these products are
included, users must also have licenses for them.
Displays may include automation scripts in VBA.
The developer may also prepare cabinet files to download and install PI-ActiveView
software for the users from the Web site.
PI-ActiveView may be used in other containers, such as Microsoft Excel, as well.
Chapter 4 discusses the details of producing Web sites with PI-ActiveView.

PI-ActiveView Installation Options

Developers should install directly from the CD in order to obtain both the runtime
version of PI-ActiveView and the Developer’s Kit. The Developer’s Kit is loaded into the
acview/webdev directory.

Depending on the corporate security standards for the Browser, users may be able to
install and configure the PI-ActiveView application directly from the Web site where PI-
ActiveView displays are incorporated. Otherwise, the user or a network administrator can
install the product individually at each PC using the setup kit. Read more about this in the
Installation section.
Microsoft Internet Explorer (IE) is required if automated installation from the Web site
is used. Users do not need a copy of PI-ProcessBook.
Installation procedures appear in Chapter 3.

Security
Security issues may be addressed through security features of the Web server, the user's
PC, and the PI Data Archive.

Training Users
Most users will be familiar with the features of their browser, but they will need an
introduction or support to become familiar with the interactive features of PI-ActiveView.
A developer may provide online help for using the features of the PI Display Document
by including a help button in the PI Display Document.
Help for Users is included in Chapter 2 of this document and repeated in acview.hlp.
OSI Software provides this Developer’s Guide in Microsoft Word format for trainers to
adapt in preparing training materials.

Glossary of Terms
This Developer’s Guide uses a number of Internet and computer terms that may be
unfamiliar or imprecise to readers. A Glossary of Terms is included in Appendix D to
explain how the terms are used in this book.

PI-ActiveView Developer’s Guide 2

 What the Product Package Includes
The PI-ActiveView product is shipped with the following components:
1. Developer Kit for building Web sites, containing the ActiveX control, signed cabinet
files, the Cabinet Wizard utility, supporting files, and a Staging Area with sample
code for Internet Explorer and Netscape Navigator.
2. PI-ActiveView software for end users, including VBA and ADO components.
3. PI-ActiveView ActiveX control. This PI-ActiveView Control has a simple set of
properties that allows viewing of the PI Display Document and permits VBA scripts
to run.
4. Online documentation, as follows:
 PI-ActiveView Developer’s Guide in help file format. This is normally installed
in the acview directory.
 PI-ActiveView Developer’s Guide in Microsoft Word format is located on the CD
but not installed by setup.exe. Chapter 2 of this document contains information
for the end user on using features of Displays.
 Help files for the PI-ActiveView control (installed in the procbook directory)
and the CabWizard (installed in the webdev directory).
 Readme.htm, which includes last-minute release note information.
 Sample.htm, a sample HTML file with an OBJECT tag specifying the
ActiveView Control.
 Staging Area Sample Site.htm, which describes how to use the files provided
for a download staging area.

PI-ActiveView Developer’s Guide 3

 Chapter 2.
Information for End-Users

How to View PI Data with PI-ActiveView

PI-ActiveView allows users to browse displays of live data from the PI Data Archive on
the Internet or on a Corporate Intranet.
While a user is viewing a PI Display Document in the browser, the display will
automatically update every few seconds with new data that reaches the PI Data Archive.
Dynamic symbols such as trends, bars, or values, will update just as they would in
PI-ProcessBook.
Users can obtain specific data values from a trend image, change the size of a trend, or
shift the time period being displayed in a trend.
Four steps are involved in viewing a PI Display Document on a Web page with
PI-ActiveView:
1. A user goes to a Web site page containing a PI Display Document.
2. The browser loads the PI-ActiveView Control and displays the page. If automated
software downloading has been established by the Web page developer, the Web
server determines whether the user's PC already has PI-ActiveView. If not, the Web
server attempts to download and install it.
3. PI-ActiveView presents the PI Display Document on the HTML page in the user's
PC.
Note: If the user needs a password to connect to the PI Data Archive, a dialog box
for logging on will appear at this point.
4. PI-ActiveView gets the appropriate data from the PI Data Archive and loads the data
into the PI Display Document.
Figure 2 shows the downloading and data retrieval paths in a diagram.

PI-ActiveView Developer’s Guide 5

Chapter 2 Information for End-Users

Figure 2 How PI-ActiveView Presents PI Data

Content of a PI Display Document

A PI Display Document viewed through PI-ActiveView can contain both static and
dynamic content. Static content may include bitmaps, schematics, or text. Dynamic
elements include values, bars, and trends that are updated when the data in the PI Data
Archive changes. A developer can include symbols that change colors as certain values
are reached.
Values are simply numeric values for particular points in the PI Data Archive. A value
may or may not include a tag (point) name or a time stamp. Bars show values graphically.
Trends are plots of point data over time.

Figure 3 Values, Bars, and Trends in a Display

6 OSI Software, Inc.

 Each trend has at least one plot. The various plots and their labels may be colored in
matching colors. If the trend extends to the current time, the right border is a dotted line.
Labels may include the point name, description, current value, and engineering units.
Figure 4 Parts of a trend

Trace Types
A Trace, also referred to as a pen, is a single line on a trend. When a trace is continuous,
a line is drawn from measurement to measurement. When a trace is discrete, the value is
propagated forward until a new value is recorded in the database. This results in a
horizontal line and a vertical line for the tag (staircase trace).
Digital points in the PI Data Archive are discrete type measurements, producing staircase
traces. For digital points, the offset from the starting digital state code is plotted. When
the value is shown in a trend cursor or legend, the text translation is displayed (for
example, ON or OFF). Certain other attributes for points in the PI Data Archive will also
produce staircase traces.

Updates to Data in a Display

Every five seconds, PI-ActiveView asks each PI Server for all the new values for tags in
open Displays. The trends, bars, and other symbols in each Display are updated to reflect
the new information. The PI System Administrator can alter this update scan rate.
Values from PI calculations and custom data sets are also updated dynamically.

Refresh Button in the Browser

Clicking the Refresh button on IE forces the PI-ActiveView Control to download the
Display from the Web site again. It is not necessary to use Refresh to update the data in
the Display; Displays are updated automatically.

User Interaction with the PI Display Document

The user may interact with trends in a PI Display Document through several features,
including expanding the trend, changing the time range, and showing specific values
through trend cursors.

PI-ActiveView Developer’s Guide 7

Chapter 2 Information for End-Users
Users may not change the Display or save it separately. Display documents may not be
resized. No menus or toolbars are available.
After a user has finished viewing a document and closed the page, any interactive
features that were used revert to their original configuration.

Expand a Trend
Double clicking on a trend will expand it to fill the PI Display Document. Double
clicking again will restore the original dimensions.

Figure 5 Before and After Expanding a Trend

Trend Cursors to Display Values

Trend cursors may be used to determine values at particular points on a trend.
To initiate a trend cursor, move the mouse cursor to the left axis of the trend. It will
change to a small icon. Drag it to the right. The values shown will change as you move
across the trend.

Figure 6 Trend cursors. One has a value of 78.78. The other is not yet pulled from the left
margin.
When you release the mouse, the vertical line and value will remain on the display and
you can obtain a second trend cursor from the left margin. When you close the page, the
vertical lines and values will disappear.

8 OSI Software, Inc.

 To remove a trend cursor without closing the page, click on a trend cursor and drag it to
the left or right off the trend.

Shift Time Range

The time range represented by a trend, bar or value may be shifted. Click on the right-
mouse button to bring up the menu and select Time Range.

Figure 7 Right mouse click on a Trend reveals a menu

The Change Time Range dialog appears. Select a range from the two dropdown boxes or
type in a range. You can enter time ranges in relative time, absolute time, or a
combination of the two. Time Range Formats are discussed in detail in a later section.

Figure 8 Change Time Range dialog

Click OK and the new values for the trend or bar will be displayed. To return to the
original range, select Revert on the right-mouse menu.
Note: The time represented on your display is the time relative to the PI Data Archive
server. If the server to which you are connected is in a different time zone, current data is
of the location of the server.
The example below shows a trend displaying data through the current time and the same
trend displaying data from 8 hours ago. Note that the right border of the trend changes

PI-ActiveView Developer’s Guide 9

Chapter 2 Information for End-Users
from dotted, signifying current time, to solid, signifying a specific time in the past. The
vertical scale may also change, as it does here, if the trend is formatted to have Autorange
scaling.
Figure 9 Shifting the Time Range of a Trend

Time Range Formats

All trends have a left and a right time scale that define the span of time for which tag data
is plotted. Each scale can be expressed in either absolute or relative time. Bars have
similar scales; values have only one time scale.

Relative Time
Relative time is some number of days, hours, minutes, or seconds. The leading sign
(+ or -) is required.

+/- N d | h | m | s
where N is any number.
The default starting point for relative time is usually the current time. Therefore, a time of
-8h is eight hours before the current time. Fractional times may be entered. For example,
use -1.5d for one and one-half days.
For trends, relative times for the left time scale are relative to the current time. Relative
times for the right time scale are relative to the left time scale.

Absolute Time
Absolute times have one of these formats:
Format Description
DD-MMM-YY hh:mm:ss day-month (alphabetic)-year hour:minute:second
* The current time.
T 00:00:00 on the current day (TODAY)
Y 00:00:00 on the previous day (YESTERDAY)
S,M,TU,W,TH,F,SA 00:00:00 on the most recent Sunday, Monday,.., Saturday.

For the DD-MMM-YY hh:mm:ss format, if any of the date fields are left out, they default
to the current date. Time fields default to 00.
Examples of the DD-MMM-YY hh:mm:ss format, including defaulted fields:
Example Description
25 00:00:00 on the 25th of the current month
8: 08:00:00 on the current date
25 8 08:00:00 on the 25th of the current month
21::30 9:00:30 PM on the current date

Note that this format is slightly different from the DEC OpenVMS format, which uses a
4-digit year.
You may also use the Windows time and date format for an absolute time. These are
configured through the Control Panel.

10 OSI Software, Inc.

 Combined Time Scales
Combined time scales use both an absolute and a relative time. The absolute part of the
time can be *, T, Y, or a day of the week.
Examples of combined time scales:

Example Description
T + 8h 08:00:00 AM on the current day (today)
Y - 8h 04:00:00 PM on the day before yesterday
M + 14.5h 02:30:00 PM on the most recent Monday
SA - 1m 11:59:00 PM last Friday
* - 1h one hour ago

Trends with Future Time Ranges

Trends with time ranges that extend into the future will update normally. Use an asterisk
plus a time interval (for example, *+4h). This feature will not work if you input the time
in a format such as 10-Jan-00 or T+10H. The asterisk and plus sign are necessary.

Alter Trend Scale

If you double click on the Y-axis, a trend scale dialog appears and you can reset the scale
or scales.
Figure 10 Trend Scale dialog

PI-ActiveView Developer’s Guide 11

Chapter 2 Information for End-Users
Other Features
If a developer includes VBA script in the PI Display Document, the user will be able to
initiate other functionality, such as selecting from a list of PI Display Documents or
switching data points or servers being viewed.

12 OSI Software, Inc.

 Chapter 3.
Software Installation

Software Installation
PI-ActiveView is distributed as a complete package for a developer to use in preparing
Web pages with content from the PI Data Archive. The runtime version for users is
derived from the complete package and may be installed either by an automated
download from a Web site or by the use of Setup.exe.

Minimum Software Requirements

For Users
 Windows95, Windows98, WindowsNT 4.0 SP3 or later, or Windows 2000
 16 MB RAM (at least 32 MB RAM is recommended)
 Microsoft Internet Explorer 4 or Netscape 3.0*
 32 MB of hard disk space
 For Windows95, in order to see SQC charts, a user also needs to have WinSock
installed in advance of the download. For more information, see:
http://support.microsoft.com/support/kb/articles/q182/1/08.asp

For Developer PC
 PI-ProcessBook 2.0 or greater
 Suitable tools for creating Web pages
 Windows95, Windows98, WindowsNT 4.0 SP3 or later, or Windows 2000
 16 MB RAM (at least 32 MB RAM is recommended)
 Microsoft Internet Explorer 4.0 or greater. To use a digital signature, Microsoft IE 4
Service Pack 1 is also required. Alternatively, Netscape Navigator 3.0*.
 48 MB of disk space
 To use the PI-SQC installation kit cabinet file (outerSQC.cab), a developer must
have installed PI-SQC 1.0 first. Likewise, to use the PI-BatchView installation kit
.cab file, (outerbv.cab) a developer must have installed PI-BatchView 2.1 first.
* A Netscape browser may be used if you are not planning to download installation files
from the Web site. The Netscape browser must also contain a plug-in enabling the use of
ActiveX controls.

For Web Server

If you are not installing PI-ActiveView through the automated download process, the
server can be any web server that will deliver the files to a web browser.

PI-ActiveView Developer’s Guide 13

 If you are planning to use automated download and installation of PI-ActiveView for
users, you will need:
 a WindowsNT server 4.0, SP3 or greater
 Microsoft(R) Internet Services Personal Web Server Version 4.0 (PWS) or
Microsoft Internet Information Server 4.0 (IIS)
 IIS requires NT 4.0 Server or Win2000. PWS runs on NT 4 Workstations.

Installation Procedures
There are three types of installation of PI-ActiveView:
 Developer installation through setup.exe.
 User installation through an automated download from a Web site.
 User installation by running a modified version of setup.exe.
Each type is described in the following sections.

Developer Installation
For developing PI-ActiveView Web sites, use the default installation of PI-ActiveView as
shipped by OSI Software. It contains all of the .cab and .inf files needed to create Web
pages with PI-ActiveView content.
To install, run setup.exe. The setup will ask for a target directory. The default target
directory is C:\Program Files\PIPC, which is the default location for installing PI
client products.
Unless there is a PI product already installed in the target directory, Setup will ask for PI
Data Archive connection information.
Setup.exe will install ADO and VBA components if these are not already on the PC. If
the installation procedure includes ADO or VBA components, it will require a reboot of
the PC during the process.
The installation program will refer to a Microsoft web site to obtain MFC.dlls. If your
corporate firewall prevents this, you will need to incorporate these files into your
download cabinet files.
Upon completing the setup, the directory structure will be as follows:
Directory Contents
<target>/acview PI-ActiveView application (Acview.exe) and supporting .dlls
<target>/acview/webdev Web-development utilities, cabinet files, and text files
<target>/acview/webdev/stagin Sample.asp, demonstrating a staging area for download.
g
<target>/procbook pbdcrtl.ocx, the PI-ActiveView Control; pbdctrl.twd;
and help files
<target>/dat acview.ini, pilogin.ini

CabWizard will appear under PI System on your Start menu.

You can see exactly what files were installed by reading <target>/dat/setupav.log.

PI-ActiveView Developer’s Guide 14

 You will also need a copy of PI-ProcessBook 2.0 or greater, in order to build the PI
Display Documents (.PDI files) used to show the data. Both applications can be used on
the same PC without difficulty. Where both applications are present, Acview.exe, rather
than ProcBook.exe, will become the automation server for The PI-ActiveView Control.
If you want to use PI-BatchView and/or PI-SQC add-ins to PI-ProcessBook in your
Displays, you will need to install these as well.

Automated User Installation

Once you have set up a Web site containing installation files, users can install and
configure a runtime version of PI-ActiveView when they first browse a page containing
it. The download is automated and will ask users only a few simple questions.
Information about security options and other planning decisions for automated downloads
may be found in other sections of this guide.
Whenever a user clicks on the HTML page, IE will determine whether a user has already
installed the user's version of PI- ActiveView and if not, will attempt to download and
install it.
Depending upon the PC’s IE security settings, the user may be asked if it is OK to
download one or more components. If the cabinet files in the download have not been
digitally signed, the user may not be able to complete installation.
You can include PI-BatchView and PI-SQC components to Displays when you build your
installation cabinet files. Each user will need a licensed copy of these components.
Note: Help files are not built into the automatic download. If you want users to access
them, you will need to install these separately, possibly on the Web server.
The download will also include ADO and VBA components if these are not already on
the PC. Either the installation will refer to a Microsoft web site to obtain them or the
developer must include them in the cabinet files. The installation procedure will require a
reboot of the PC during the process.
On WindowsNT, an error condition may accompany the reboot message because the
download has not completed. Dismiss the error and reboot. Upon rebooting, open IE,
browse to the HTML page again, and double click to complete the download.
Note: Users who need to install ADO or VBA components must be logged on with
administrative privileges to enable the install. Otherwise, 'guest' privileges will be
sufficient to install the remaining parts of PI- ActiveView.
A full download of PI-ActiveView software over an Intranet may require several minutes.

User Installation via Setup.exe

Information about security options and other planning decisions for PI-ActiveView users
may be found under “Planning to Use PI- ActiveView.”
If you do not wish to have users download and configure their own PI-ActiveView
automatically, you can load the software individually using setup.exe. You will also
need to ensure that each user has installed an appropriate copy of pilogin.ini in order to
access the PI Data Archive. Information about security options and other planning
decisions for user installation may be found in other sections of this guide.
If you plan to include PI-BatchView and/or PI-SQC add-ins in your Displays, you will
need to acquire a license and load these components separately for each user.

PI-ActiveView Developer’s Guide 15

Chapter 3 Software Installation
Preparing PI-ActiveView for User Installation from Setup.exe
1. Copy the PI-ActiveView files to a separate, writeable location that you will be using
for user installations.
2. Open the copy of setup.ini in an application such as Notepad.
3. Add the following line under the [Defaults] section:
DEVELOPER= N

4. Save and close setup.ini.

This change will allow setup.exe to omit the Developer's Kit during installation.

Installation on a User's PC
Log on to a user's PC with an ID that has administrative privileges. Run setup.exe. The
resulting directory structure will be created as follows:
Directory Contents
<target>/acview PI-ActiveView user's application and supporting .dlls
<target>/procbook PBDCtrl.twd; PBDCrtl.ocx, the PI- ActiveView Control;
and help files
<target>/dat acview.ini, pilogin.ini

The files you have installed are listed in <target>/dat/setupav.log.

Uninstalling PI-ActiveView

Installs from Setup.exe

If you install PI-ActiveView using setup.exe, you can use the Add/Remove Programs
option on Control Panel to remove it. You must remove the BatchView and SQC
components separately. The VBA components will not be removed.

Installs from Web Sites

If you install PI-ActiveView through a Web download, you can use the Add/Remove
Programs option on Control Panel to remove it. BatchView and SQC components will
also be removed. The VBA components will not be removed.

16 OSI Software, Inc.

 Chapter 4.
Technical Overview

Flow of Information
When a Web page containing PI-ActiveView content is opened, the flow of information
occurs in several distinct steps:
1. The user opens a browser such as Internet Explorer (IE) and selects an Internet or
Intranet address (URL) for a stored HTML page. The page downloads from the Web
server unless it is already cached on the user's PC. The PC has Internet settings that
determine how long an existing page is stored before it is discarded.

Figure 11 User downloads HTML page, .cab files if necessary, and Display
2. The browser tries to load the PI-ActiveView Control object and determine the
current DisplayURL property, which tells where the PI Display Document (.PDI
file) is stored.
If the control is not registered on the user's PC, the browser cannot load it. Then, if
cabinet files are specified in the HTML, the browser will attempt to download them
so the user can install the PI-ActiveView software from the Web site. User browser
security settings may prevent this download. The browser will also check the
version of the control on user’s PC, and if the control is older than the one
mentioned in the CODEBASE property then the browser will attempt to download
it.
3. When the browser loads the PI-ActiveView Control successfully, the control will
open acview.exe. Acview.exe enables the Display (.PDI file), which may be stored
separately from the HTML page, to be viewed through the PI-ActiveView Control on
the user's PC.

PI-ActiveView Developer’s Guide 17

 4. Acview.exe connects to the PI Data Archive through the PI-API and displays actual
data. The user sees the HTML page, part of which is drawn by the PI-ActiveView
Control and acview.exe. The acview.exe and the PI-ActiveView Control are not
visible to the user.

Figure 12 Data begins arriving from the PI Data Archive.

The sequence of events is shown in the following flowchart.

PI-ActiveView Developer’s Guide 18

 Figure 13 Flowchart Showing How PI-ActiveView Works

PI-ActiveView Control
The PI-ActiveView Control, pbdctrl.ocx, is an ActiveX control. It enables PI Display
Documents to be viewed inside ActiveX containers, including Web browsers. The PI-
ActiveView Control also needs server support, which it obtains from PI-ActiveView
executable, acview.exe. The control is marked Safe for Initialization.
The Control is embedded in Web pages using the OBJECT tag in an HTML document.
The CODEBASE attribute of the OBJECT tag points to an information file (.inf) or a
"cabinet file," which contains the information file. An .inf file points to other cabinet
files, containing the control and other components, and controls the installation of the
software on users' PCs. The CODEBASE attribute can be omitted if you do not want
users to download the PI-ActiveView software from that Web page.
The PI-ActiveView Control provides a read-write Property (DisplayURL) that points to a
PI Display Document (.PDI file) for viewing. The control provides a read- only Property
(Display) that permits access to the Display Object’s automation interface so that you can

PI-ActiveView Developer’s Guide 19

Chapter 4 Technical Overview
manipulate the display from browser scripts. More information is given under
Automation.
Note: The Display file may be stored separately from the Control; however, the
DisplayURL property of the PI-ActiveView Control, Pbdcrtl.ocx, must point to the
exact location of the .PDI file.

PI-ActiveView Executable
The PI-ActiveView executable, acview.exe, displays data in the Display file. It will
not interfere with the browser. To improve performance, the PI-ActiveView Control,
pbdcrtl.ocx, contains caching for recently viewed Display files.
Acview.exe persists for up to 5 minutes when a page is closed. Two or more Displays
on the same page use the same acview.exe instead of loading multiple copies of it in
the memory.
In order to operate, acview.exe requires several supporting .DLLs, ADO core
components, and VBA core components. OSI Software provides most of these
components in cabinet files. There is also a link to the Microsoft MFC.DLL installation
Web site to provide MFC42.dll and other files. The Troubleshooting section discusses
how to handle instances where a firewall prevents access to Microsoft Web sites.

Cabinet Files and Digital Signatures

Cabinet files are compressed files that minimize the file size and the associated download
time for Web content. The .cab file format is a nonproprietary compression format, also
known as MSZIP. Cabinet files have a .cab file name extension.
The Internet Explorer browser is able to decompress and use .cab files. At this time, the
Netscape browser is not.
Like ActiveX controls, .cab files can be digitally signed. A digital signature associates a
software vendor's name with a given file. A signature is applied to a .cab file using the
Microsoft Authenticode technology. Cabinet files provided by OSI Software, Inc., are
signed with OSI Software’s digital signature.
More information on cabinet files and digital signatures can be found on a Microsoft Web
site:
http://msdn.microsoft.com/msdn-online/workshop/components/activex/packaging.asp

User Interface of PI-ActiveView

The user interface is similar to that of a PI-ProcessBook Display in View-only mode.
Expanding a trend, zooming in a time range, and manipulating cursors can be
accomplished.
The right mouse menu has two options, Time Range and
Revert, which are used in manipulating the time range of
a trend.
Analysis operations that call a dialog or new window
(such as a Trend Display window, or Point Attributes
dialog) cannot be performed. The Display’s window cannot be resized. No menu or
toolbars are available.

20 OSI Software, Inc.

 Refresh Button (IE Only)
Clicking the Refresh button on the IE toolbar forces the PI-ActiveView Control to
download the Display using the DisplayURL and, if present, ServerINIURL Properties.
Any cached versions of the Display are discarded.

Back and Forward Buttons (IE Only)

Once a page is downloaded, the PI-ActiveView Control will use cached information
when the user clicks either the Back or Forward button in IE, unless the page has expired.

Expiration (IE Only)

The expiration is controlled by the registry key
"HKEY_LOCAL_MACHINE\Software\PISystem\PI-ActiveView\PDITTL." This is a
string representing the number of seconds that a Display should remain in the cache
before being refreshed.
If this registry entry is not present, then a timer is set when a Display is loaded. This will
count down until the browser is closed, until 6 more Displays are loaded, or until 24
hours pass. Upon expiration, the Display will be removed from the cache.

PI-ActiveView Developer’s Guide 21

 Chapter 5.
Planning to Use PI-ActiveView

Developer's Kit
When you have installed PI-ActiveView from the original setup kit on the CD (or
downloaded directly from OSI Software), you have installed the Developer’s Kit version
of the product. It includes the extra tools in a subdirectory called acview/webdev.
To produce a Web site containing PI-ActiveView content, a developer will complete these
procedures.
1. Resolve installation, security, and content choices.
2. Create one or more PI Display Documents in the PI-ProcessBook application to
present dynamic data from the PI Data Archive. Alternatively, these may be
converted from displays in existing ProcessBooks by using a file called
Export.pdi.
3. Build cabinet files for downloading parameters and for installing PI-ActiveView on
the user's PC.
Or, install PI-ActiveView on each user's PC from the setup kit. Using the setup kit is
discussed under Installation.
4. Develop at least one HTML page (or an ASP) incorporating the PI-ActiveView
Control, pointing to a PI Display Document, and, optionally, pointing to the cabinet
files for the installation. .
For convenience, you may wish to organize a Web site with one location for the cabinet
files, which are only used for downloading software, and a variety of locations for the
HTML pages with the embedded PI Display Documents.
The Developer’s Kit assists you to incorporate PI-ActiveView into new or existing Web
pages. It includes a CabWizard for preparing cabinet files, signed cab files from OSI
Software, an export utility called export.pdi, a sample HTML page called
Sample.htm, and other files as well as a Staging subdirectory. Staging contains a
sample Web site for downloading PI-ActiveView to end-users. If you wish to use the files
in staging, you will need to modify them to function correctly on your Web site.

Installation Considerations
You will need to decide whether users will be permitted to download and install PI-
ActiveView from a Web site or whether you will choose to install the software directly.
Administrator privileges on the PC are required to install PI-ActiveView. A software
license is required for each user.
Additional information about user installation is found under Software Installation.

PI-ActiveView Developer’s Guide 23

 Security Choices

Access to PI Data
Users will need a pilogin.ini file with a user name and the Server name in order to
access the PI Data Archive. Automated downloading of pilogin.ini can be achieved
using ServerIniURL Property of the control. If the PI Server requires a password, the user
will be prompted to enter one. For more information, see the Automation section.

Access to Web Sites

Please consult your documentation to determine the appropriate settings for Netscape
Navigator. Automated downloading of PI-ActiveView will not be possible.
Internet Explorer security settings can determine whether users can view PI Display
Documents and whether users may download and install PI-ActiveView. These settings
can be viewed by opening IE and selecting in IE 4x View | Internet Options | Security
or, in IE 5, Tools | Internet Options | Security.
For HTML pages distributed through a corporate Intranet, you may want to use a
different zone with different settings than for external sites.
Table 1 indicates the security levels that are available for IE.
Setting Response
High (default) Will not download or run ActiveX Controls,
either signed or unsigned. Will not run PI-
ActiveView.
Medium The user will be prompted to download
digitally signed components. Unsigned
components will not be allowed to
download.
Low Signed components will be downloaded
without any user interaction. The user will
be prompted to download unsigned
components.

PI-ActiveView Developer’s Guide 24

 Chapter 6.
Creating PI Display Documents

Creating PI Display Documents

By using PI-ProcessBook 2.0 or greater, you can create and save independent files to
present PI data. These files have a .PDI file name extension and are called PI Display
Documents.
The PI Display Documents may include additional functionality for the user through
VBA scripting.
PI-BatchView trends and PI-SQC charts may be included in a Display. These require
installation of the PI-BatchView-for-ActiveView and PI-SQC-for-ActiveView products,
respectively, which may be accomplished automatically through cabinet files (discussed
under Components). You may also install these products through individual setup kits.
In designing PI Display Documents in PI-ProcessBook, consider the guidelines in the
following sections.

Sizing the ActiveView Control and the PI Display Document

PI-ActiveView does not permit scrolling through a PI Display Document. You will need
to coordinate the size of the document with the PI-ActiveView Control Width and Height
properties. In general, design the display to fill a maximum of one screen.
The aspect ratio of the PI Display Document will be maintained when it is displayed by
the PI-ActiveView Control. In other words, the whole PI Display Document will appear,
no matter how small the space provided.

Embedded Objects
Any ActiveX controls within a PI Display Document must be installed separately on
every user’s PC.
Embedded ActiveX controls, such as dropdown boxes, usually cannot resize when the PI
Display Document resizes to fit the PI-ActiveView Control.

Fonts
Select fonts for the PI Display Document that are typically available on each user's PC.

ADO
If you include ADO data through PI Data Sets in the PI Display Document, you must
ensure that the ODBC data source is configured on each user's PC.

Commands
Save, SaveAs, and Print Preview may not be used in VBA script.

PI-ActiveView Developer’s Guide 25

 Help Buttons for Users
A developer may include a help button to access online help for using the features of the
PI Display Document. Help for Users is included in a set of two files, acview.hlp and
acview.cnt, which are loaded by setup.exe. The automatic installation download
process does not include a help file.

Buttons to Other Displays or Applications

Use caution in including buttons to other displays and applications in your PI Display
Document because these buttons look for specific or relative paths in the file system,
which may differ among users. If the links are among a set of files that are stored
together, the links will work.
One alternative approach is to put buttons in the HTML page that call up other displays
by re-setting the DisplayURL property of the PI-ActiveView Control.
PI-ActiveView can use links among independent displays, but cannot use links to
displays stored within a ProcessBook.

Converting Existing Displays

PI Display Documents may be converted from existing displays in ProcessBooks. To
convert all of the displays in an existing ProcessBook, follow this procedure:
1. Be sure that disp.bmp is in the same directory as export.pdi (usually
acview/webdev).
2. Open PI-ProcessBook.
3. Open a ProcessBook of displays. A ProcessBook file has an extension of .piw.
4. Open export.pdi..
5. Click the Export button on the display.
6. Enter a destination directory.
The VBA script included in export.pdi will produce a separate PI Display Document
for each display in the ProcessBook. Feel free to adapt the code in export.pdi to your
specific needs.
You can view these displays through the sample Web page called pbhome.htm provided
in the staging subdirectory.

PI-ActiveView Developer’s Guide 26

 Chapter 7.
Building Cabinet Files

Building Cabinet Files

The Cabinet Wizard (CabWizard.exe) is a utility included in the acview/webdev
directory of PI-ActiveView. It allows you to build cabinet files that can install and
configure PI-ActiveView on a user’s PC automatically.
Note: Internet Explorer is able to download these files; Netscape Navigator is not.
This CabWizard is used to specify the necessary information to create cabinet ( .cab)
files and store them. Cabinet files are a particular format used in downloading
information to install PI-ActiveView from a corporate Intranet.
To use the CabWizard, you will need:

 A temporary storage location for the .cab files and a final location from which the
cab files are available to be downloaded. These may be the same.
 Protocol to access the cab files: http, ftp, unc, or local. Http is suggested.
 A pilogin.ini file for PI Servers to be accessed.
In addition to a PI Independent Display File, the CabWizardwill incorporate several types
of components that you may wish to display on your Web pages, including PI-
BatchView trends and PI-SQC charts. Components are discussed in the next section.
Optionally, the CabWizard will allow you to apply your digital signature to the created
.cab files. You must have installed Microsoft IE 4 Service Pack 1 or greater. The digital
signature files must be created on a PC with the same version of IE as the developer PC.

Additional Components
The CabWizard has a special input screen for specifying additional components, such as
additional ActiveX controls, .Dlls, or a pre-built .cab file containing a component,
supporting files, and an installation program.
PI-ActiveView also provides special installation kits for PI-BatchView trends and PI-
SQC charts. The kits include the correct .Dll file. You select these through the
Additional Component input screen. The user need not have PI-SQC or PI-BatchView
installed but must have a license for them.
To distribute a component that you have built containing a cabinet file with an .inf file,
you cannot use the CabWizard. Instead, modify the HTML page. This technique is
discussed under Adding a Component with an INF File.

PI-ActiveView Developer’s Guide 27

 Using the Cabinet Wizard
The following instructions assume that your Developer's Kit, including the .cab files
supplied by OSI Software, is installed in the <targetdir>/acview/webdev
subdirectory. Do not separate files from the Developer's Kit into different directories.
1. Run CabWizard.exe.

2. On the Location of Cab Files dialog, select the protocol that will be used in
acview.inf to point to the set of .cab files. The default protocol is http.
Note: When you define the CODEBASE Attribute of the OBJECT tag in HTML, you
may use only http or ftp.

PI-ActiveView Developer’s Guide 28

 3. Enter Full Path. Enter the path to the final, production location where the set of cab
files will be placed for downloading. This is the location that will be used in
acview.inf to point to the set of .cab files.

4. Enter Deploy Location. Indicate where the CabWizard should place the set of .cab
files at the conclusion of the Wizard. This includes the two files that CabWizard
builds and the ones provided by the PI-ActiveView application or by you later in the
Wizard. The immediate location may or may not be different from the final location.
You may find it convenient to use the Staging subdirectory where your PI-
ActiveView Developer’s Kit is loaded.
5. If the CabWizard cannot find acview.inf, the next screen requests the current
location of acview.inf. This file is normally installed into <targetdir>/acview/webdev
and should not be edited or moved.
6. On the PI Server Information dialog enter the full path and filename of the .ini file
containing the necessary PI Server information. The default value for this entry in the
CabWizard is taken from the pilogin.ini that was installed with the Developer’s
Kit. The CabWizard will combine pilogin.ini, mergepilogin.exe, and
pipc.ini into pilogin.cab.

It is important that server names in the pilogin.ini file be entered using the fully
qualified hostname/path used in DNS lookups (e.g., hostname.thecompany.com).
If a user already has a pilogin.ini file before PI-ActiveView is downloaded and
installed, then any new server names will be added to the existing file. The default
server choice and the user name(s) in any existing pilogin.ini file will not be
altered.
If your server information is already available on the user's PC or if you are
downloading the ServerIniURL Property, then you may leave this blank and creation
of pilogin.cab will be omitted.

PI-ActiveView Developer’s Guide 29

Chapter 7 Building Cabinet Files
Note: After a user installs PI-ActiveView, pilogin.ini will not be downloaded
again unless the Web site contains a new version of the PI-ActiveView

7. The next screen asks for your digital signature information. This is optional. You
can’t use this page (and it won’t appear) unless you are using Microsoft IE 4.0
Service Pack 1 or later. The computer where your private key and signature files are
stored must be using the same version of IE as your computer.

Either skip this page or enter the path and filename of the signature file and of the
private key file.

30 OSI Software, Inc.

 If you enter Digital Signature information, the acviewinf.cab file, the
pilogin.cab file, and any cab files created through the Additional Components
screen (which appears later) will be signed.
8. The Additional Components dialog is used to incorporate other components in the
automated download, such as other controls, .dll files, executable files, or .cab
files. Components needed for BatchView Trends or PI-SQC charts may be added
here. You may select an installation order for each component.

9. Verify your selections on the final screen, click Finish, and the Cabinet Wizard will
complete acviewinf.cab and pilogin.cab in the target directory that you specified
earlier.

PI-ActiveView Developer’s Guide 31

Chapter 7 Building Cabinet Files

Once you have run the Cabinet Wizard, the seven necessary .cab files for a PI-
ActiveView installation will be located in the deploy directory that you specified:
Web Installation Files Contents
Acviewinf.cab Acview.inf, which determines which files to install and how
to install them during a download.
Cleanup.cab Cleanup.cab contains code to remove temporary directories
and create an uninstall key.
InstallAV.cab acview.exe application, supporting .DLLs, and installation
routines. No help files are included to save ‘space’ (size
constraints) during download.
Outervba.cab VBA files and installation routines needed by acview.exe.
Piado.cab piado.cab contains ADO files and installation routines.
Pilogin.cab MergePilogin.exe is an application that merges the
appropriate PI Server information onto the user’s PC during
download. The Cabinet Wizard combines
mergepilogin.exe and webpilogin.ini, into
pilogin.cab.
Pbdctrl.cab pbdctrl.ocx, the PI-ActiveView Control

When you are ready to put the Web page into production and begin installing the user
version of PI-ActiveView, you can move the cab files from the deploy directory to the
final location.

32 OSI Software, Inc.

 If You Have a Firewall
If your location does not permit Internet access, automated downloads for user installs
will not succeed. The acview.inf file created by the CabWizard points to a Microsoft
web site to obtain the correct version of MFC DLLs.
Instead of accessing the Internet during the download installation, you can obtain the
mfc42.cab file from Microsoft and save it to your own Web server. Then, you can
modify acview.inf to point to your server. The Microsoft Web site location is
http://activex.microsoft.com/controls/vc/mfc42.cab.
1. Extract the file acview.inf from the file acviewinf.cab created by the
CabWizard.
2. Replace the external Web site reference in this line to point to your Web server:
File-win32-x86=http://activex.microsoft.com/controls/vc/mfc42.cab

The resulting line would look like this:

File-win32-x86=http://<MyWebServer>/<PI-ActiveViewDeploymentArea>/mfc42.cab

3. Recreate the acviewinf.cab file by running the following command in an MS-DOS

window.
\pipc\acview\webdev\cabarc -s 6144 n acviewinf.cab acview.inf

4. Move acviewinf.cab to the Web server deployment area.

PI-ActiveView Developer’s Guide 33

 Chapter 8.
Developing the Web Page

Developing the Web Page

A full discussion of Web page creation is beyond the scope of this manual. However,
information pertinent to PI-ActiveView is included here.
There are three steps to developing a Web page with PI-ActiveView content:

1. Create an HTML Web page.

2. Incorporate the PI-ActiveView Control, PbdCrtl.ocx, in the HTML page and set
the control's DisplayURL property to the intended location of the Display file.
Note: The Display file may be placed in a separate location from the Web. However,
the DisplayURL property of the PI-ActiveView Control, PbdCrtl.ocx, that you set
in this step must point to the exact location of the Display file.

3. Copy files as follows:

 Copy the Display file into the location designated by the DisplayURL property of
PbdCrtl.ocx.
 If you are permitting automated installation, prepare the .cab files and copy them
from their deploy directory, usually <targetdir>/acview/webdev, into the Web
server at the production location specified in the Cabinet Wizard.
 Put the Web page on the server.

If you are unsure how to create an HTML page incorporating a control, you may adapt
the Sample.htm provided in the webdev directory. It is a Web page with an embedded
PI-ActiveView Control using VBScript. To use this file, you need to provide the location
of the .PDI file and, if you are using automated downloads, acviewINF.CAB files.
Alternatively, you may use a software tool, such as Microsoft FrontPage. Information
on using FrontPage2000 is described later in this document. Directions are given in the
section called Embedding a Display into an HTML Page Using FrontPage 2000.

Resizing Displays
Browser windows may be resized. In order for a Display to resize appropriately as
Browser window sizes change, you will need to set the Height and Width Properties of an
OBJECT TAG within the HTML. This can be done either with pixels or with
percentages. Examples are given below.
Note: If you resize with pixels, the size of the display will remain constant, regardless of
Browser window size. If you resize with percentages, as the Browser window changes
size, the display will adjust as well. The display will retain its basic proportions.
With Pixels:

PI-ActiveView Developer’s Guide 35

 <object ID="Pbd1" WIDTH="382" HEIGHT="191"
CLASSID="CLSID:4F26B906-2854-11D1-9597-00A0C931BFC8">

With Percentages:
<object ID="Pbd1" WIDTH="80%" HEIGHT="50%"
CLASSID="CLSID:4F26B906-2854-11D1-9597-00A0C931BFC8">

Using Netscape Navigator

PI-ActiveView has been written to take advantage of the latest technologies including
ActiveX controls and the ability to download these controls over the Internet. Netscape
Navigator does not have the native ability to view ActiveX controls at the time of this
software's release (Navigator version 4.7). To run ActiveX controls, a plug-in that
enables Netscape to run ActiveX controls is required.
If your organization uses Netscape Navigator and you wish to download PI-ActiveView
to users from a Web site, you will need to prepare a local setup kit in a downloadable,
self-extracting executable file. One tool for doing this is InstallShield's Package for the
Web.

Downloading New PI Server Information

If you expect to change or add PI Data Archive server names after PI-ActiveView
software is downloaded to users, you may set the ServerIniURL property of the PI-
ActiveView Control to point to a particular pilogin.ini file. Then, before a new
display is loaded into a user's PC, any new server information can also be downloaded
and merged into the user's pilogin.ini file.
This is a good tool to use when there are multiple PI Servers in the corporation, and a
special or different username/password is used for PI-ActiveView connections.
If you using DisplayURL and ServerIniURL, it is better to list ServerIniURL first so
that the connection to data is made before the Display is launched.
The pilogin.ini file may have another filename, but it must be in the same format as a
standard pilogin.ini file.
<object classid="clsid:4F26B906-2854-11D1-9597-00A0C931BFC8"
id="Pbd1" width="192" height="192">
<param name="ServerIniURL" value="
http://servername/webinstall/pilogin.ini">
</object>

Or,
<!--
Sub window_onLoad()
Pbd1.ServerIniURL = "http://servername/webinstall/pilogin.ini"
Pbd1.DisplayURL = "http://servername/displays/anydisplay.pdi"
end sub
-->

Adding a Component with an .inf File

PI-ActiveView Developer’s Guide 36

 If you are including a cabinet file with an embedded .inf file, do not use the
CabWizard. Instead, add the supplied OBJECT tag into the HTML page containing the
PI ActiveView Control OBJECT tag.

Embedding a Display into an HTML Page Using FrontPage2000

The following instructions assume that the reader has some knowledge of
FrontPage2000.
1. Create a new page from the FrontPage Explorer.
2. Insert the PI-ActiveView Control by selecting the Insert | Advanced | ActiveX
Control… menu item
3. Select the PI-ActiveView Control from the Pick a Control combo box. If you do not
see PI-ActiveView Control, click the customize button and select it there first.

4. You will see a flashing vertical line on Front Page as well as the words “DisplayURL
is empty.” The control itself is invisible. With your cursor on the words click the right
mouse to see the menu and choose ActiveX Properties.
The ActiveX Control Properties Page appears. It has 4 Tabs: Display URL, Server
Ini, Object Tag and Parameters.

PI-ActiveView Developer’s Guide 37

Chapter 8 Developing the Web Page

Figure 14 ActiveX Control Properties dialog, DisplayURL tab

5. Enter the path to the Display file in the DisplayURL property. This will usually take
the form of http://MyWebServer/mylocation/MyDisplay.PDI)
6. Tab to the Server Ini Page. This setting is used to add a server, in case the user does
not have that server in a pilogin.ini file. It is optional.

Figure 15 ActiveX Control Properties dialog, Server Ini tab

7. Enter the path to the PI Data Archive in the ServerINIURL property. This will usually
take the form of http://MyWebServer/mylocation/MyPDI.PDI).
8. Tab to the Object Tag Page. Enter a name for this instance of the Control. (You may
add multiple instances of the Control to your page, each pointing to a different
display document.). You will need this Name Property if you plan on adding a script
to the Web page that will access the PI-ActiveView Control.

38 OSI Software, Inc.

 Figure 16 ActiveX Control Properties dialog Object Tag tab
9. You can change the other values on the dialog to modify the control size and other
appearance attributes. It is recommended that the Width and Height attributes be set
to a minimum of 550 and 350 respectively, to allow easy viewing of the PI Display
Documentfile. You may also use percents for the Width and Height attributes.
10. Enter a Code Source (optional). This entry points to the location where
AcviewINF.CAB is located. The entry will be similar to:
http://MyWebServer/Mylocation/AcviewINF.CAB#Version=2,1,2,1
FrontPage will translate this entry into HTML inserted into the Object Tag as follows:
codebase="http://MyWebServer/Mylocation/AcviewINF.CAB#Version=2,1,2,1"

The version qualifier insures that the correct version of the PI-ActiveView Control is
loaded on the user's PC. This is necessary because the user might have had an earlier
version, such as 2,0,0,5 installed by PI-ProcessBook 2.0.
11. Parameters tab. No entries are required.
12. Click the OK button to apply the Properties and then click the Front Page Save icon
to save the file. The .PDI file will now be displayed in the FrontPage Preview
window. The HTML code window will display code that is similar to the following
sample code:
<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>New Page 2</title>
</head>

<body>

<p>

PI-ActiveView Developer’s Guide 39

Chapter 8 Developing the Web Page
<object classid="clsid:4F26B906-2854-11D1-9597-00A0C931BFC8" id="Pbd1"
width="25%" height="20%">
<param name="DisplayURL" value="http:\Front Page webs\content\PI-
ActiveView\TANK LEVELS.PDI">
<param name="ServerIniURL" value>
</object>
</p>

</body>

</html>

13. Place the .htm file on the Web site.

40 OSI Software, Inc.

 Chapter 9.
Automation

Automation Interface
The PI-ActiveView Control exposes a property that provides
access to the full object model of the Display that it currently
contains. This allows an HTML script to control the Display as
one would control a PI-ProcessBook Display through remote
automation. Although methods requiring dialogs or new
windows are not allowed from normal view mode, certain
automation methods may cause dialogs to appear.

Control Characteristics
The Control is self-registering.
Property Pages Support for Property Pages is included;
custom property pages are accessible, one for the DisplayURL property and the other for
the ServerIniURL property.
Data Binding None
Window/Windowless This is a windowed control.
Active/Inactive The PI-ActiveView Control does not support IPointerInactive. The
Control is activated when visible.
Quick Activation Support None (IQuickActivate not implemented.)
Drag/Drop Support None
Sizing Support None

Container Requirements
Supported Containers

 InternetExplorer V3.02 or greater

 PI-ProcessBook V2.0 or greater on WinNT 4.0 SP3 or greater, Windows ’95, or
Windows ’98.
 Microsoft Visual Basic
 Microsoft Office applications can also be used as containers, e.g., Excel and Word.

Container Interface Requirements Basic OCX container interfaces.

Sizing Support The Display is sized to fit within the boundaries of the Control specified
in the PI-ActiveView HTML OBJECT tag. The Control then uses a "fit-all" algorithm to
display all symbols contained in the Display while preserving the aspect ratio.
Ambient Properties None used.

PI-ActiveView Developer’s Guide 41

 Event implementation None required.

Internet Requirements
Digital Signatures The Control is digitally signed by OSI Software, Inc.
Control Size None.
Component Categories The Control is considered safe for Initialization.

Properties, Methods, and Events

The control has the following properties, methods, and events:

Properties Description
BuildDateStamp Read-only. Provides the date that the control was built.

Display Read-only. Accesses the automation dispatch interface of the opened

display.
DisplayURL Informs the control where to locate the PDI file to display. This
parameter is required to display a PDI.
ReadyState Read-only.
Loading – the control is accessing the server.
Interactive – AV is loading the PDI.
Ready – informs Microsoft Internet Explorer (IE) to stop spinning the
world icon.
ServerIniURL Informs the control where the PI server information is stored. This is
an optional parameter.

Method Description
AboutBox Displays version information about the Control.

Events Description
BeforeConnection Fires before a server connection is attempted. This allows the
programmer to alter the Username or password so that logging into
the PI Data Archive is not apparent to the user.
ConnectionFailed Fires if the connection to any PI server fails. It fires before the user
interface for entering the username and password is displayed.
ReadyStateChange The ReadyState property transitions trigger the ReadyStateChange
stock event.

IE Supported Events
The Control provides support for the IE Back, Forward and Refresh methods.

AboutBox Method
This method displays version information about the Control.

Example
Displays PI-ActiveView Control AboutBox.
Sub btnAboutBox_onclick
pbd1.AboutBox()

PI-ActiveView Developer’s Guide 42

 End Sub

BeforeConnection Event
This event occurs before a connection to the PI Server is attempted. This allows the
programmer to alter the User name and/or password so that logging into the PI Data
Archive is not apparent to the user. When the call returns the connection is processed.

Format
BeforeConnection (myParam as BCParam)

Example
The following is an example of using JavaScript to use the security events:
<html>
<head>
<script LANGUAGE="VBScript">
<!--
Sub window_onLoad()
Pbd1.DisplayURL = "c:\<your pdi file>.pdi"
end sub
-->
</script>
<SCRIPT ID=clientEventHandlersJS LANGUAGE=javascript>
<!--
function Pbd1_BeforeConnection(pParam )
{
pParam.UserName = "MyUserName";
pParam.Password = "My Password";
}
//-->
</SCRIPT>
<SCRIPT LANGUAGE=javascript FOR=Pbd1
EVENT=BeforeConnection(pParam)>
<!--
Pbd1_BeforeConnection(pParam)
//-->
</SCRIPT>
</script>
<meta NAME="GENERATOR" Content="Microsoft FrontPage 3.0">
<meta HTTP-EQUIV="Content-Type" content="text/html; charset=iso-
8859-1">
<title>Test Component Download</title>
</head>
<body>
<p>
<object ID="Pbd1" WIDTH="700" HEIGHT="510"

PI-ActiveView Developer’s Guide 43

Chapter 9 Automation
CLASSID="CLSID:4F26B906-2854-11D1-9597-00A0C931BFC8">
</object>
</p>

<p>Some other text o go with the PDI. </p>

</body>
</html>

The following example uses the events with VBScript. To use, simply replace the code
between the <head> and </head> tags above with the following code:
<html>
<head>

<script LANGUAGE="VBScript">
<!--
Sub window_onLoad()

Pbd1.DisplayURL = "c:\<MyPDIFile>.pdi"
end sub
-->
</script>
<script LANGUAGE="VBScript">
<!--
Sub Pbd1_BeforeConnection(pParam)

pParam.Username = "MyUserName"
pParam.Password = "My Password"
End Sub
-->
</script>
</head>

BCParam
This object is passed to the container as a parameter to the BeforeConnection event. The
BCParam object is then used to read and update the parameters.
BCParam.Server
Server is a string that represents the server name. This parameter can only be read.
BCParam.Username
Username is a string that represents the user that is trying to log on to the server. The
value is initialized to the user logging on and can be modified.
BCParam.Password
Password is a string that represents the password for the user trying to log on to the
server. The value is initialized to the user’s password logging on and can be modified.
BCParam.ConnectString

44 OSI Software, Inc.

 This parameter is reserved for future use.
BCParam.MyData
This parameter is reserved for future use.

BuildDateStamp Property
This read-only property provides the date that the Control was built.

Example
Here is an example to set TextBox to BuildDateStamp of the Control:
Sub btnBuildDateStamp_onclick
txtBuildDateStamp.value = "This control was built on " &
trim(pbd1.BuildDateStamp)
End Sub

ConnectionFailed Event
If connection to the PI Server fails, no login dialog is displayed. This will allow the script
to retry programmatically without showing the login dialog. The event occurs separately
for each different PI Server connection attempted.

Format
ConnectionFailed (myParam as CFParam)

Example
The following is an example of using JavaScript to use the security events:
<html>
<head>
<script LANGUAGE="VBScript">
<!--
Sub window_onLoad()
Pbd1.DisplayURL = "c:\<your pdi file>.pdi"
end sub
-->
</script>
<SCRIPT ID=clientEventHandlersJS LANGUAGE=javascript>

<!--
function Pbd1_ConnectionFailed(pParam )
{
alert (pParam.Server);

pParam.UserName = "MyUserName";
pParam.Password = "My Password";
}

PI-ActiveView Developer’s Guide 45

Chapter 9 Automation

//-->
</SCRIPT>
<SCRIPT LANGUAGE=javascript FOR=Pbd1
EVENT=ConnectionFailed(pParam)>
<!--
Pbd1_ConnectionFailed(pParam)
//-->
</SCRIPT>
<meta NAME="GENERATOR" Content="Microsoft FrontPage 3.0">
<meta HTTP-EQUIV="Content-Type" content="text/html; charset=iso-
8859-1">
<title>Test Component Download</title>
</head>
<body>
<p>
<object ID="Pbd1" WIDTH="700" HEIGHT="510"
CLASSID="CLSID:4F26B906-2854-11D1-9597-00A0C931BFC8">
</object>
</p>

<p>Some other text o go with the PDI. </p>

</body>
</html>

The following example uses the events with VBScript. To use, simply replace the code
between the <head> and </head> tags above with the following code:

<html>
<head>

<script LANGUAGE="VBScript">
<!--
Sub window_onLoad()

Pbd1.DisplayURL = "c:\<MyPDIFile>.pdi"
end sub
-->
</script>
<script LANGUAGE="VBScript">
<!--
Sub Pbd1_ConnectionFailed(pParam)

pParam.Username = "MyUserName"
pParam.Password = "My Password"

46 OSI Software, Inc.

 End Sub

-->
</script></head>

CFParam
This object is passed to the container as a parameter to the ConnectionFailed event. The
CFParam object is then used to read and update the parameters.
JavaScript cannot take simple types by reference as parameters. The CFParam object is
used to get around this problem.
CFParam.Server
Server is a string that represents the server name. This parameter can only be read.
CFParam.Username
Username is a string that represents the user that is trying to log on to the server. The
value is initialized to the user logging on and can be modified.
CFParam.Password
Password is a string that represents the password for the user trying to log on to the
server. The value is initialized to the user’s password logging on and can be modified.
CFParam.ConnectString
This parameter is reserved for future use.
CFParam.Retry
This parameter specifies an action taken when the event returns. The possible actions are
as follows.
 pbConnectRetry (a value of 0) Retry connection to PI Server.
 pbConnectDefault (a value of 1) Return control to PI-ActiveView.
 pbConnectFail (a value of 2) Fail the connection.
Note: The Developer needs to use the integer values for these constants or to define
them within their scripts. These values can also be looked up in the VB Object Browser.
CFParam.MyData
This parameter is reserved for future use.

Display Property
The Display is the object class that represents the encapsulation of a single ProcessBook
display. This object is the PI-ProcessBook Display object and can be manipulated in the
same manner.
The Display Property is the dispatch interface of the opened Display. It may be ‘Nothing’
(in VB terms) if the loading of the Display failed. VB code should always check for this
or handle errors appropriately.

Examples
Three examples for accessing the Display object of the opened Display are shown below:
MyControl.Display.SetTimeRange “*-4h”, “*-1h”

PI-ActiveView Developer’s Guide 47

Chapter 9 Automation
MyControl.Display.BackgroundColor = RGB(256,0,0) ‘Red
Dim MyTime as string
MyTime = MyControl.MyDisplay.EndTime

DisplayURL Property
The DisplayURL property, which is read-write, specifies the location of the PI-
ProcessBook Display file. This property must be an absolute, rather than a relative,
reference.
It can be set to a URL string. The URL string should not contain any escape characters.
HTTP or FTP protocols (services) are supported. You may also use a UNC path to such a
file, in which case it must not have any protocol prefix.
When the property is set, the Control first determines if the Display (PI Display
Document) is already open. The last five Displays that have been opened (for the current
'lifetime' of the Control) are cached in internal memory by the Control. If the Display is
cached, it is activated.
Otherwise, the Control attempts to open the file. If it is not a UNC file, it attempts to
create a cache on the local hard drive. A cache entry is created in the directory used to
store temporary Internet files. (The location of this directory is an option available
through an Internet browser.) The file is copied to the cache, the cache is committed, and
the file is retrieved from the cache, locking the cache entry. The file is loaded via the
IPersistFile interface of the display. All cache operations are done using the Win32
Internet functions.
If the attempt to locate, cache or load a display file fails, the Control displays an error
message in its window and the Display will not be displayed.
If five Displays are already open, the least recently opened Display is closed, thereby
destroying that Display. All open Displays are destroyed when the Control itself is
destroyed.

Examples:
To set the display URL:
MyControl.DisplayURL = http://www.MyServer.Com/MyDisplay.PDI

Example 1 gets DisplayURL Property from the Control

Sub btnGetDisplayURL_onclick
Dim strCurDisplayURL, strNewDisplayURL, fso

'Get the Current DisplayURL from the PI-ActiveView Control

strCurDisplayURL = trim(pbd1.DisplayURL)
if len(strCurDisplayURL) > 0 then
txtDisplayURL.value = strCurDisplayURL
else
txtDisplayURL.value = "Current Display URL is not set"
end if
End Sub

Example 2 sets DisplayURL with string from the textarea.

Sub btnSetDisplayURL_onclick
Dim strCurDisplayURL, strNewDisplayURL, fso

48 OSI Software, Inc.

 'Get the Current DisplayURL from the PI-ActiveView Control
strCurDisplayURL = pbd1.DisplayURL
'New DisplayURL is in the text box
strNewDisplayURL = trim(txtDisplayURL.value)

if (Len(strNewDisplayURL) > 0) and (strNewDisplayURL <>

strCurDisplayURL) then
' NOTE -> Should add code here to check if the new PDI
referenced exists or not.

pbd1.DisplayURL = strNewDisplayURL
end if

End Sub

ReadyState Property
The read-only property indicates the state of the Control, which may be Loading,
Interactive, or Ready, as shown below:
pbReadyStateLoading (a value of 1) The Control is being constructed. Once its
window is created, it becomes Interactive.

pbReadyStateInteractive (a value of 3) PI-ActiveView is loading the Display.

PbReadyStateComplete (a value of 4) The Display is viewable. The Control

informs Microsoft Internet Explorer (IE) to stop spinning the world icon.
The state transitions trigger the ReadyStateChange stock event.

Note: The Developer needs to use the integer values for these constants or to define
them within their scripts. These values can also be looked up in the VB Object Browser.

ReadyStateChange Event
When the Control is initially constructed, its state is ‘Loading’. Once its window is
created, it enters an ‘Interactive’ state. When it completes the display of a PI Display
Document or fails to find the Display, it enters the ‘Ready’ state.
Each state transition triggers the ReadyStateChange stock event.

Format
ReadyStateChange (nReadyState as pbReadyStateEnum)

Example
Sub Pbd1_ReadyStateChange(nReadyState)

Const pbReadyStateLoading=1

Const pbReadyStateInteractive=3

Const pbReadyStateComplete=4

PI-ActiveView Developer’s Guide 49

Chapter 9 Automation
Dim myTime, myValue, myStatus

If Pbd1.ReadyState = pbReadyStateComplete then

ThisDisplay.Trend.CurrentTrace = 1

myValue = ThisDisplay.Trend.GetValue(myTime, myStatus)

'now you can do something here with this value, time and
status

End If

End Sub

ServerIniURL Property
This property, which is optional, contains the location of the Pilogin.ini file that
contains PI Server information.
When its value is set or changes, the file that it points to is read and the values are merged
with the user’s Pilogin.INI file.

Examples
Example 1 gets ServerINIURL property from the Control

Sub btnGetServerINIURL_onclick
Dim strCurServerINIURL, strNewServerINIURL

'Get the Current DisplayURL from the PI-ActiveView Control

strCurServerINIURL = trim(pbd1.ServerINIURL)
if len(strCurServerINIURL) > 0 then
txtServerINIURL.value = strCurServerINIURL
else
txtServerINIURL.value = "Current Display URL is not set"
end if
End Sub

Example 2 sets ServerINIURL with string from the text area. The login information in the
web file is merged with existing information on the User's PC.
Sub btnSetServerINIURL_onclick
Dim strCurServerINIURL, strNewServerINIURL, fso

'Get the Current ServerINIURL from the PI-ActiveView Control

strCurServerINIURL = pbd1.ServerIniURL
'New ServerINIURL is in the textarea.
strNewServerINIURL = trim(txtServerINIURL.value)

if (Len(strNewServerINIURL) > 0) and (strNewServerINIURL <>

strCurServerINIURL) then
pbd1.ServerINIURL = strNewServerINIURL

50 OSI Software, Inc.

 end if
End Sub

Set DisplayURL to SIMPLE.PDI, and pilogin.ini'

Sub window_onload

Dim strPDI, iCount

if trim(pbd1.DisplayURL) = "" then

strPDI = document.url
iCount = len(strPDI) - 1

Do until iCount = 1
if right(strPDI, 1) = "/" then exit do
strPDI = Left(strPDI, iCount)
iCount = iCount - 1
Loop
pbd1.DisplayURL = strPDI & "simple.pdi"
end if
End Sub

-->
</SCRIPT>
</HEAD>
<BODY>

<P><FONT size=4>Various PI-ActiveView Display (pbd control)

Properties </FONT>
</P>

<P>
<OBJECT classid=clsid:4F26B906-2854-11D1-9597-00A0C931BFC8 id=pbd1
style="HEIGHT: 213px; LEFT: 0px; TOP: 0px; WIDTH: 412px"><PARAM NAME="DisplayURL"
VALUE=""><PARAM NAME="ServerIniURL" VALUE=""></OBJECT>
</P>

<P>
<INPUT
id=btnAboutBox
name=btnAboutBox
type=button
value="PI-ActiveView Control AboutBox()"
title ="Shows PI-ActiveView Display Object's About Box in a separate
pop-up Window.">&nbsp;
</P>

<P>
<INPUT
id=btnBuildDateStamp
name=btnBuildDateStamp
style="HEIGHT: 24px; WIDTH: 173px"

PI-ActiveView Developer’s Guide 51

Chapter 9 Automation
type=button
value="Displays BuildDateStamp"
title='BuildDateStamp "read-only" property returns the date that the Control
was built.'>
<TEXTAREA id=txtBuildDateStamp name=txtBuildDateStamp readOnly rows=1
style="HEIGHT: 23px; WIDTH: 312px" title="PlaceHolder for BuildDateStamp">
BuildDateStamp
</TEXTAREA>
</P>

<P>
<INPUT
id=btnGetDisplayURL
name=button3
title="This property specifies the location of the PI-ProcessBook Display
file. It can be set to a URL string. The URL string should not contain any
escape characters. HTTP or FTP protocols (services) are supported. You may
also use a UNC path to such a file, in which case it must not have any
protocol prefix."
type=button
value="Get DisplayURL">
<INPUT
id=txtDisplayURL

name=txtDisplayURL size=64 value=DisplayURL>

<INPUT
id=btnSetDisplayURL
name=btnSetDisplayURL
title="To set the display URL: MyControl.DisplayURL =
http://www.MyServer.Com/MyDisplay.PDI"
type=button
value="Set DisplayURL">
</P>

<P>
<INPUT
id=btnGetServerINIURL
name=btnGetServerINIURL
title="This property, which is optional, specifies the location of a
Pilogin.ini file that contains PI&nbsp;Server information. "
type=button
value="Get ServerINIURL">&nbsp;&nbsp;
<INPUT
id=txtServerINIURL
name=txtServerINIURL

size=64 value=ServerINIURL>
<INPUT
id=btnSetServerINIURL
name=btnSetServerINIURL
title = "To
set
the ServerINI URL: MyControl.ServerINIURL =
http://www.MyServer.Com/MyPILogin.ini" type=button value="Set
ServerINIURL">&nbsp;
</P>

</BODY>
</HTML>

52 OSI Software, Inc.

 Chapter 10.
Using Other Containers

Embedding PI Display Documents in Other Containers

In addition to HTML pages, the PI-ActiveView Control may be used in other containers
capable of supporting ActiveX controls, such as Microsoft Excel, or Visual Basic or VBA
forms. The Control essentially is a container for a PI Display Document object. The
Control starts the PI-ActiveView application, which is used as a local server for the
Display. The user can interact with the display from the Control’s window.
This means, for example, that you can view a dynamic display of PI data inside an Excel
spreadsheet. After you have loaded Excel and PI-ActiveView on a PC, the PI-ActiveView
Control will be available to be inserted into Excel. The procedure is given in the next
section; similar procedures would be used to embed a PI Display Document in other
containers.

Embedding a Display in a Spreadsheet

These are the steps to create and embed a PI Display Document in Excel through PI-
ActiveView:
1. Use PI-ProcessBook 2.0 or greater to create an independent PI Display Document
(.PDI file). Some design guidelines are suggested.
2. On a PC loaded with Excel install PI-ActiveView.
3. Open an Excel spreadsheet, right click on the Toolbars, and select the Controls
Toolbox. Select the "More Controls" button.
4. Click on the PI-ActiveView Control and click on the spreadsheet to establish the
location for the .PDI image. Adjust the size to be appropriate for the PI Display
Document.
5. Click on the location to select it. Right click to bring up the right mouse menu. Select
PI-ActiveView Control Object|Properties to bring up the PI-ActiveView Control
Properties dialog:
6. Use the browse button (or type in the text box) to select the path to the .PDI file that
you would like to view in the spreadsheet.
In VBA terminology, you are "setting the Display URL Property of the Control."
Click the OK button.

PI-ActiveView Developer’s Guide 53

 Figure 17 PI Display Document in an Excel Spreadsheet
7. In the spreadsheet, click the Design Mode button to switch from VBA design mode to
Run mode. This will allow the PI-ActiveView Control to load acview.exe and show
the PI Display Document file.
Once you have established a PI Display Document in a spreadsheet, you
can alter the document's size or position by clicking the Design Mode
button on the VBA Toolbar or Controls Toolbox and selecting the
Design Mode document.
button
You can use VBA to alter properties and even alter the Display itself
programmatically.

PI-ActiveView Developer’s Guide 54

 Chapter 11.
Troubleshooting

Before You Call OSI Tech Support

This chapter includes troubleshooting ideas for problems with PI-ActiveView
applications.
You may also find answers in the readme.htm file shipped with PI-ActiveView or on
the OSI Web site.
If you continue to experience technical problems with PI-ActiveView, OSI Technical
Support is available to help you. Please assemble the following information before you
call OSI Tech Support:
 What version of PI-ActiveView is installed?
 Was it installed through setup.exe or CAB files?
 What Browser, including version, are you using?
 What is your PC Operating System, including version?

Browser Security
Users will need to be able to run ActiveX controls on the HTML page. This ability may
be prohibited if the user's PC has excessively restrictive security settings. If the browser
is Netscape Navigator, a plug-in allowing ActiveX control use must be installed.
Security settings can be viewed for IE 4 by opening IE and selecting View | Internet
Options| Security. For IE 5, the Internet Options… menu item is under the Tools menu
item. There are four or more choices, High, Medium, Low, and Custom.
Go to the Custom settings option and click the Settings button. It lets you see what
selections are possible. In general, the guidelines below may be helpful:
If security settings are High, the user may get a message stating that Active X controls are
not allowed. The PI-ActiveView content on the page will not show for this user.
If security settings are Medium, the page and ActiveX controls will be displayed, and the
user will be warned each time a signed .cab file is downloaded. Unsigned .cab files
will not be downloaded.
Setting the security settings to Low allows the browser to download signed .cab files
and to ask about downloading unsigned .cab files. PI-ActiveView will be installed if
necessary, and the page and Active X controls will be displayed.

Accessing PI Data
In order to obtain data from the PI Data Archive, the user's pilogin.ini file must
contain both the server connection information and a user name. This information may

PI-ActiveView Developer’s Guide 55

 already be on the user’s PC, it may be installed when acview.exe is installed, or it may be
obtained through the ServerIniURL Property assigned in the Object Tag of the Control.

Web Installs on NT Machines

If a user on NT does not log on with administrative privilege, a software installation from
the Web site cannot occur because the install process needs to modify the registry If MFC
and ADO components are already on the PC, "Guest" privileges will be sufficient to
download PI-ActiveView software.

Viewing a Revised HTML Page

Depending on how the browser is configured, users may not see revisions to an HTML
page on the Web site.
IE uses a caching algorithm to speed up the display of Web pages. It checks for newer
versions of stored HTML pages according to a specification set on each PC. Among the
choices for this specification are: 'Every visit to the page,' 'Every time IE starts,' or
'Never.'

Changing the IE Specification for Checking for New Versions

To change the IE specification for checking for new versions of HTML pages, follow
these steps:
1. Close the HTML page containing the .PDI file and select the View | Internet
Options… menu item in IE 4.x. For IE 5, the Internet Options… menu item is
under the Tools menu item.
2. Click the Settings button in the Temporary Internet files frame.
3. Change the setting for checking new versions and click the OK button. Click OK
again.
4. Select the page again to load the updated HTML file.

How to Refresh a Particular Stored HTML Page or Display on a Page

On the IE main menu, click View|Refresh.

How to Delete Stored HTML Pages

To delete out-of-date cached Internet Files stored on a user's PC, follow these steps:
1. Close the HTML page containing the .PDI file and select the View | Internet
Options… menu item in IE 4.x. For IE 5, the Internet Options... menu item is
under the Tools menu item, General tab.
2. Click the Delete Files button. Click the OK button. Click OK again.
3. Select the HTML page again.

PI-ActiveView Developer’s Guide 56

 Digital Signature Problems in the CabWizard
If you are running IE4 and the digital signature screen of the CabWizard does not appear,
you may need to install IE4 Service Pack 1.
The computer where your private key and signature files are stored must be using the
same version of IE as your computer. Otherwise, the digital signature may not be applied.
To test whether CabWizard can use your signature file and key, use the following
procedure:
1. At a DOS prompt, switch to your acview/webdev directory.
2. Copy a dummy text file there.
3. Cabarc.exe should be available in your acview/webdev directory. Create a
dummy .cab file with this command:
cabarc 6144n <cabfilename>.cab <dummy filename>

4. Attempt to sign the dummy .cab file with this command:

signcode -y <private key filename> -spc <signature filename>
<cabfilename>

5. Enter the password when asked.

If this procedure is successful, the CabWizard may be used to sign files. (You may ignore
a message indicating there is no timestamp.)

PI-ActiveView Developer’s Guide 57

 Chapter 12.
Glossary
Term What it means in this Developer’s Guide
ActiveData Objects (ADO) ActiveX implementation of ODBC for the Internet
ActiveX control An element of the user interface that is based on Microsoft’s
ActiveX technology An ActiveX control has a filename ending
in .ocx.
Active Server Pages (ASPs) Scripted HTML documents supported by Microsoft Internet
Information Server.
Browser Software application used to display Internet material on a PC.
Cabinet files, .cab files Type of software files used to compress and download software
and data to a PC.
control See ActiveX control.
corporate intranet A collection of networks restricted to a limited group of users,
such as one corporation's employees or other limited group.
Developer Person (or team of persons) who develops a Web site displaying
PI data.
Digital Signature A means of labeling Web site files with the name of the company
responsible for developing them. Some companies do not permit
downloading unsigned files.
download Copy a file from a Web site to a user's PC.
HTML Hypertext Markup Language, which is used to prepare a Web
page. Files written in HTML code are stored on a Web server and
used by the browser to determine what to display on a PC
monitor.
intranet See corporate intranet
.ocx file See ActiveX Control.
ODBC Open Database Connectivity code allows access to data in a
relational database. Parts of ODBC must be installed in order to
use PI-ActiveView. ADO components are used to enable ODBC
access through Web pages.
page Web document written in HTMLcode, usually one of a collection
constituting a Web site.
.pdi file See PI Display Document.
PI-ActiveView Control ActiveX control (pbdctrl.ocx) that displays PI data in a PI
Display Document (.pdi file) on a user's PC.
PI Data Archive A repository of data for monitoring and analysis of control data,
lab data, specifications, etc. The PI Data Archive is connected to
the control system equipment and other data sources in a facility
and is updated whenever that equipment recognizes new events.
Sometimes called PI System.
PI Display Document, .PDI File that determines what PI data is viewed and the format in

PI-ActiveView Developer’s Guide 59

 file which it is presented.
.piw file PI-ProcessBook file, a set of displays
.twd file File used by VBA to improve performance when loading an
associated ActiveX control.
Trend A graphic depiction of data from a PI Data Archive over time.
URL Uniform Resource Locator, the specific address of a page or file
on a Web site.
User Person who browses the Web site
VBA Visual Basic for Applications software, parts of which must be
installed in order to use PI-ActiveView.
Web site A collection of HTMLpages developed as a whole, such as the
OSI Software Web site at www.osisoft.com.
Web server Computer where a Web siteis located. Its software accepts
browser requests for data or documents.

PI-ActiveView Developer’s Guide 60

 Index

.cab files, 20, 28

.Dlls
adding to Web sites, 27
.PDI file, 25, 26, 61
.piw file, 62
.twd file, 62
AboutBox Method, 42
access
PI data, 24
to PI Data, 58
to Web sites, 24, 57
Active Server Pages, 61
ActiveData Objects, 61
ActiveX control, 25, 55, 61
accessing pages with, 57
adding to Web sites, 27
Properties dialog, 38
acview.cnt, 26
acview.exe, 20
persistence of, 20
acview.ini, 16
Additional Components dialog, 28, 31
administrative privileges, 15, 16
ADO, 20, 25, 61
Authenticode technology, 20
automated installation, 35
Firewall, 33
for users, 14
Automation Interface, 20
Autorange scaling, 10
Back or Forward button, 21
BatchView trends
using with PI, 27
BCParam, 44, 45
BCParam.ConnectString, 42
BCParam.MyData, 42
BCParam.Password, 42
BCParam.Server, 42
BCParam.Username, 42
Before You Call OSI Tech Support, 57
BeforeConnection Event, 43, 44
Browser, 61
Security, 57
window size, 35
BuildDateStamp Property, 45
Building Cabinet Files, 27
Buttons, 26
to help files, 25
to other applications, 25
Cab Files
definition of, 27
Cabinet files, 20, 61
Digital Signatures, 20
CabWizard, 27

PI-ActiveView Developer’s Guide 61

 Digital Signature Problems in, 59
Using, 29, 30
cache, 20, 48
CFParam object, 47
CFParam.ConnectString, 42
CFParam.MyData, 42
CFParam.Password, 42
CFParam.Retry, 42
CFParam.Server, 42
CFParam.Username, 42
CODEBASE attribute, 19, 37
Components
with an .inf File, 37
Components
cab file containing, 27
installation program, 27
ConnectionFailed Event, 45, 47
container, 41, 55
requirements, 41, 42
Converting Existing Displays, 26
corporate intranet, 1, 5, 24, 61
Data Set
dynamic updating of, 7
Delete Stored Pages, 59
Deploy Location, 29
Developer, 61
Developer installation, 14
Developer's Kit
planning to use PI-ActiveView, 23
Developing the Web Page, 35
digital signature, 20, 61
problems, 59
software requirements for, 13
Display Property, 19, 47
Display Values
Trend Cursors, 8, 9
Displays, 26, 35
converting, 26
Export button, 26
how user sees, 17
sizing, 35
DisplayURL Property, 19, 35, 38, 41, 48
DLLs, 28
DNS, 29
documentation, 3
Downloading New PI Server Information, 36
Dynamic elements, 6
Embedded Objects, 25
Embedding
a Display in a Spreadsheet, 55
a Display into an HTML Page Using FrontPage2000, 37
PI Display Documents in Other Containers, 55
Excel Spreadsheet, 55, 56
expand a trend, 8
Export.pdi, 26
Firewall, 14, 33
impact on automated installation, 33
FrontPage2000, 37
Glossary, 61
guest privileges, 58

PI-ActiveView Developer’s Guide 62

 Height, 35, 39
ActiveX control property, 37
Help Buttons, 25
HTML, 61
HTML page
deleting from PC, 58
developing, 35
refresh, 58
revisions don't show, 58
If You Have a Firewall, 33
independent display files, 25
conversion to, 26
Inf file, 37
Information
Flow, 17
Installation, 14, 23
automated, 15
Considerations, 23
default, 14
from Web site, 14
Procedures, 14
users, 15
installation program, 27
for special components, 27
Interactive, 42, 49
Internet, 61
Options, 24
Internet Explorer security, 24
Intranet, 61
IPersistFile, 48
IPointerInactive, 41
JavaScript, 47
Loading, 42, 49
Mergepilogin.exe, 29, 32
Microsoft Internet Information Server, 61
Microsoft MFC.DLL, 20
Name Property, 37
Netscape Navigator, 20, 36
NT, 58
OBJECT, 39
OBJECT Tag, 19, 37, 41
Height Properties, 35
Width Properties, 35
ODBC, 61
core components loaded, 20
OSI Tech Support, 57
PARAM NAME, 37, 42
Password, 24, 42, 43, 45, 47
CFParam, 42
pbdctrl.ocx, 61
PI data, 58
access to, 58
viewing a PI Display Document with, 5
PI Data Archive, 6, 61
PI Display Document, 6, 62
creating, 25
embedding, 55
PI Server, 24, 29, 32
changing, 36

PI-ActiveView Developer’s Guide 63

Chapter 12 Glossary
Information dialog, 29
PI-ActiveView
Executable, 20
installation, 28
Planning to use, 23
PI-ActiveView Control, 19, 61
characteristics, 41
PI-BatchView trends, 27
using with PI, 27
pilogin.ini, 16, 27, 58
PROCBOOK.INI, 7
Product Package components, 3
Properties, Methods, and Events, 42
Property Pages, 41
ReadyState Property, 42, 49
ReadyStateChange Event, 42
Refresh, 21, 58
Stored page or display, 58
the cache of pages, 7
registry, 21, 58
Relative Time, 10, 11
release notes, 3
Resizing Displays, 35
Retry
CFParam, 47
Revised HTML Page, 58
Viewing, 58
runtime version for users, 13, 14
Sample.htm, 35
scan rate, 7
security
Browser, 57
Choices, 24
ServerIniURL Property, 36, 41, 50
setup.exe, 15
Shift Time Range, 9
signature
digital, 20
Software Installation, 13, 58
on NT machines, 58
SQC charts, 27
using with PI, 27
Staging Area, 28
use, 29, 30
Static elements, 6
Tech Support, 57
Time Range, 8
dialog, 10
formats, 10
future, 12
Shifting, 10
training users, 2
Trend, 7, 62
Trend Cursors, 8
Trend Scale, 12
Troubleshooting, 58
UNC, 48
Uniform Resource Locator, 62
Uninstalling PI-ActiveView, 16

64 OSI Software, Inc.

 Updates to Data in a Display, 7
URL, 48, 49, 62
User
Interaction with the PI Display Document, 8
Interface, 20
Username, 42, 44, 47
CFParam, 42
Users
training, 2
Using the Cabinet Wizard, 28
utility, 27
CabWizard, 27
VBA, 62
core components, 20
script, 12, 26
version qualifier
Code Source property, 37
Versions, 13, 57, 59
View|Refresh, 58
Viewing
a PI Display Document with PI data, 5
a Revised HTML Page, 58
Web Installs on NT Machines, 58
Web page
developing, 35
Web server, 62
Web site, 62
Width, 39
ActiveX control property, 37
Width Properties, 35
Wizard, 29, 31, 32

PI-ActiveView Developer’s Guide 65