DataSheet Control 2.0.1.

0
User Guide
OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com

OSIsoft Australia • Perth, Australia

OSIsoft Europe GmbH • Frankfurt, Germany
OSIsoft Asia Pte Ltd. • Singapore
OSIsoft Canada ULC • Montreal & Calgary, Canada
OSIsoft, LLC Representative Office • Shanghai, People’s Republic of China
OSIsoft Japan KK • Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V. • Mexico City, Mexico
OSIsoft do Brasil Sistemas Ltda. • Sao Paulo, Brazil
OSIsoft France EURL • Paris, France

Copyright: © 2003-2011 OSIsoft, LLC. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical,
photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.

OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Analysis Framework, IT Monitor, MCN
Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI
Web Parts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC.
All other trademarks or trade names used herein are the property of their respective owners.

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, Inc. license agreement and as
provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, Inc.
This product includes software (SSubTmr6.dll) developed by vbAccelerator (http://vbaccelerator.com/ (http://vbaccelerator.com/)).
Copyright © 2002 vbAccelerator.com
THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL VBACCELERATOR OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Version:
Published: 8/16/2011
Table of Contents
Chapter 1 Introduction ..................................................................................................................5
Binding to Units ..................................................................................................................5
Specifying the Data to Display and Enter...........................................................................5
Display of Specification Data .............................................................................................6
Writing Data to PI ...............................................................................................................6

Chapter 2 Identifying Data Entry Points......................................................................................7

ValueSets ...........................................................................................................................7
Creating the Necessary Aliases .........................................................................................8
Handling Missing Aliases ...................................................................................................8

Chapter 3 Installing the Control ...................................................................................................9

System Requirements ........................................................................................................9
Installation Procedures.....................................................................................................10
Other Information .............................................................................................................10

Chapter 4 Siting and Configuring the Control..........................................................................13

Siting the Control..............................................................................................................13
Configuring the Control ....................................................................................................17

Chapter 5 Viewing Data in the Control ......................................................................................29

Using the Control's Popup Menu......................................................................................29
Updating the Control ........................................................................................................31
Resizing the Control's Rows and Columns ......................................................................32
Changing the Data to be Displayed .................................................................................32
Using the About Value Dialog ..........................................................................................34
Viewing Range Limits.......................................................................................................35
Understanding the Application of Colors and Fonts.........................................................36
Navigating in the Control..................................................................................................37
ProcessBook Specific Functionality .................................................................................38

Chapter 6 Entering Data in the Control .....................................................................................41

Entering Values ................................................................................................................41
Committing and Confirming Entered Values....................................................................45
Using E-Signature ............................................................................................................50
Creating PIUnitBatches and PIBatches ...........................................................................51

Chapter 7 Programmatic Interface.............................................................................................55

OSIsoft DataSheet Control...............................................................................................55

iii
Table of Contents

Supporting Classes ........................................................................................................109

Enumeration Sets...........................................................................................................119

Chapter 8 Glossary....................................................................................................................123
ActiveX ...........................................................................................................................123
ANSI ...............................................................................................................................123
Batch Database..............................................................................................................123
COM ...............................................................................................................................123
Component Object Model ..............................................................................................123
IsPIUnit Property ............................................................................................................124
MDB................................................................................................................................124
Module............................................................................................................................124
Module Database ...........................................................................................................124
PI Batch Database .........................................................................................................124
PI Module Database.......................................................................................................124
PI Unit Module................................................................................................................124
Property Pages...............................................................................................................124
System Colors ................................................................................................................125
Unit Module ....................................................................................................................125

Index ............................................................................................................................................127

iv
Chapter 1

Introduction
The OSIsoft DataSheet Control is an ActiveX control that allows you to write data to PI
points from ProcessBook displays and other ActiveX control containers. Data entry is
facilitated by using the PI Batch database to identify new and existing PI Unit Batches for a
unit, and automatically supporting data entry for these PI Unit Batches.
When provided, specification ranges can be used to color-code entered data when it falls
outside of the specification range. Specification range limits can be fixed values or PI point
values.

Binding to Units
To truly add value, it must be easy to configure the DataSheet control. This is accomplished
by binding it to a PI Unit Module in the Module Database (MDB), and using the descendant
aliases of that PI Unit Module to identify the points to which entered data is written. This unit
binding also allows the control to automatically recognize PI Unit Batches running against
the unit to which the control is bound, thereby easily allowing values to be entered in the
context of a PI Unit Batch.

OSIsoft DataSheet Control

Specifying the Data to Display and Enter

The OSIsoft DataSheet Control is bound to a PI Unit Module, which helps to determine the
points to which entered values are written, and is used to automatically identify new PI Unit
Batches for data entry. The control also has an ordered collection of ValueSets; the primary
component of a ValueSet is the alias (on the bound unit) that identifies the point to which
entered values are written. Each ValueSet may also include any number of specification

5
Introduction

ranges, which can be used to visually distinguish entered values that are out of range. In
addition, each ValueSet may be read-only, or can be used to both display data and allow it to
be entered.
ValueSets may also be used to display header data, such as timestamps or Batch IDs.
ValueSets that are read-only or that display header data do not allow data entry, and indicate
that they are locked with a picture of a key in the upper-right-hand corner of the header cell
for the ValueSet.

Display of Specification Data

If specification ranges for a ValueSet are available, they can be used to change the
appearance of entered or displayed values. In addition, the range limits may be displayed in a
ToolTip. Ultimately, specification range data is either hard-coded, or comes from PI points.
By default, ranges for a ValueSet are used only for display purposes, such as color-coding,
and not to restrict the values that a user may enter. However, with the RangeEnforcement
property you can configure the control to prompt the user to confirm an entered value that
falls outside of an applicable range.

Writing Data to PI
If a ValueSet is not read-only, the entered value for a particular cell (row & column) can be
committed to PI as entered (when the cell loses focus), or can be retained in the control to be
committed at some later time. By default, uncommitted entered values are color-coded red
and emboldened to distinguish them from the rest of the data in the control, but this color-
coding and font formatting is configurable.
Each column in the control represents a PI Unit Batch for the unit to which the control is
bound. Since the cell in which data is entered refers to a single PI Unit Batch, that PI Unit
Batch is used to supply the timestamp for the data entered in that cell. All entered data values
are given the timestamp of the start of the PI Unit Batch to which they correspond.

6
Chapter 2

Identifying Data Entry Points

The OSIsoft DataSheet Control has an ordered collection of ValueSets. Each ValueSet can
display header information such as a Batch ID or timestamp, or represent a PI Point for which
data can be displayed and optionally entered. A ValueSet that represents a PI Point may also
include zero or more accompanying specification ranges. Each specification range may have
hard-coded limits, or draw them from PI Points. In fact, actual points are not specified for
ValueSets or Ranges. Instead, aliases are used to identify the interesting points, which
facilitate the unit-relative operation of the control.

ValueSets
Each ValueSet has four properties:
Name: A unique name used for row header text.
Value: The path to the PIAlias that identifies the PI Point to which entered values are written
and from which displayed values are drawn, relative to the Unit.
Type: An indicator of the content (header information or PI Point values) and write-ability
(whether it is read-only or read/write) of the ValueSet.
Ranges: A collection of specification ranges.
Any number of specification ranges may be provided for a single ValueSet. Each range may
have two associated colors for each limit (a background color and a foreground color) to be
used to color-code entered or displayed values when they fall above or below the
specification range. If specification range data is not needed, the collection of specification
ranges for a ValueSet may be empty.
Each PI Unit Module in the Module Database (MDB) to which the control may be bound is
expected to have aliases at the relative path specified for the ValueSets. For example, if an
instance of the control had a single ValueSet, with a value alias path of "pH," and two
specification ranges with alias paths "pH.Safety.High" and "pH.Safety.Low," and
"pH.Quality.High" and "pH.Quality.Low," the aliases for that unit in the MDB would appear
as depicted below.

7
Identifying Data Entry Points

Example of Aliases for a Module in the Module Database

Creating the Necessary Aliases

As stated, the set of points for which data can be entered for the control is determined by the
descendant aliases of the PI Unit Module to which the control is applied, and the ValueSets
created for the control. The points from which specification range minimums and maximums
may be drawn are also determined by the combination of aliases and ValueSets. You can use
the PI-Module Database Editor, the Module Database Editor plug-in for System Management
Tools version 3, or the Module Database Builder add-in for Microsoft Excel, to build the
necessary aliases for each PI Unit Module to ensure proper operation.

Handling Missing Aliases

If the value alias expected by a ValueSet cannot be found relative to the bound unit, the
ValueSet will not be displayed in the control. If the alias for a limit of a specification range
cannot be found, the ValueSet will still be displayed, but that limit for the specification range
will be ignored, and only the other specification limit will be applied.

8
Chapter 3

Installing the Control

The OSIsoft DataSheet Control must be installed on a Windows operating system. Since the
control cannot function as a stand-alone application, a container such as ProcessBook or
Visual Basic must be available to host it.

System Requirements

Operating Systems

This release supports Windows XP, Windows 2003, Windows Vista, Windows Server 2008,
and Windows 7.

System Prerequisites

Installation of an OSIsoft product relies on the presence of operating system components such
as the Microsoft .NET Framework. OSIsoft product setup kits check for prerequisite software
during installation. If not found, the installation will stop and you will be prompted to install
prerequisites.
To determine which MS Operating System prerequisites you need, see the OSIsoft Tech
Support Web site Prerequisite Kits pages
(http://techsupport.osisoft.com/Products/Prerequisite+Kits/Prerequisite+Kits+Overview.htm
).

Server Platforms

The control works with batch data on PI Server versions 3.4.364 and later.

Supported Client Software

The OSIsoft DataSheet Control has been shown to operate properly with the following
container software:
• PI ProcessBook 3.0 or Higher
• Visual Basic 6 Service Pack 6

9
Installing the Control

Installation Procedures
The OSIsoft DataSheet Control is distributed as a self-extracting executable which will
extract the setup kit to any location. Before running this self-extracting executable, close all
other applications so that they do not interfere with the installation process.

Note: Administrative privileges are required to install the OSIsoft DataSheet Control.
Before attempting installation of the OSIsoft DataSheet Control, you must first
install the appropriate OSIsoft Prerequisite Kit for your Operating System.

The setup wizard for the OSIsoft DataSheet Control begins with a welcome screen, which
lists all of the dependent components that may be installed during the installation of the
control. Only components that are not present, or that have an older version present, will be
installed during this process.
Following the installation of any necessary dependent components, the installation of the
DataSheet Control itself will begin.
Next, you can personalize your installation, and determine the scope of its availability.
The Ready screen indicates that the setup wizard has all of the information that it requires to
install the OSIsoft DataSheet Control. Clicking the Next button will begin copying files, etc.
A progress bar will be displayed as this happens.
When the DataSheet component of the installation is finished, you will see the DataSheet
Installation Complete page. Click next to complete the installation of the DataSheet and its
dependent components.
When installation of the DataSheet and all of its dependents is complete, the final screen of
the wizard will display, indicating same. On some versions of the Windows operating system,
a reboot may be required at this time.
The results of the setup wizard can be found in the SetupDataSheetSetup.log file in the
PIPC\Dat folder. OSIsoft support will require a copy of this log file if they are to assist in the
resolution of any problems that occurred during installation.

Other Information
The OSIsoft DataSheet Control can be removed with the "Add/Remove Programs" control
panel. The appearance and behavior of this control panel varies from one version of the
Windows operating system to the next. However, the OSIsoft DataSheet Control maintenance
wizard can be invoked from this control panel by selecting it from the list of installed
applications, and then clicking the appropriate button: Change, Remove, or Add/Remove,
depending on the Windows version.
Once the OSIsoft DataSheet Control Application Maintenance wizard is displayed, you may
choose to either repair or remove the control. Choosing Repair will search for missing
components, and attempt to restore them, whereas choosing Remove will un-install the
control from the computer. Administrative privileges are required to repair or remove the
OSIsoft DataSheet Control.

10
 Other Information

Message Logging

Information and Error messages appear in the Server & SDK Log. To view these messages
open PI-SMT 3, Open the Operation folder and select Message Log Viewer. The message
Program listing will be the name of the container (Processbook.exe, VB6.exe, etc.)
and the message will start with "OSIsoft DataSheet Control". To look for messages that came
from the DataSheet control, change the Message filter to "*DataSheet*".
As with other SDK applications, if the server cannot be contacted messages will be inserted
in the PIPC.log on the client machine.

11
Chapter 4

Siting and Configuring the Control

To use the OSIsoft DataSheet Control, it must first be sited in a container such as
ProcessBook, and then configured for operation. The process of configuring the control is the
same regardless of the container in which the control is sited.

Siting the Control

As stated, to make use of the control the first step is to site the control in a container. The
procedure for doing so varies from one container to the next, so it is provided in a step-by-
step fashion for the containers considered most likely to be used: ProcessBook, Visual Basic
6, and Visual Studio.NET.

Siting the Control in a ProcessBook Display

The OSIsoft DataSheet Control can be added to a ProcessBook Display very easily. When the
DataSheet control is installed on a machine, there will be an icon in the toolbar and a menu
item.
1. Start ProcessBook, and open the Display on which to place the control.
2. Click the DataSheet icon in the ProcessBook Toolbar.

PI ProcessBook Drawing Toolbar

3. Drag a box on the screen to indicate the size of the control.

4. After you release the mouse button, the property pages for the control open.
5. In the property pages for the control, make any configuration changes you desire (see
Configuring the Control (page 17) for more information about the control's property
pages).
6. Click OK to close the property pages. The control updates to show the ValueSets that
you've added.
7. When editing a control after it has been instantiated, ensure that the Display is in Build
Mode and right-click the control. Select Properties

13
Siting and Configuring the Control

OSIsoftDataEntryControls.OSIsoftDataSheet Object to display the control's property

pages.

PI ProcessBook popup menu

Siting the Control on a Visual Basic 6 Form

1. Start Visual Basic, and open the project in which you wish to use the control.
2. From the Project menu, select Components.
3. In the list of installed controls, check the OSIsoft Data Entry Controls. If it is not in the
list, use the Browse button to find the OSIDataEntryControls.ocx file in the
PIPC\Library folder, and add it to the list of installed controls.

14
 Siting the Control

Microsoft Visual Basic Components dialog

4. Click OK in the Components dialog to add the control to your project.

5. Open the designer for the form on which you wish to site the control.
6. Select the OSIsoftDataSheet control in the toolbox, then click and drag to identify the
rectangular area of the form where the control should be placed.

Microsoft Visual Basic Toolbox

7. Use the properties window or the property pages to configure the control.

Siting the Control on a .NET WinForm

The OSIsoft DataSheet control can be used to build a .NET application for writing data to
PI, using C# or any of the .NET languages.
1. Start Visual Studio.NET, and open or create a Visual C# Application.
2. From the Tools menu, select Add/Remove Toolbox Items.

15
Siting and Configuring the Control

3. Switch to the COM Components tab and, in the list of components, select the
OSIDataEntryControls.OSIsoftDataSheet. If the control is not in the list, use the Browse
button to find the OSIDataEntryControls.ocx file in the PIPC\Library folder and add
it to the list of components, and then select it.

Microsoft Visual Studio .NET Customize Toolbox dialog

4. Click OK in the Customize Toolbox dialog, to close the dialog and add the control to the
toolbox.
5. Open the designer for the form on which you wish to place the OSIsoft DataSheet
Control.
6. Select the control in the toolbox, then click and drag to identify the rectangular area of
the form where the control should be placed.

16
 Configuring the Control

Microsoft Visual Studio .NET Toolbox

7. Use the properties window or the property pages to configure the control.

Configuring the Control

Configuring an instance of the control is easy with the control's Property Pages dialog,
which consists of the following tabs: Data, Source, Settings, Defaults, Regulatory, Font,
Color, and Utilities. You can also use the Custom Name Sets to rename batch-specific
terminology to something compatible with non-batch industries.

Data Tab

The Data tab of the control's property pages allows you to bind the control to a PI Unit
Module, and to configure the content and order of the data it will display.

17
Siting and Configuring the Control

Property Pages dialog, Data tab, ValueSet view

Unit: Specifies the PI Unit Module in a Module Database whose aliases dictate the points
from which data is displayed and to which data is written. This same unit is also monitored
for new PI Unit Batches. Clicking the ellipsis (…) button allows browsing for a unit.
Auto Config: This button configures the ValueSets (but not Ranges) automatically. It adds a
ValueSet for BatchID, Product, Start Time, End Time and one for each of the aliases in the
selected unit. You are able to do a deep search for aliases, which will find all aliases in any
module under the selected unit, or a shallow search for aliases that are contained within the
selected unit itself. For Auto Config to work, you must first specify the Unit and also be able
to connect to the server. Using Auto Config removes any ValueSet already configured.
ValueSets: Shows the ValueSets that configured for the control, in the order in which they
will appear on the control. ValueSets that have configured ranges have a plus sign to the left
of the ValueSet name; click the plus sign to display the ValueSet's Ranges.
New ValueSet : Adds a ValueSet.
New Range : Adds a Range.
Delete : Removes the selected ValueSet or Range.
Up : Moves the selected ValueSet or Range up in the list.
Down : Moves the selected ValueSet or Range down in the list.
Type: Determines what the selected ValueSet displays. When a non Alias type is selected
and the ValueSet is still the default name, the ValueSet will be renamed to the name of the
Type. For Example, if you create a ValueSet and then select the Type as "BatchID", the name
of the ValueSet will be changed to "BatchID". If the name has been edited, then no
replacement is made.
Alias: Specifies the path to the alias that identifies the point from which displayed data is
retrieved, and to which entered data is written. The path is relative to the path to the bound
unit, and the alias must be a descendant of that unit. A backslash is used to separate modules

18
 Configuring the Control

in the path. If module names are included in the path, the alias name is expected to appear at
the end of the path and to be separated from the preceding module name by a vertical bar.
When an alias name is filled in, and the ValueSet Name is still set to its default, the ValueSet
will be renamed to the name of the Alias. For Example, if you create a ValueSet and then
select the Type as "Read Only" and then select the pH Alias, the name of the ValueSet will be
changed to "pH". If the name has been edited, then no replacement is made.
Also on the ValueSets tab, you can add, edit and remove a ValueSet's Ranges. For each
Range, you can configure both a Minimum and a Maximum, each of which support the same
set of properties.

Property Pages dialog, Data tab, Range view

Name: Specifies the name that will be used to identify the Minimum or Maximum for the
Range.
Type: Determines if the Value provided for the Minimum or Maximum should be considered
a fixed value, or a relative alias path.
ForeColor: Specifies the foreground color that will be used to color-code values that fall
outside the Range.
BackColor: Specifies the background color that will be used to color-code values that fall
outside the Range.
Value: Fixed value, or path to the alias that identifies the point from which Minimum or
Maximum values are drawn, depending on Type. The alias path can be typed in, or the alias
can be selected from a dialog that displays all aliases for the bound unit. The path is relative
to the path to the bound unit, according to the same rules as the alias for the ValueSet.

19
Siting and Configuring the Control

Select an Alias dialog

Source Tab

The Source tab of the control's property pages allows you to specify which PI Unit Batches
to display.

Property Pages dialog, Source tab

Start Time: Specifies the beginning of the time range from which the displayed PI Unit
Batches are drawn.
End Time: Specifies the end of the time range from which the displayed PI Unit Batches are
drawn.

20
 Configuring the Control

If the End Time is before the Start Time, batches will be displayed with the most current
batch on the left. Start Time and End Time cannot be the same value.
If a relative start time and/or end time is used, as illustrated, these relative times are
recalculated every time the control's display is updated. Relative times are the means of
configuring the control to recognize new PI Unit Batches as they are created.
To optimize the refresh speed of the control, limit the search time (between the start and end
times) to return the correct number of batches. The amount of time a batch query takes is
dependent on the number of batches that are returned.
Include: Determines if all PI Unit Batches in the specified time range are displayed, or only a
specific number of the first or last members of the specified time range.
Batch ID Filter: Used to filter Unit Batches by Batch ID. Wildcard searches are allowed
using the '*'. For example, if searching for all PI Unit Batches between the start and end times
with a Batch ID that starts with the letter 'A', the Product string would be 'A*'. Default value
is '*'.
Product Filter: Used to filter Unit Batches by Product. Wildcard searches are allowed using
the '*'. For example, if searching for all PI Unit Batches between the start and end times with
a product that starts with the letter 'A', the Product string would be 'A*'. Default value is '*'.

Settings Tab

The Settings tab of the control's Property Pages lets you control the appearance and behavior
of the control, such as the default column width and border style.

Property Pages dialog, Settings tab

21
Siting and Configuring the Control

Automatically Commit Entered Values: Determines if entered are written to PI when the
cell loses focus, or must be committed at some later time. This is equivalent to the
AutoCommit property of the programmatic interface.
Scroll to New Unit Batches: Determines if the control automatically scrolls to ensure that
newly-added PI Unit Batches are completely visible. This is equivalent to the AutoScroll
property of the programmatic interface.
Show Popup Menu: Determines if the popup menu is displayed when the control is right-
clicked. This is equivalent to the ShowPopupMenu property of the programmatic interface.
Show Gridlines: Determines whether or not gridlines are displayed between rows and
columns. This is equivalent to the ShowGridlines property of the programmatic interface.
Prompt for Comments for Entered Values: Prompts the user to enter a comment to
accompany an entered value. Comments are stored as annotations to entered values. This is
equivalent to the PromptComment property of the programmatic interface.
Warn Before Discarding Changes: Displays a warning in a dialog box before discarding
uncommitted entered values. This is equivalent to the PromptChangesPending property of the
programmatic interface.
Allow PIUnitBatches Edits: Allows the user to edit batch data in the grid. PIUnitBatch State
and PIBatch cannot be edited.
Allow Editing of Batch Information: Allows the user to edit batch data in the grid.
Allow Creation of PIUnit Batches: Enables right-click menu option to use the Create Batch
dialog to insert a new batch in the current unit.
Enable Context Switching: Only valid in ProcessBook. Allows the control to respond
changes in the selected unit made in the Module Context Add-In.
Show Engineering Units: Includes the display of the engineering units for the PI Point to
which the ValueSet refers in the header column.
Interval: Specifies the number of seconds between updates of data.
Appearance: Determines if the control has a flat or three-dimensional appearance.
Border Style: Specifies the line style used to draw the border that marks the boundary of the
control, if any.
Scrollbars: Determines whether or not scroll bars are displayed.
Enter Navigation: Determines if/how focus advances when the enter key is pressed.
Logging Level: Determines what messages are sent to the SDK Message Log which is
available via the PI-SMT 3 application. See Message Logging (page 11) for more
information.
Custom Names: This group of controls allows the user to select what custom name set is
used in the control.
The list allows the user to browse and select the Custom Name Set the control will use. This
defaults to the standard Custom Name Set for the machine the control is instantiated on.
Restore Default: Resets the Custom Name drop box to the default for this computer.

22
 Configuring the Control

Defaults Tab

Property Pages dialog, Defaults tab

Column Width: Specifies the default width of each column in twips. A twip is a twentieth of
a point, or 1/1440 of an inch. The default column width is set when the control is drawn on
the screen so the default 5 columns will fit.
Row Height: Specifies the default height of each row in twips. A twip is a twentieth of a
point, or 1/1440 of an inch.
Range Enforcement: Determines if Ranges are enforced against entered data.
Default Min Name: Default name of each new Range Minimum. The default is "Minimum"
Default Max Name: Default name of each new Range Maximum. The default value is
"Maximum"
Write Time: Sets the default time that data is written with respect to the batch. The choices
are "Batch Start" and "Batch End". Default is "Batch Start"
Write Mode: Allows the user to opt for replacing values instead of inserting new values. For
the replace to function, there must be a value that exists at the same timestamp that the new
value is destined. The default value for this setting is "Insert".
Reset Columns: Fits the default number of columns plus ValueSet Name column so they are
all visible.
Create Batch Properties: These properties are the defaults for the Create Batch dialog. The
properties available are:
• BatchID: Default is blank.
• Product : Default is blank.

23
Siting and Configuring the Control

• Procedure : Default is blank.

• StartTime : Default is "*".
• EndTime: Default is "*".

Regulatory Tab

The Regulatory tab controls the regulatory features of the control.

Property Pages dialog, Regulatory tab

Data Quarantine: Determines if newly entered data will be marked questionable in the PI
archive. This data will be marked as questionable in the grid. See the Regulatory section for
more details.
Require E-Signature: Indicates that for each commit the user must confirm their identity for
the data to be committed. The signature is recorded in the annotation for each data point for
that commit. E-Signatures are not supported on Windows 98.
Commit PI Group: The PI User Group that is allowed to commit data. The default is
"<All>" which allows anyone with the proper Write privileges to confirm data. The list in the
dropdown box is made up of all the PI User Groups on the selected server.
E-Sig Description: The description for the E-Signature window. Is stored with each E-
Signature. This field is limited to 1,000 characters.
Confirm PI Group: The PI User Group that is allowed to confirm data. The default is
"<All>" which allows anyone with the proper Write privileges to confirm data. The list in the
dropdown box is made up of all the PI User Groups on the selected server.

24
 Configuring the Control

Confirm E-Sig Description: The description for the Confirm E-Signature window when data
is confirmed. Is stored with each E-Signature. This field is limited to 1,000 characters.

Font Tab

The Font tab of the control's property pages allows you to control the appearance of the
instance of the control, through selecting fonts.

Property Pages dialog, Font tab

EnteredFont: Specifies the characteristics of the font used to display text in the data cells
that has been manually entered, and not yet committed.
Font: Specifies the characteristics of the font used to display all text in the data cells.
HeaderFont: Specifies the characteristics of the font used to display all text in the header
cells.

Color Tab

The Color tab of the control's property pages allows you to control the appearance of the
instance of the control, through selecting colors.

25
Siting and Configuring the Control

Property Pages dialog, Color tab

BackColor: Specifies the color used to fill data cells by default.

BaseColor: Specifies the color used to fill all control area not occupied by cells.
EnteredBackColor: Specifies the color used to fill data cells where values have been
manually entered, and not yet committed.
EnteredForeColor: Specifies the color used to display text in data cells that has been
manually entered, and not yet committed.
ForeColor: Specifies the color used to display text in data cells by default.
HeaderBackColor: Specifies the color used to fill header cells.
HeaderForeColor: Specifies the color used to display text in header cells.

Utilities Tab

26
 Configuring the Control

Property Pages dialog, Utilities tab

Validate Configuration: Used to ensure that all the aliases in the referenced PI Unit exist
and that configuration of the control is valid. When pressed, a list of all aliases that are
referenced in the control but do not exist in the current PI Unit is displayed in the text box
below the Validate button.

Using Custom Name Sets

BatchView 3.1 introduced Custom Naming, which consists of renaming the batch
terminology to complement non-batch industries. The Custom Name Set property (on the
Settings tag of the Property Page) defaults to the standard set of batch names (PIBatch,
PIUnitBatch etc). One other Custom Name Set is built into each PI Server called "Airline".
This translates batch names into names that would describe airline flights (Trip, Flight, etc.)
New custom name sets can be created using the SMT 3.1.0.0 or higher using the "Batch
Custom Name Editor" under the "Batch" group. Custom Name sets are stored on the Server,
but can be used against any unit batch as long as the server is available.
Layout problems have been noticed with long Custom Names for certain pages. The
problems result in labels for fields being truncated. Any truncated text can be viewed by
viewing the tool tip. To avoid layout issues, take care in assigning long Custom Names.
Not all of the batch names are used by the DataSheet control. The following lists the names
that are referenced:
• General: Unit
• PIUnitBatch: PIUnitBatch
• PIUnitBatch: PIUnitBatches

27
Siting and Configuring the Control

• PIUnitBatch: Batch ID
• PIUnitBatch: Product
• PIUnitBatch: Procedure
• PIBatch: Batch ID
• PIBatch: PIBatch
• PIBatch: PIBatches
• PIBatch: Product
• PIBatch: Recipe
• Results: Start Time
• Results: End Time
Because the labels for ValueSets are set when they are created, changing the Custom Name
Set after the ValueSets have been created will not change the ValueSet names even if they
have been auto generated. The best method for using the Auto Config feature is to change the
Custom Name Set first and then create the ValueSets.

28
Chapter 5

Viewing Data in the Control

In Run Mode, navigating and viewing data within the control is the same regardless of the
container, with a few exceptions that are discussed later in this section. The number and
content of rows and columns displayed are determined by the number of PI Unit Batches
requested and available for display and/or the way in which PI Unit Batches are chosen, and
by the ValueSets themselves.

Using the Control's Popup Menu

By default, when you right-click the control its popup menu is displayed. The popup menu is
used to interact with the control while in run mode. The options that are available on the
popup menu depend on the active selection within the control and the configuration of the
control.

Popup menu with Quarantined value selected, uncommitted values in control

29
Viewing Data in the Control

Popup menu with uncommitted value selected, other uncommitted value and quarantined value
in control

If the ShowPopupMenu property is False (the default is True), the popup menu will not be
displayed when the control is right-clicked.
The following is a description of the options that can be included on the popup menu.
Option Function
Select Unit Opens the Select Unit dialog. Provides access to the PI Connection
Manager dialog, which allows you to change the current PI server
and/or unit.
Select Data Source Opens the Select Data Source dialog, which allows you to specify
Source settings.
Scroll Forward Scrolls the control to the next set of PI Unit Batches in the future. See
Scrolling Through Batches (page 37) for details.
Scroll Back Scrolls the control to the previous set of PI Unit Batches in the future.
See Scrolling Through Batches (page 37) for details.
Reset Scrolling Resets the control to display the batches as currently configured in the
Select Data Source dialog. See Scrolling Through Batches (page 37)
for details.
Auto Width Resizes the rows and columns to fit the data currently displayed.
Refresh Retrieves the most current information available from the PI Server and
updates the control with this data.

30
 Updating the Control

Option Function
Commit Commits the value in the currently selected cell. If there are additional
uncommitted values in the control they will NOT be committed. Is only
included in the menu when a cell with an uncommitted value is
selected.
Revert Reverts the value of the currently selected cell to its previous value. If
there are additional uncommitted values in the control they will NOT be
reverted. Is only included in the menu when a cell with an uncommitted
value is selected.
Commit All Commits all uncommitted values in the control. Is only enabled when
there are uncommitted values in the control.
Revert All Reverts all uncommitted values to their previous values. Is only
enabled when there are uncommitted values in the control.
Create PIUnitBatch Allows you to create a new PI Unit Batch via the Create PIUnitBatch
dialog. Is only included in the menu when the "Allow Creation of
Batches" feature must be enabled.
About Value Opens the About Value dialog, which allows you to view the values
and associated information related to the selected cell.
Edit Value Opens the Edit Value dialog, which allows you to add a new value for
the selected cell.
New Value Opens the New Value dialog, which allows you to add a new value for
the selected cell.
Confirm Value Confirms the value in the currently selected cell. If there are additional
unconfirmed values in the control they will NOT be confirmed. Is only
included in the menu when a cell with an unconfirmed value is selected.
Confirm All Confirms all unconfirmed values in the control. Is only enabled when
there are unconfirmed values in the control.

Updating the Control

When the control first displays content, such as when a ProcessBook display is opened, the
most up-to-date values for all cells are retrieved and displayed. At this time, the control also
establishes two "event pipes," which are used to monitor the snapshot values for the
ValueSets, and to monitor the unit for new PI Unit Batches.
Once the control is visible, it will periodically update itself with a check of these event pipes
for new PI Unit Batches, and for new values for the ValueSets.
Each time a new PI Unit Batch is created for the PI Unit Module to which the control is
bound, that falls within the time range configured for the control, the new PI Unit Batch is
added to the control. If the maximum number of displayed PI Unit Batches has already been
reached, the oldest PI Unit Batch is removed, unless a cell for that PI Unit Batch has focus, or
uncommitted data has been entered for that PI Unit Batch. If a cell for the oldest PI Unit
Batch has focus or holds uncommitted data, and the maximum number of PI Unit Batches is
being displayed, new PI Unit Batches will not be displayed in the control until focus leaves
the oldest PI Unit Batch and all uncommitted data for that PI Unit Batch has been committed
or explicitly discarded.

31
Viewing Data in the Control

If the AutoScroll property of the control is set to True, when a new PI Unit Batch is added
the control the control will automatically scroll to ensure that the newest PI Unit Batch is
completely visible.
Periodically, the control checks with the PI server to ensure that the most current data is
displayed. At this time, the control also checks for any new PI Unit Batches for its PI Unit
Module, and adds them to the display if appropriate.

Refreshing the Control

At any time, the control can be asked to completely re-render or "Refresh" itself. Refreshing
the control will recognize new values and new PI Unit Batches.
When you Refresh the control, all of its content is discarded in favor of the most recent
values retrieved from the archive, and any uncommitted values are lost at that time. If the
PromptChangesPending property is True (it is False by default), the user will be warned with
a dialog box that uncommitted values are about to be discarded, and will have the opportunity
at that time to cancel the refresh operation. The PromptChangesPending property is
equivalent to the Warn Before Discarding Changes checkbox on the Settings tab of the
control's property pages.

Resizing the Control's Rows and Columns

When the control enters the run mode it sets the column widths and row heights to the sizes
specified in the configuration. However, if the control is using a font size that requires more
row height than is currently configured, then the row height will automatically resize to fit the
font.
You can manually resize the row heights and column widths by dragging the row or column
separators to the appropriate position. You can use the AutoWidth option on the popup menu
to automatically resize both the column widths and row heights to fit the currently displayed
data.

Changing the Data to be Displayed

When the control is configured, defaults are defined to indicate the unit, the time range to be
used, the number of PI Unit Batches to be included, as well as Batch ID and Product filtering.
These settings can be changed while in run mode. Each time these settings are changed while
in run mode, the control is updated to display the most current information.

Changing the Unit

While in run mode, you can change the unit to which the control is attached by selecting
"Select Unit" on the control's popup menu. The Select Unit dialog displays a hierarchical
view of the PI servers to which you are currently connected and the PI Units defined for each
server.

32
 Changing the Data to be Displayed

Selecting a new server and/or unit and clicking OK causes the control to update with the
newly selected server/unit information. ValueSets that reference an alias that exists in the
newly selected unit are displayed. If a ValueSet references an alias that doesn't exist in the
new unit, the ValueSet is not displayed in the control. The ValueSet is not removed from the
control's configuration, just hidden until you change the unit selection to a unit that does
contain the ValueSet's alias.

Select a Unit dialog

While in the Select Unit dialog, you can click the Connections button to open the PI
Connection Manager dialog. You can add and remove PI Servers to/from the list of
available PI Servers, as well as reconnect to a PI Server as a different user.

Changing the Data Source

You can change the filtering of the batch data displayed in the control at anytime while in run
mode. The Select Data Source item in the popup menu displays the Select Data Source
dialog, which gives you the same interface for specifying the data to display as is available
from the Source tab of the control's property pages.

33
Viewing Data in the Control

Select Data Source dialog

You can select a Start Time and End Time from pre-defined lists of time filters, or enter your
own time filter. The value must be a valid PI Time Format. If the actual date associated with
the Start Time is less than the actual date associated with the End Time, the batches are
displayed in date order from left to right (the oldest batch being in the left-most data column).
Otherwise, the batches are displayed in date order from right to left (the oldest batch being in
the right-most data column).
You can specify the number of batches to be included in the control using the Include and PI
Unit Batches fields. Select from Last, First and All in the Include list. If you select Last or
First, the PI Unit Batches is enabled and defaults to 5. If you select All the PI Unit Batches is
disabled.
Use the Batch ID Filter and Product Filter fields to specify the filter the displayed batches
based on the Batch ID and Product. Only those batches that match the specified filter criteria
are included in the control.

Using the About Value Dialog

The last value archived for each PI Unit Batch is displayed for each ValueSet in the cell that
represents that combination of PI Unit Batch and ValueSet. If a value has not been provided
for a ValueSet during a particular PI Unit Batch, the cell for that combination of PI Unit
Batch and ValueSet will be empty.
In addition to the entered value, a set of metadata is stored in the annotations and is available
using the About Value dialog, which is available via the right-click menu. To view this data,
right-click a cell with a value that has been entered using the DataSheet Control. Select the
About Value menu item. The About Value dialog displays the data. Even though data points
entered by a different method show up in the DataSheet Control, this ancillary data is only
available for data points that have been entered with the DataSheet control.

34
 Viewing Range Limits

About Data dialog

The About Data dialog shows the information about the batch, and a list of all the values that
exist for that ValueSet between the batch start time and batch end time. The values are shown
in the reverse order that they exist in the Archive. The current value being displayed will be
expanded and at the top of the list.
If comments were stored with the data value, Comment nodes will be in the tree, and the
comment is displayed in the lower box when the node is selected.

Viewing Range Limits

If ranges are defined for a ValueSet, they can provide fixed limit values, or can identify the PI
points from which limit values can be drawn. These limit values can then be used to color-
code entered values. Limit values that are drawn from PI points are drawn at the timestamp of
the value against which they are being compared.
Range data may also be displayed in ToolTips. When you mouse over a data cell whose value
falls outside of a range for the corresponding ValueSet, the range information will be
displayed in a ToolTip. The range that the value comes closest to but still falls outside of will

35
Viewing Data in the Control

be displayed. Specifically, the name of the Range will be displayed, followed by the name of
the Minimum and its value, then the name of the Maximum and its value.

Display of range limits

Ranges are ignored when created for a ValueSet whose value alias references a PI point
whose point type is not numeric (blobs, strings, and digital state sets), but are supported for
numeric types (floats and integers).
Likewise, when the limit types are "Alias", the Minimum and Maximum aliases for a Range
are expected to refer to PI points that are numeric. If a Range limit refers to a point of type
blob, string, or digital state set, that limit will be ignored. No range consistency checking is
performed to ensure that, for example, Minimum is less than Maximum.
When two different Ranges for the same ValueSet have the same limit value, the Range that
appears first in the list of Ranges for the ValueSet will be applied. This is true even when the
value for the minimum for one Range is the same as the value for the maximum for another
Range for the same ValueSet.

Understanding the Application of Colors and Fonts

By default, data displayed in the control uses the default font of the container in which the
control is sited, and the default foreground and background colors of the operating system.
Also by default, entered values will be in a bold font, red in color on a white background,
drawing the remainder of the font characteristics for entered values from the font of the
container, until it is committed to and read back from the PI Server. Data displayed in a
ValueSet that falls outside of any specification range for that ValueSet will by default be blue
on white, but otherwise appear in the same font as committed values.
The foreground and background for uncommitted values may be customized to any RGB or
system color. In addition, a separate font can be used to distinguish uncommitted values from
the rest of the data displayed. Furthermore, each range for a ValueSet can have its own
foreground and background colors. When a value falls outside of one or more applicable
ranges, it will have applied the colors according to the outermost range that it exceeds.
The priority of possible colors applied to a value is as follows:
1. If the value has been entered but not committed, it will be displayed in the font specified
by the EnteredFont property, and in the colors specified by the EnteredForeColor and
EnteredBackColor properties.
2. If the value has been committed, but exceeds the maximum value for any Range for the
ValueSet in which it resides, it will be displayed according to the Font property of the

36
 Navigating in the Control

control, and in the colors specified by the MaximumForeColor and MaximumBackColor

properties of the Range for the ValueSet whose Maximum value it falls closest to but
exceeds.
3. If the value has been committed, does not exceed the maximum value for any Range for
the ValueSet in which it resides, but does fall below the minimum value for one or more
Ranges for the ValueSet in which it resides, it will be displayed according to the Font
property of the control, and in the colors specified by the MinimumForeColor and
MinimumBackColor properties of the Range for the ValueSet whose Minimum value it
falls closest to but does not exceed.
4. If the value has been committed and does not fall outside of any Range for the ValueSet
in which it resides, it will be displayed as specified by the Font, ForeColor, and
BackColor properties of the control.

Navigating in the Control

When a cell has focus, pressing the enter key can advance focus to the next cell in the control
(if any), by default moving top to bottom. If the Shift key is held down while the enter key is
pressed, the advancement of focus is reversed, by default moving focus up one cell instead of
down. The EnterNavigation property controls the order of advancement of focus when the
enter key is pressed. For example, you can change the EnterNavigation property so that
pressing the enter key will advance focus to the right (if possible) instead of down.
The arrow keys advance focus to the next cell in the direction of the arrow. If no cells remain
in the direction of the arrow, pressing that arrow key will have no effect. The other common
keyboard navigation keys behave as expected. The Home key advances focus to the left-most
cell in the current row, the End key advances focus to the right-most cell in the current row,
the Page Up key advances focus up at most one viewable page of rows, and the Page Down
key advances focus down at most one viewable page of rows. The Page Up and Page Down
keys keep focus in the same column. All four of these common navigation keys can cause the
control to scroll if necessary. The tab key will always advance focus away from the OSIsoft
DataSheet Control.

Note: If the AutoCommit property is true, and data has been entered into the cell that
has focus, that data will be committed to PI when the tab key, the enter key, or
any arrow key or common navigation key is pressed, or when the cell loses focus
for any other reason.

Scrolling Through Batches

To facilitate viewing batches the user can step backwards and forwards through time. Each
time the forward or back method is executed the next or previous time period is displayed.
This can be accessed through the right-click menu or programmatic access.
If the control is set to display first or last # of batches, the scrolling from the right-click menu
will scroll the number of batches displayed into the future or the past. For example, if the
control is set to show the last 5 batches in the timeframe, each time the user scrolls forward or

37
Viewing Data in the Control

backwards, the control shows the next or previous 5 batches. If Data Inclusion is set to "All"
then it will scroll the Start and End times. For example if the control is set to show all batches
in the past hour, the control will scroll forward and back by one hour at a time.
When the control has been scrolled backwards in time, the time span that the control is set for
(Start Time and End Time) is set to a fixed time that will not change until the user uses the
"Reset Scrolling" menu item or until the ResetSearchTimes method is called. When that
method is fired, the search criteria are set back to the defaults.
All uncommitted data in the grid must be committed before scrolling. If "Warn Before
Discarding Changes" is on, the user will be queried if the values should be saved before
scrolling.
While the search times are set, arrows appear at the tops of the grid to indicate that there are
more batches to be displayed.

Scrolling through batches

ProcessBook Specific Functionality

For the most part, viewing data in the control is the same regardless of the container.
However, the control has one feature (Enable Context Switching) that only affects the way
data is displayed when ProcessBook is the container. When this feature is selected and
ProcessBook is the container, you can use the "Module Relative Displays" and "Client
Time/Server Time" features within ProcessBook.

Module Relative Displays

When setting up a Module Relative Display, the control detects when the module changes
and changes the context of the control. Any ValueSets and Ranges that map to aliases that do
not exist in the new module will be ignored. To have the control monitor module changes,
you must check the Enable Context Switching checkbox on the Settings tab in the Property
Pages for the control.

Client Time/Server Time

The control can translate all displayed timestamps according to the Client Time / Server Time
setting in ProcessBook. This only occurs if the Enable Context Switching setting is turned
on in the Property Pages of the control. Entered times and dates are translated as well.

38
ProcessBook Specific Functionality

39
Chapter 6

Entering Data in the Control

The OSIsoft DataSheet Control provides an easy means for entering data directly into PI
points. You can enter values into specific points, edit values that have been entered using the
DataSheet Control, plus create and edit batches. Data can be entered by either interacting
directly with a cell or by using the New Value dialog. Values are not written to PI until they
are committed; this can be done manually or automatically.

Entering Values
You can enter a value into a cell by clicking in the cell then typing the value. When the point
type is a digital state, the cell will provide a pull-down list containing the allowable values,
from which an entered value must be chosen.

Selecting a value from a digital state set

If the AutoCommit property is True, regardless of the method of data entry (directly in a cell
or with the New Value dialog), data entered into a cell in the control is written to PI at the
time that the cell loses focus. If AutoCommit is off, you must either commit entered data with
the popup menu, or provide a way to invoke the control's Commit method.
Until entered data has been successfully written to PI and read back, it will appear
uncommitted (by default, this means in a bold, red font).

41
Entering Data in the Control

Color-coding uncommitted entered values

During the short period of time during which an entered value has been committed without
error, but not yet reported back by the PI Server to which it was written, and hourglass icon
will appear in the cell with the value.

Hourglass indicates successful write, waiting for confirmation

The EnteredForeColor property can be used to change the color of uncommitted data to any
other RGB or system color. In addition, the EnteredFont property can be used to display
uncommitted data in a different font than the rest of the data in the control.

Editing Batch Data

If the Allow Editing of Batch Information checkbox is enabled in the Property Pages, Unit
Batch properties can be edited in the grid just like other ValueSets. The ValueSet Types that
can be edited are: BatchID, Procedure, Product, Start Time and End Time.
PIUnitBatches cannot overlap, so when editing Batches be cautious about moving Start
Times or End Times that overlap other batches. Any errors will be displayed with a red
exclamation point in the cell that has the error with a text description of the error in the
ToolTip.
Because Batch properties do not have annotations they cannot store E-Signatures or
comments. When committing only batch properties you will not be prompted for either an E-
Signature or a comment. If committing a mixture of values and Batch properties, you will be
prompted, but only the values will store the E-Signatures and comments.

Displaying Invalid Values

The data type of each read-only or read/write ValueSet is dictated by the type of the PI Point
to which the Value Alias for the ValueSet refers. Any attempt to enter data that cannot be
coerced to the appropriate data type will be prevented, and indicated in the cell where the
offending value was entered. An exclamation point within a cell indicates an error has
occurred. If the invalid value is committed programmatically, the method that was invoked
(Commit or CommitAll) will raise an error.
Pointing your cursor over the cell with the exclamation point causes the error message to be
displayed in a ToolTip.

42
 Entering Values

Indication of a write failure

Using the New Value Dialog

An alternate way to enter data is to use the New Value dialog, which gives you more control
over how the data is recorded. Right-click the cell you want to enter data into and select New
Value.

New Value on the popup menu

The resulting dialog allows you to enter a value, enter a comment or select from a list of pre-
defined reason codes, and specify the timestamp to be associated with the new value. The
timestamp can be set to the Beginning of the Batch, the End of the Batch (or current time if
the batch has not been completed), or to a specific timestamp. This timestamp must be
between the start time and the end time of the batch at the time the value is committed.

43
Entering Data in the Control

Note: A value must have a timestamp that is greater than or equal to the start of the
batch and less than the end of the batch to be included in the batch. For that
reason, when you use the End of Batch option for the timestamp in the control, the
control will assign a timestamp that is one second less than the actual end of
batch to ensure that the value is included in the batch.

New Value dialog

If you are entering a value in an empty cell, the New Value dialog will not have Existing
Value data. However, if you are editing an existing value, the Existing Value area displays
the current value and the timestamp associated with that value.
If the Enable Batch Editing option is enabled on the Settings property page, Batch ID, Start
Time, End Time, and Product will all be editable. These values can only be edited within the
cell; they cannot be edited using the New Value dialog.

Note: The timestamp of a value written to a PI point is used to associate the value with
the PI Unit Batch for which it was entered. Should the start time or end time of the
PI Unit Batch be edited after the value is written to PI, it's possible that the value
will lose its association with the PI Unit Batch if the timestamp for the value falls
outside of the new time range for the PI Unit Batch. This problem can be avoided
by setting the IsBatchAnchored property of the PI Aliases used to write the data to
True. Setting the IsBatchAnchored property to True will cause the timestamp of
entered values to change relative to any change made to the timestamp for the
start of the PI Unit Batch.

44
 Committing and Confirming Entered Values

Committing and Confirming Entered Values

Commit All on the popup menu

If the ShowPopupMenu property is False (the default is True), the popup menu will not be
displayed when the control is right-clicked.
If you right-click in a data cell (not in the header row or column), and that cell contains
uncommitted data, two additional popup menu items will be available, allowing you to either
Commit or Revert just the uncommitted value in that single cell.

Popup menu for a data cell holding an uncommitted value

With the Data Quarantine setting ON all data entered is marked as questionable in the PI
Archive. All questionable values are displayed with a question mark and have a Confirm
Value option available in the right-click menu. If the questionable bit is set by an interface or
program other than the DataSheet Control, then anyone that has write access to that point can
confirm the data.

45
Entering Data in the Control

Note: If the AutoCommit property is True, the popup menu members for committing and
reverting entered data will not be present.

With the E-Signature setting on, before committing data a pop up box displays to accept your
credentials. If the login fails, no data is committed; the values remain marked as
uncommitted.

Comments for Entered Data

If the PromptComment property of the control is set to True, each time entered data is
committed to PI, you will be provided with a dialog box that allows you to optionally provide
a comment for the entered data.

Providing a comment for an entered value

If you are committing several entered values at once, you will only be allowed to provide a
single comment, which will be applied to all of the values committed.
All comments that have been defined on a point by point basis (using the New Value Dialog)
will not be overwritten. This comment will be added to the one previously entered.
Comments are stored as annotations to the entered values in the PI archive. Batch properties
do not have annotations, so comments will not be applied to those changes. Comments are
restricted to 10,000 characters.
Reason codes are stored in the Module Database and can be created and edited using the
Reason Code Editor Plug-in available through the OSI support site. Reason Codes are defined
with a Module Name (Reason Code) and may or may not have a Description (Comment).
When a Reason Code with a Comment is selected, the Comment text is copied into the
Comment field; it is locked and cannot be edited. When a Reason Code without a Comment

46
 Committing and Confirming Entered Values

is selected, any pre-existing Comment text remains, and the Comment field is enabled for
editing. When "<none>" is selected, the Comment field is enabled for editing, any pre-
existing Comment text remains.

Select a reason from the Reason Code list

Confirming Data

If the Data Quarantine option is selected, committed data will be entered as "Questionable"
in the archive and be displayed with a question mark on the right hand side of the cell:

Example of data marked as Questionable

When Questionable values are displayed, the Confirm and Confirm All menu items will
appear on the popup menu (if popup is enabled). Confirm is only enabled when the selected
cell is questionable. Confirm All will confirm all values in visible cells.
Annotations for confirmed values are similar to committing values. If the correct options are
enabled, the user can submit an E-Signature and a comment. The logged PI User and logged

47
Entering Data in the Control

in Windows user, as well as Windows user who signs in for the E-Signature, are stored along
with the time/date the value is confirmed.
If the Write Mode is set to Insert (default) a new value is written to the archive at the same
time as the questionable value with all of the confirm annotations as well as the annotations
that were attached to the value when it was initially committed to the archive. After
confirming the value, if you look in the About Value dialog (right Click) two values will
appear. The first value (latest) will be the value with all of the committed and confirmed
annotations. The second value will have just the data that was committed. If the Write Mode
is set to Replace, the value that exists in the archive will be overwritten with the value and all
of its committed and confirmed annotations.

Value annotated with Commit and Confirm annotations

Value Metadata

A series of data is stored for each PIValue written to the PI Archive. This data is stored in a
PIAnnotations collection as an annotation for the value. Some of the values will be included
or not depending on the settings of the control. This metadata can be viewed with the About
Value dialog available through the right click menu.

48
 Committing and Confirming Entered Values

Generic Metadata
• Entered By (Windows User) – The user that is logged into the window session. In
Windows 2000, XP and 2003, this value will be the Domain\UserName if logged into a
domain, and Machine\UserName if logged into the machine as a local user.
• Entered By (PI User) – The PI User name from the current connection.
• Entered Date – The time and date the user committed the data to the archive. May differ
from the Timestamp of the value
• Comment – There could be up to 2 comments per value. Comments can be entered from
the New Value box and can be prompted for when data is committed.

E-Signature Metadata
• ESig UserId – Domain and User Name of the E-Signature in the form of
Domain\UserName
• ESig Action – The description from the E-Signature box configured on the Regulatory
Property Page

Confirmation Metadata
• Confirmed By (Windows User) – Exactly the same as the Entered By data
• Confirmed By (PI User) – The PI User name from the current connection
• Confirmation Date – The time and date the user confirmed the data to the archive
• Confirmation Comment – The comment that can be submitted with the confirmation E-
Signature
• Confirmation ESig UserId – Domain and User Name of the E-Signature in the form of
Domain\UserName
• Confirmation ESig Action – The description from the E-Signature box configured on the
Regulatory Property Page

Committing and Confirming PI Groups

Committing and Confirming can be restricted by PI User Group. On the Regulatory Property
Page, select the PI Group that will be allowed to commit data and confirm data. When
committing data or confirming data, if the PI logged in user performing the action is not in
the selected PI Users Group, the user will be notified with a popup box.
The Commit PI User Group will always be applied. It does not matter what the other settings
are on the Regulatory page. If Data Quarantine is not enabled, then the Confirm PI Group is
disabled.

49
Entering Data in the Control

Auditing Data

When data is committed or confirmed the logged-in user is recorded in the annotation for that
data point. This information is viewable in the DataSheet Control (using the About Value
menu option) or through a ProcessBook trend when viewing annotations.

About Value dialog

If configured to do so, the PI Audit Trail will record changes and deletions of data including
annotations if PI 3.5 or greater is used.

Using E-Signature
With the Require E-Signature setting on, a dialog displays each time you commit a value (or
values) and requires you to enter your credentials for verification. If verification fails, the
user is notified. The E-Signature/Comment box OK button will not operate without a valid
UserName / Password pair. If you do not supply the correct credentials, the data will not be
committed.
Because E-Signatures are stored in annotations, E-Signatures cannot be attached to Batch
Properties. If only Batch Property changes are being committed no E-Signature dialog will
appear.

50
 Creating PIUnitBatches and PIBatches

E-Signature Login dialog

For Window 2000 Pro and Server machines, the logged in user needs the Act as part of the
operating system right.
The user signing the E-Signature must have rights to log into the local machine.

Creating PIUnitBatches and PIBatches

Batches can be manually created in the DataSheet Control. When the Allow Creation of
PIUnitBatches checkbox on the Settings page is enabled, the Create PIUnitBatch menu
item on the right-click menu is available. Clicking this menu item opens the Create
PIUnitBatch dialog.

51
Entering Data in the Control

Create PIUnitBatch dialog

The Unit text box indicates the current unit, but is not editable.
The Batch ID, Start Time, End Time, Product and Procedure text boxes default to the values
specified in the Insert PIUnitBatches Defaults in the Defaults tab.
After you fill out the data and click OK, a new batch is created and the control will refresh
with the new data column. If the batch that was created is outside the current search criteria it
will not display. If the Start Time and/or End Time falls within the time frame of another
batch, an error displays indicating the batch cannot be created.

Attaching a PIUnitBatch to a PIUnitBatch

There are two methods for attaching the new PIUnitBatch to a PIBatch. You can select an
existing PIBatch or create a new PIBatch.

Selecting a PIBatch
Click the Select PIBatch option and click the ellipsis to the right. The PIBatch Search
dialog displays.

52
 Creating PIUnitBatches and PIBatches

Create PIUnitBatch dialog

The PIBatch Search dialog defaults to searching for PIBatches during the past day.
PIBatches are listed in the hierarchy. Expanding a PIBatch in the hierarchy displays
information about the PIBatch. PIUnitBatches belonging to a PIBatch are included in a
PIBatch’s hierarchy under the PIUnitBatches node. Expand the PIUnitBatches node to view
the PIUnitBatches and their information
Only the PIBatch level of the hierarchy can be selected. When a PIBatch is selected, the
Select button is enabled. When a PIBatch is selected, its BatchID is displayed in the text box
to the right of the Select PIBatch radio button.
Click OK to create the new PIUnitBatch. The new PIUnitBatch is attached to the selected
PIBatch.

Creating a PIBatch
To create a PIBatch, select the Create PIBatch option. The Create PIUnitBatch dialog
expands to display the PIBatch Info area.

53
Entering Data in the Control

Create PIUnitBatch dialog, expanded

The PIUnitBatch’s BatchID, Start Time, End Time and Product are copied to the PIBatch
Info fields. Modify these fields as needed, and add a value to the Recipe (if needed). Click
OK to create a new PIUnitBatch and PIBatch. The new PIUnitBatch is attached to the new
PIBatch.

54
Chapter 7

Programmatic Interface
The OSIsoft DataSheet Control is an ActiveX control, and as such, has a COM interface for
programmatic interaction, which consists of a set of properties, methods, and events. In
addition, the control's COM interface includes some supporting objects or classes that have
their own properties, methods and events, and several enumeration sets that simplify usage of
the programmatic interface by providing symbolic names to represent fixed values.

OSIsoft DataSheet Control

The OSIsoft DataSheet Control is a configurable control, capable of both displaying and
allowing the entry of PI data.

Note: The OSIsoft DataSheet Control is found in the OSIDataEntryControls.ocx

file. When distributing an application that you build using the OSIsoft DataSheet
Control, you must also distribute the OSIDataEntryControls.ocx file, as well
as the libraries upon which it depends.

Properties

The properties of the OSIsoft DataSheet Control are used to control the behavior and
appearance of an instance of the control.

AllowBatchEdits
Sets and returns if batch data can be edited.

Syntax
object.AllowBatchEdits [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression that indicates if the control's CreatePIUnitBatch
method is available for use.

Settings
The settings for value are:

55
Programmatic Interface

Constant Description
True Allows the editing of batch information the same way data is
normally edited.
False (Default) Does not allow editing of batch data.

Remarks
See the Data Entry section for a description of the behavior.

AllowBatchInsert
Sets and returns if the control should allow the creation of new Unit Batches.

Syntax
object.AllowBatchInsert[= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression that indicates if the control's CreatePIUnitBatch
method is available for use.

Settings
The settings for value are:
Constant Description
True Allows the creation of new batches (columns) in the DataSheet
Control either through the right-click popup or through the
CreatePIUnitBatch method.
False (Default) Does not allow creation of new Unit Batches.

Remarks
See the Data Entry section for a description of the behavior.

Appearance
Returns or sets appearance of the control.

Syntax
object.Appearance [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is an expression that indicates if the control's appearance should be flat or
three-dimensional.

Settings
The settings for value are:
Constant Description
0 The control has a flat appearance.

56
 OSIsoft DataSheet Control

Constant Description
1 (Default) The control has a three-dimensional appearance.

Remarks
The AppearanceConstants enumeration set of Microsoft's Common Controls library can be
used to assign values to or compare values with the Appearance property, in place of the
literal constants shown in Settings.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Value (380) The only allowable values for Appearance are zero and one.

AutoCommit
Returns or sets whether data entered in the control is automatically written to PI, or waits
until the Commit method is called.

Syntax
object.AutoCommit [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression that determines if entered data is automatically
committed to PI, or waits until the Commit or CommitAll method is called, as described in
Settings.

Settings
The settings for value are:
Constant Description
True Entered data is automatically written to PI.
False (Default) Entered data is not written to PI until either the Commit
method or the CommitAll method is called, or the Commit or
Commit All popup menu item is clicked.

Remarks
The control's popup menu will contain the "Commit", "Commit All", "Revert", and "Revert
All" items only when the AutoCommit property is False.

AutoScroll
Returns or sets whether the control automatically scrolls to ensure that the most recent PI
Unit Batch is visible.

57
Programmatic Interface

Syntax
object.AutoScroll [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression that determines if the control automatically scrolls
to show new PI Unit Batches, as described in Settings.

Settings
The settings for value are:
Constant Description
True When a new PI Unit Batch is added, the control automatically
scrolls to guarantee that the new PI Unit Batch is completely
visible.
False (Default) All scrolling is initiated by the user.

Remarks
If a cell in the control is being edited, new PI Unit Batches may be added without any
scrolling occurring, regardless of the value of the AutoScroll property. In this event,
automatic scrolling will occur, if necessary, once the control loses focus.

BackColor
Returns or sets the background color used in all data cells in the control.

Syntax
object.BackColor [= color]
The object placeholder represents an object expression that evaluates to an instance of the
control. The color value is a long integer expression specifying what background color
should be used for all data cells in the control, as described in Settings.

Settings
The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a
number in this range equals 0; the lower three bytes, from least to most significant byte,
determine the amount of red, green and blue, respectively. The red, green and blue
components are each represented by a number between 0 and 255 (&HFF). If the high byte is
not 0, the value represents a system color; see Microsoft Visual Basic for Application's
SystemColorConstants enumeration set for more information.

Remarks
The BackColor value applies only to data cells, not header cells. To control the background
color of header cells, use the HeaderBackColor property.
The default value of the BackColor property is the BackColor of the container.

58
 OSIsoft DataSheet Control

BaseColor
Returns or sets the background color for the unoccupied portion of the control.

Syntax
object.BaseColor [= color]
The object placeholder represents an object expression that evaluates to an instance of the
control. The color value is a long integer expression specifying what background color
should be used for all portions of the control not occupied by cells, as described in Settings.

Settings
The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a
number in this range equals 0; the lower three bytes, from least to most significant byte,
determine the amount of red, green and blue, respectively. The red, green and blue
components are each represented by a number between 0 and 255 (&HFF). If the high byte is
not 0, the value represents a system color; see Microsoft Visual Basic for Application's
SystemColorConstants enumeration set for more information.

Remarks
Use the BackColor, EnteredBackColor, and HeaderBackColor properties to control the
background color of cells.

BorderStyle
Returns or sets the border style for the control.

Syntax
object.BorderStyle [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is an expression specifying what kind of border the control should have, if
any, as shown in Settings.

Settings
The settings for value are:
Constant Description
0 None. No border is drawn.
1 (Default) Fixed single. The control has a fixed border with a one-pixel width.

Remarks
The BorderStyleConstants enumeration set of Microsoft's Common Controls library can be
used to assign values to or compare values with the BorderStyle property, in place of the
literal constants shown in Settings.

59
Programmatic Interface

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Value (380) The only allowable values for BorderStyle are zero and one.

CellsPerValueSet
Returns or sets the maximum number of PI Unit Batches to display.

Syntax
object.CellsPerValueSet [= integer]
The object placeholder represents an object expression that evaluates to an instance of the
control. The integer value is an expression specifying the maximum number of PI Unit
Batches to display.

Settings
The minimum value of this property is one, and the maximum value is 100. The default value
is five.

Remarks
When a new PI Unit Batch is detected but the control is already displaying the number of PI
Unit Batches indicated by the CellsPerValueSet property, the oldest PI Unit Batch is removed
from the display, and the new PI Unit Batch is added.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Value (380) The minimum allowable value is one, and the maximum is one
hundred.

ChangesPending
Returns a Boolean that indicates when True that values have been entered but not yet
committed.

Syntax
object.ChangesPending
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
This property is not available in Build Mode, and is read only in Run Mode.

60
 OSIsoft DataSheet Control

This Boolean property returns True if there are entered values that have not yet been
committed, and False otherwise.

ColumnWidth
Returns or sets the width of each column in logical twips.

Syntax
object.ColumnWidth [= width]
The object placeholder represents an object expression that evaluates to an instance of the
control. The width value is a long expression specifying the width of all columns in the
control, as described in Settings.

Settings
The ColumnWidth property is expressed in units of twips. The default value is one-sixth the
width of the entire control when sited, the minimum value is zero, and the maximum value is
2147483647.

Remarks
After the ColumnWidth property is applied to the widths of the columns, the user may
interactively resize each column individually.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Value (380) The minimum allowable value is zero, and the maximum is
2147483647.

ConfirmESignatureDescription
Sets and returns the text that is displayed on the E-Signature sign in box.

Syntax
object.ConfirmESignatureDescription [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a string that is displayed on the E-Signature.

Remarks
Is only used when ESignature and DataQuarantine is turned on. Text is recorded with each
ESignature for confirming data.

ConfirmESignatureGroup
Sets and returns the PI User Group to which the confirming user must belong.

61
Programmatic Interface

Syntax
object.ConfirmESignatureGroup [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is the name of the PI User Group.

Remarks
Is only used when ESignature and DataQuarantine is turned on.

CurrentBatchIndex
Returns the index of the currently selected batch.

Syntax
CurrentBatchIndex
The object placeholder represents an object expression that evaluates to an instance of the
control. The integer is a value between 1 and the value of the DisplayedBatchCount property.

Remarks
See the Data Entry section for a description of the behavior.

CurrentComment
Returns or sets the operator Comment of the value in the currently-selected cell.

Syntax
object.CurrentComment [= string]
The object placeholder represents an object expression that evaluates to an instance of the
control. The string is a comment to be associated with the entered value.

Remarks
This property is not available in Build Mode. This property returns a string. This property is
only utilized if a new Value is entered for this cell as well. Order does not matter, but a
Comment cannot be entered in the PI Archive without a Value.

CurrentQuestionable
Returns a Boolean to indicate if the current value is marked as questionable in the PI Archive
and is ready to be confirmed.

Syntax
object.CurrentQuestionable
The object placeholder represents an object expression that evaluates to an instance of the
control.

62
 OSIsoft DataSheet Control

Remarks
This property is not available in Build Mode. This property returns a Boolean.

CurrentTimeStamp
Returns or sets the TimeStamp of the value in the currently-selected cell.

Syntax
object.CurrentTimeStamp [= timestamp]
The object placeholder represents an object expression that evaluates to an instance of the
control. The timestamp is a variant that represents the timestamp at which the entered value
should be written. See Remarks for details.

Remarks
This property is not available in Build Mode. This property returns a variant. Valid Values for
this property include a PI Time String ("*", "*-1d", etc), a PI Time object, or a literal string
representing a valid time string ("3-mar-05 01:22:33").
This property is only utilized if a new Value is entered for this cell as well. Order does not
matter, but a TimeStamp cannot be entered in the PI Archive without a Value.

CurrentUnitBatch
Returns the PISDK.PIUnitBatch that corresponds to the current cell.

Syntax
object.CurrentUnitBatch
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
This property is not available in Build Mode, and is read only in Run Mode.
The CurrentValueSet and CurrentUnitBatch properties can be used to determine the selected
cell. If no cell is selected, both will return Nothing.

CurrentValue
Returns or sets the value in the currently-selected cell.

Syntax
object.CurrentValue [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value placeholder represents the new value to be placed in the current cell.

63
Programmatic Interface

Remarks
This property is not available in Build Mode. This property returns a string.

CurrentValueSet
Returns the ValueSet that corresponds to the current cell.

Syntax
object.CurrentValueSet
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
This property is not available in Build Mode, and is read only in Run Mode. This property
returns a reference to a ValueSet object.
The CurrentValueSet and CurrentUnitBatch properties can be used to determine the selected
cell. If no cell is selected, both will return Nothing.

CurrentValueSetIndex
Returns the index of the currently selected ValueSet.

Syntax
object.CurrentValueSetIndex
The object placeholder represents an object expression that evaluates to an instance of the
control. The integer is a value between 1 and the value of the DisplayedValueSetCount
property.

CustomNameSET
Returns or sets the name of the terminology set used in the control. By default, batch
terminology is used, which is the "<Standard>" custom name set.

Syntax
object.CustomNameSet [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is the name of the custom name set applied to the control.

DataInclusion
Returns or sets the specification of what data are chosen for display within the time range.

64
 OSIsoft DataSheet Control

Syntax
object.DataInclusion [= value]
The object placeholder represents an object expression that evaluates to an instance of the
OSIsoft DataSheet Control. The value is an expression specifying what data will be displayed
from the time range, as shown in Settings.

Settings
The settings for value are:
Constant Description
0 All PI Unit Batches in the time range are displayed.
1 The first PI Unit Batches in the time range are displayed.
2 (Default) The last PI Unit Batches in the time range are displayed.

Remarks
When the value of the DataInclusion property is zero (IncludeAll), all PI Unit Batches that
fall completely within the time range specified by the StartTime and EndTime properties are
displayed. When the value is one (IncludeFirst) or two (IncludeLast), the CellsPerValueSet
property controls the number of PI Unit Batches that appear.
The members of the PIDEDataInclusions enumeration set can be used to assign values to and
compare values with the control's DataInclusion property.
Any PIUnitBatch is eligible for inclusion if it has an end time on or after the control's
StartTime, and a start time on or before the control's EndTime.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Value (380) The minimum allowable value is zero, and the maximum is two.

DataQuarantine
Sets and returns if the control should mark new data points as questionable

Syntax
object.DataQuarantine [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is an expression that determines whether or not committed entered values
will be marked as questionable.

Settings
The settings for value are:

65
Programmatic Interface

Constant Description
True When a new value is being committed it will mark the data as Questionable.
False (Default) Data will be entered into the archive normally.

Remarks
See the Data Entry section for a description of the behavior.

DefaultCreateBatchID
Returns or sets the default Batch ID used when creating a new PI Unit Batch.

Syntax
object.DefaultCreateBatchID [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is the Batch ID to be used by default.

DefaultCreateEndTime
Returns or sets the default end time used when creating a new PI Unit Batch.

Syntax
object.DefaultCreateEndTime [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is the end time to be used by default.

DefaultCreateProcedure
Returns or sets the default procedure name used when creating a new PI Unit Batch.

Syntax
object.DefaultCreateProcedure [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is the procedure name to be used by default.

DefaultCreateStartTime
Returns or sets the default start time used when creating a new PI Unit Batch.

Syntax
object.DefaultCreateStartTime [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is the start time to be used by default.

66
 OSIsoft DataSheet Control

DisplayedBatchCount
Returns the number of batches (represented by columns) in the grid.

Syntax
object.DisplayedBatchCount
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
See the Data Entry section for a description of the behavior.

DisplayedValueSetCount
Returns the number of ValueSets (represented by rows) in the grid.

Syntax
Object.DisplayedBatchCount
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
See the Data Entry section for a description of the behavior.

EnableContextSwitching
Returns or sets whether or not the control can respond to the Module Context Add-In in a
ProcessBook display.

Syntax
object.EnableContextSwitching [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression specifying whether or not the control can respond
to the Module Context Add-In in ProcessBook.

Settings
The settings for value are:
Constant Description
True Allows control to respond to the user changing the ProcessBook
Module context.
False (Default) Prevents control from responding the user changing the
ProcessBook Module context.

67
Programmatic Interface

Enabled
Returns or sets whether or not the control can respond to user-generated events.

Syntax
object.Enabled [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression specifying whether or not the control can respond
to user-generated events, as shown in Settings.

Settings
The settings for value are:
Constant Description
True (Default) Allows control to respond to user events.
False Prevents control from responding to user events.

EndTime
Returns or sets the end time of the time range from which displayed PI Unit Batches may be
drawn.

Syntax
object.EndTime [= timestamp]
The object placeholder represents an object expression that evaluates to an instance of the
control. The timestamp value is a variant expression specifying a specific date and time, as
described in Settings.

Settings
The timestamp can be any valid PI Time Format, as described in Appendix B of the PI Server
Reference Guide.

Remarks
If the EndTime is set to a string, the value must be a valid PI Time Format. See Appendix B
of the PI Server Reference Guide for more information on formatting PI Times. A date is
interpreted as a local date and time and all numeric values are interpreted as the number of
seconds since UTC 1970. The EndTime property can also be set equal to a valid PITime or
PITime subclass reference.
When retrieving PI Unit Batches, only those with an end time on or after the control's
StartTime, and a start time on or before the control's EndTime are included.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:

68
 OSIsoft DataSheet Control

Error Description
tseFRACTIONSNOTALLOWED Fractional intervals are not allowed.
tseNAMENOTFOUND Name not found in collection.
tseTIMEINVALID The time is invalid.
tseTIMESTAMPTODATE Unable to convert a PI timestamp to a DATE.
tseDATETOTIMESTAMP Unable to transform a DATE into a PItimestamp.

EnteredBackColor
Returns or sets the background color used in data cells in the control that hold uncommitted
data.

Syntax
object.EnteredBackColor [= color]
The object placeholder represents an object expression that evaluates to an instance of the
control. The color value is a long integer expression specifying what background color
should be used for all data cells in the control that contain uncommitted data, as described in
Settings.

Settings
The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a
number in this range equals 0; the lower three bytes, from least to most significant byte,
determine the amount of red, green and blue, respectively. The red, green and blue
components are each represented by a number between 0 and 255 (&HFF). If the high byte is
not 0, the value represents a system color; see Microsoft Visual Basic for Application's
SystemColorConstants enumeration set for more information.

Remarks
The EnteredBackColor property applies only to data cells that hold uncommitted data, not
other data cells, or column or row header cells. To control the background color of data cells
that hold committed data, use the BackColor property. To control the background color of
header cells, use the HeaderBackColor property.

EnteredFont
Returns or sets the font used by data cells in the control that hold uncommitted data.

Syntax
Set object.EnteredFont [= font]
The object placeholder represents an object expression that evaluates to an instance of the
control. The font object is the font to use for data cells in the control that hold uncommitted
data.

69
Programmatic Interface

Remarks
The EnteredFont property applies only to data cells that hold uncommitted data, not data cells
that hold committed data, or column or row header cells. To control the font of data cells that
hold committed data, use the Font property. To control the font of header cells, use the
HeaderFont property. The default value of the EnteredFont property is the font of the
container at the time the control is sited, with the Bold attribute added if not already present.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Value (380) The object assigned to the EnteredFont property
must be a StdFont.

EnteredForeColor
Returns or sets the foreground color used by data cells in the control that hold uncommitted
data.

Syntax
object.EnteredForeColor [= color]
The object placeholder represents an object expression that evaluates to an instance of the
control. The color value is a long integer expression specifying what foreground color should
be used by data cells in the control that hold uncommitted data, as described in Settings.

Settings
The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a
number in this range equals 0; the lower three bytes, from least to most significant byte,
determine the amount of red, green and blue, respectively. The red, green and blue
components are each represented by a number between 0 and 255 (&HFF). If the high byte is
not 0, the value represents a system color; see Microsoft Visual Basic for Application's
SystemColorConstants enumeration set for more information.

Remarks
The EnteredForeColor property applies only to data cells that hold uncommitted data, not to
data cells that hold committed data, or to column or row header cells. To control the
foreground color of data cells that hold committed data, use the ForeColor property. To
control the foreground color of header cells, use the HeaderForeColor property.

EnterNavigation
Returns or sets the way in which focus is advanced through the control when the enter key is
pressed.

70
 OSIsoft DataSheet Control

Syntax
object.EnterNavigation [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a long integer expression specifying the order in which focus advances
through the control when the enter key is pressed.

Settings
The settings for value are:
Constant Description
0 Focus moves left to right, then top to bottom.
1 (Default) Focus moves top to bottom, then left to right.
2 None. Pressing the enter key does not advance focus.

Remarks
The members of the PIDEEnterNavigationTypes enumeration set can be used to assign
values to or compare values with the EnterNavigation property, in place of the literal
constants shown in Settings.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Value (380) The minimum allowable value is zero, and the maximum is two.

ESignatureDescription
Sets and returns the text that is displayed on the E-Signature sign in box. Text is recorded
with each ESignature.

Syntax
object.ESignatureDescription [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a string that is displayed on the E-Signature.

ESignatureGroup
Sets and returns the name of the PI User Group to which the signing user must belong.

Syntax
object.ESignatureGroup [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a string that is the name of the PI User Group to which the signing user
must belong.

71
Programmatic Interface

ESignatureRequired
Sets and returns if the control should require a login to verify the user's identity before storing
data in the PI Archive

Syntax
object.ESignatureRequired [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression that determines if the user is prompted to login
when an entered value is committed, as described in Settings.

Settings
The settings for value are:
Constant Description
True When an entered value is being committed a Dialog will require the user to verify
his/her credentials.
False (Default) No extra confirmation is required.

Remarks
See the Data Entry section for a description of the behavior.

Font
Returns or sets the font used by all data cells in the control.

Syntax
Set object.Font [= font]
The object placeholder represents an object expression that evaluates to an instance of the
control. The font object is the font used for all data cells.

Remarks
The Font property applies only to data cells, not column or row header cells. To control the
font of header cells, use the HeaderFont property. The default Font is the font of the container
at the time the control is sited.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Value (380) The object assigned to the Font property must be a StdFont.

72
 OSIsoft DataSheet Control

ForeColor
Returns or sets the foreground color used by all data cells in the control.

Syntax
object.ForeColor [= color]
The object placeholder represents an object expression that evaluates to an instance of the
control. The color value is a long integer expression specifying what foreground color should
be used by all data cells in the control, as described in Settings.

Settings
The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a
number in this range equals 0; the lower three bytes, from least to most significant byte,
determine the amount of red, green and blue, respectively. The red, green and blue
components are each represented by a number between 0 and 255 (&HFF). If the high byte is
not 0, the value represents a system color; see Microsoft Visual Basic for Application's
SystemColorConstants enumeration set for more information.

Remarks
The ForeColor property applies only to data cells, not column or row header cells. To control
the foreground color of header cells, use the HeaderForeColor property.
The ForeColor property is applied to data cells whose values fall within all specification
pairs, or that reside in a ValueSet that has no specification pairs. There are many reasons why
data in a cell may not be shown in the color specified by ForeColor; see Understanding the
Application of Colors and Fonts (page 36) for a complete explanation.
The default value of the ForeColor property is the forecolor of the container at the time the
control is sited.

HeaderBackColor
Returns or sets the background color used in all header cells in the control.

Syntax
object.HeaderBackColor [= color]
The object placeholder represents an object expression that evaluates to an instance of the
control. The color value is a long integer expression specifying what background color
should be used for all header cells in the control, as described in Settings.

Settings
The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a
number in this range equals 0; the lower three bytes, from least to most significant byte,
determine the amount of red, green and blue, respectively. The red, green and blue
components are each represented by a number between 0 and 255 (&HFF). If the high byte is
not 0, the value represents a system color; see Microsoft Visual Basic for Application's
SystemColorConstants enumeration set for more information.

73
Programmatic Interface

Remarks
The HeaderBackColor value applies only to header cells, not cells where data is displayed or
entered. To control the background color of data cells, use the BackColor property.

HeaderFont
Returns or sets the font used by all header cells in the control.

Syntax
Set object.HeaderFont [= font]
The object placeholder represents an object expression that evaluates to an instance of the
control. The font object is the font used for all header cells.

Remarks
The HeaderFont property applies only to header cells, not cells where data is displayed or
entered. To control the font of data cells, use the Font property. The default value of the
HeaderFont property is the font of the container at the time the control is sited.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Value (380) The object assigned to the HeaderFont property must be a
StdFont.

HeaderForeColor
Returns or sets the foreground color used by all header cells in the control.

Syntax
object.HeaderForeColor [= color]
The object placeholder represents an object expression that evaluates to an instance of the
control. The color value is a long integer expression specifying what foreground color should
be used by all header cells in the control, as described in Settings.

Settings
The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a
number in this range equals 0; the lower three bytes, from least to most significant byte,
determine the amount of red, green and blue, respectively. The red, green and blue
components are each represented by a number between 0 and 255 (&HFF). If the high byte is
not 0, the value represents a system color; see Microsoft Visual Basic for Application's
SystemColorConstants enumeration set for more information.

74
 OSIsoft DataSheet Control

Remarks
The HeaderForeColor property applies only to header cells, not cells where data is entered or
displayed. To control the foreground color of data cells, use the ForeColor property.

Interval
Returns or sets the frequency with which data displayed in the control is updated.

Syntax
object.Interval [= milliseconds]
The object placeholder represents an object expression that evaluates to an instance of the
control. The milliseconds value is an expression specifying the number of milliseconds
between data updates.

Settings
The minimum value of this property is 1000, equivalent to one second, and the maximum
value is 60000 (60 seconds). The default value is 5000 (5 seconds).

Remarks
When the control is first displayed, all data is current. At this time, the control establishes two
"event pipes" for monitoring the data that it displays. Each time the Interval elapses, these
event pipes are checked for new PI Unit Batches and new values.
Calling the Refresh method ensures that all displayed data is current.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Value (380) The minimum allowable value is 1000, and the maximum is
60000.

LogLevel
Sets the logging level of the control.

Syntax
object.LogLevel [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a long integer expression specifying what (if any) information is written
to the control's log file.

Settings
The settings for value are:

75
Programmatic Interface

Constant Description
0 (Default) None. No log is created.
1 Errors Only. Only unexpected errors are written to the control's log file.
2 All. Log all major function calls in addition to any errors.

Remarks
The members of the PIDELogLevel enumeration set can be used to assign values to or
compare values with the LogLevel property, in place of the literal constants shown in
Settings. The LogAll selection should not be used unless directed by Tech Support.

NewPIUnitBatches
Indicates that new PI Unit Batches have been found but not yet displayed.

Syntax
object.NewUnitBatches
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
This property is not available in Build Mode, and is read only in Run Mode.
This Boolean property returns True if there are new PI Unit Batches that have not yet been
displayed, and False otherwise.
New PI Unit Batches will not be displayed if doing so would require dropping from display a
PI Unit Batch that has focus or that holds uncommitted entered values.

ProductBatchFilter
Returns or sets whether the control displays a dialog before discarding uncommitted values.

Syntax
object.PromptChangesPending [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression that determines if the user is warned before
uncommitted values are discarded, as described in Settings.

Settings
The settings for value are:
Constant Description
True When uncommitted data is to be discarded, the control displays a dialog warning
user of same before doing so.
False (Default) No warning dialog is displayed.

76
 OSIsoft DataSheet Control

Remarks
If the PromptChangesPending property is True, when the control is performing an operation
that would cause uncommitted values to be discarded it will notify the user via a modal
dialog box. This dialog box will allow the user to cancel the operation that would cause the
uncommitted values to be discarded, commit the changes before proceeding, or to proceed
with the operation and discard the changes.
The actions that could cause the control to discard uncommitted values are:
• Clicking the Revert popup menu item
• Clicking the Revert All popup menu item
• Clicking the Refresh popup menu item
• Invoking the Revert method of the programmatic interface
• Invoking the RevertAll method of the programmatic interface
• Invoking the Refresh method of the programmatic interface

PromptComment
Returns or sets whether the control displays a dialog before committing entered values.

Syntax
object.PromptComment [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression that determines if the user is prompted for a
comment when an entered value is committed, as described in Settings.

Settings
The settings for value are:
Constant Description
True When an entered value is being committed, the control displays a dialog allowing
the user to provide a comment to accompany the entered value.
False (Default) No comment dialog is displayed.

Remarks
If the PromptComment property is True, when the control is about to commit entered values
to PI, it will provide the user an opportunity to comment of the entered values via a modal
dialog box. The user will not be required to enter a comment in the dialog box, but could
instead simply close the dialog and continue.
The actions that could cause the control to prompt the user for a comment to accompany
entered values are:
Clicking the Commit popup menu item
Clicking the Commit All popup menu item
Invoking the Commit method of the programmatic interface

77
Programmatic Interface

Invoking the CommitAll method of the programmatic interface

Advancing focus away from a cell where a value has been entered, when the AutoCommit
property is True
If more than one entered value is being committed at the same time, the user will only be
provided the opportunity to enter a single comment, which will accompany all of the entered
values being committed at that time.

RangeEnforcement
Returns or sets the way in which Ranges are enforced against entered data.

Syntax
object.RangeEnforcement [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a long integer expression specifying if/how entered data is affected by
Ranges.

Settings
The settings for value are:
Constant Description
0 (Default) None. Ranges are used for display purposes only; any value can be
entered.
1 Prompt. When a value is entered that falls outside of any Range for the ValueSet
in which the value was entered, the user will be prompted to confirm the entry.

Remarks
The members of the OSIDERangeEnforcements enumeration set can be used to assign values
to or compare values with the RangeEnforcement property, in place of the literal constants
shown in Settings.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Value (380) The minimum allowable value is zero, and the maximum is one.

RangeMaximumName
Returns or sets the default name used to identify the high (maximum) limit of a range.

Syntax
object.RangeMaximumName [= value]

78
 OSIsoft DataSheet Control

The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a string that will be used by default to describe the maximum limit of a
new range.

Remarks
The default value is Maximum.

RangeMinimumName
Returns or sets the default name used to identify the low (minimum) limit of a range.

Syntax
object.RangeMinimumName [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a string that will be used by default to describe the minimum limit of a
new range.

Remarks
The default value is Minimum.

Redraw
Returns or sets whether or not the control should refresh.

Syntax
object.Redraw [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is either true or false.

Settings
If this property is set to True, the control will work normally. When set to False, no queries
will be made to the PIServer for new Unit Batches

Remarks
This property is not persisted, and will be set to True on load. For example if Redraw is set to
False, and then the containing page (ProcessBook or otherwise) is saved and reloaded,
Redraw will be set to True again.

RowHeight
Returns or sets the height of each row in logical twips.

Syntax
object.RowHeight [= height]

79
Programmatic Interface

The object placeholder represents an object expression that evaluates to an instance of the
control. The height value is a long expression specifying the height of all rows in the control,
as described in Settings.

Settings
The RowHeight property assumes units of twips. The default value is 330, the minimum
value is zero, and the maximum value is 2147483647.

Remarks
After the RowHeight property is applied to the heights of the rows, the user may interactively
resize each row individually.

ScrollBars
Returns or sets which scroll bars will be displayed, if any.

Syntax
object.ScrollBars [= value]
The object placeholder represents an object expression that evaluates to an instance of the
OSIsoft DataSheet Control. The value is an expression specifying which scroll bars will be
displayed, as shown in Settings.

Settings
The settings for value are:
Constant Description
0 None. No scroll bars will be displayed.
1 Horizontal. A horizontal scroll bar will be displayed.
2 Vertical. A vertical scroll bar will be displayed.
3 (Default) Both. Both vertical and horizontal scroll bars will be displayed.

Remarks
The members of the PIDEScrollBars enumeration set can be used to assign values to or
compare values with the ScrollBars property, in place of the literal constants shown in
Settings.
Scroll bars appear on the control only if its contents extend beyond its borders and the value
of the ScrollBars property indicates that scroll bars should be present. If the ScrollBars
property is set to None, the control will not have scroll bars, regardless of its contents. If the
control has no scroll bars in either direction, it will not allow any scrolling in that direction,
even if the user uses the keyboard to select a cell that is beyond the visible area of the control.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:

80
 OSIsoft DataSheet Control

Error Description
Invalid Property Value (380) The minimum allowable value is zero, and the maximum is
three.

ShowEngineeringUnits
Returns or sets whether the engineering units of the PI Point to which each alias refers are
included in the header column.

Syntax
object.ShowEngineeringUnits [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression specifying whether or not engineering units for PI
Points are shown in the header column.

Settings
The settings for value are:
Constant Description
True Engineering units are displayed.
False (Default) Engineering units are not displayed.

ShowGridlines
Returns or sets whether gridlines appear between rows and columns.

Syntax
object.ShowGridlines [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression specifying whether or not gridlines are displayed
to separate rows and columns, as shown in Settings.

Settings
The settings for value are:
Constant Description
True (Default) Gridlines are displayed.
False Gridlines are not displayed.

ShowPopupMenu
Returns or sets whether or not the control's popup menu is displayed.

81
Programmatic Interface

Syntax
object.ShowPopupMenu [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value is a Boolean expression that determines whether or not the control's popup
menu is shown.

Settings
The settings for value are:
Constant Description
True (Default) The control's popup menu is displayed when the upper-
left-most header cell in the control is right-clicked.
False The control's popup menu is never displayed.

Remarks
The control's popup menu can only be invoked by right-clicking the upper-left-most cell in
the control's header.

StartTime
Returns or sets the start time of the time range from which displayed PI Unit Batches may be
drawn.

Syntax
object.StartTime [= timestamp]
The object placeholder represents an object expression that evaluates to an instance of the
control. The timestamp value is a variant expression specifying a specific date and time, as
described in Settings.

Settings
The timestamp can be any valid PI Time Format, as described in Appendix B of the PI Server
Reference Guide.

Remarks
If the StartTime is set to a string, the value must be a valid PI Time Format. See Appendix B
of the PI Server Reference Guide for more information on formatting PI Times. A date is
interpreted as a local date and time and all numeric values are interpreted as the number of
seconds since UTC 1970. The StartTime property can also be set equal to a valid PITime or
PITime subclass reference.
When retrieving PI Unit Batches, only those with an end time on or after the control's
StartTime, and a start time on or before the control's EndTime are included.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:

82
 OSIsoft DataSheet Control

Error Description
tseFRACTIONSNOTALLOWED Fractional intervals are not allowed.
tseNAMENOTFOUND Name not found in collection.
tseTIMEINVALID The time is invalid.
tseTIMESTAMPTODATE Unable to convert a PItimestamp to a DATE.
tseDATETOTIMESTAMP Unable to transform a DATE into a PItimestamp.

Unit
Returns or sets the PI Unit Module to which the control is bound.

Syntax
Set object.Unit [= module]
The object placeholder represents an object expression that evaluates to an instance of the
control. The module placeholder represents an object expression that evaluates to a PI Unit
Module.

Remarks
When the Unit property is changed, a new value for the UnitPath property is automatically
calculated.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Assignment (450) The PIModule assigned to the Unit property must have its
IsPIUnit property set to True.

UnitBatchIDFilter
Returns or sets the string used to filter the Batch IDs of the returned unit batches.

Syntax
object.UnitBatchIDFilter [= filter]
The object placeholder represents an object expression that evaluates to an instance of the
control. The filter is a string pattern to which the Batch ID of all displayed Unit Batches must
conform.

Remarks
This property will filter the displayed unit batches by BatchID. The default is *. To filter out
all unit batches except those with a Batch ID that starts with the letter A this property should
be set to A*.

83
Programmatic Interface

When this property is set, a refresh is triggered unless there are pending changes in the
control.

UnitPath
Returns or sets the path to the PI Unit Module to which the control is bound.

Syntax
object.UnitPath [= path]
The object placeholder represents an object expression that evaluates to an instance of the
control. The path placeholder represents a string that is a path to a PI Unit Module.

Remarks
When the UnitPath property is changed, the value of the Unit property is also changed, to
reference the PI Unit Module identified by the new value for the UnitPath property.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Invalid Property Assignment (450) The PIModule identified by the path assigned to the
UnitPath property must have its IsPIUnit property set to
True.

UnitProductFilter
Returns or sets the string used to filter the products of the returned batches.

Syntax
object.UnitBatchIDFilter [= filter]
The object placeholder represents an object expression that evaluates to an instance of the
control. The filter is a string pattern to which the Product of all displayed Unit Batches must
conform.

Remarks
This property will filter the displayed unit batches by Product. The default is *. To filter out
all unit batches except those with a Product that starts with the letter A this property should
be set to A*.
When this property is set, a refresh is triggered unless there are pending changes in the
control.

ValueSets
Returns a OSIDEValueSets object, which is a collection of OSIDEValueSet objects. Each
OSIDEValueSet in the collection may identify a PI point from which data is displayed, and

84
 OSIsoft DataSheet Control

possibly for which data is to be entered, or indicate that some other data is to be displayed
(such as batch ID, start time, etc.).

Syntax
object.ValueSets(index)
The object placeholder represents an object expression that evaluates to an instance of the
control. The index value uniquely identifies the row to be retrieved from the collection.

Remarks
The index value may be an integer index, or a string key that is the name of the
OSIDEValueSet sought.
The ValueSets collection is an ordered collection, where the order of the members
corresponds to the order of the ValueSets in the control.

WriteMode
Returns or sets the behavior of the control when a data point exists in the archive at the same
timestamp of an entered value being committed.

Syntax
object.WriteMode [= value]
The object placeholder represents an object expression that evaluates to an instance of the
control. The value must be an enumeration of type OSIDEWriteModes.

Settings
The settings for value are:
Constant Description
0 (Default) On Insert the control will always insert a new value even if one already
exists.
1 If a value exists at the exact timestamp, it will be overwritten with the new value.

Remarks
The members of the OSIDEWriteModes enumeration set can be used to assign values to or
compare values with the WriteMode property, in place of the literal constants shown in
Settings.

WriteTime
Returns or sets the timestamp used by default when a value is written to the archive.

Syntax
object.WriteTime [= value]

85
Programmatic Interface

The object placeholder represents an object expression that evaluates to an instance of the
control. The value indicates what timestamp should be used by default for writing data, and
must be one of the integers specified in the Settings table below.

Settings
The settings for value are:
Constant Description
1 (Default) Use the start time of the unit batch as the timestamp for the value
written.
2 Use the end time of the unit batch as the timestamp for the value written.

Remarks
The members of the OSIDEWriteTime enumeration set can be used to assign values to or
compare values with the WriteTime property, in place of the literal constants shown in
Settings. However, only the identified members of the enumeration set apply; the entire
enumeration set is not supported by this property at this time.

Methods

Invoking a method on the control will cause it to take a particular action. In some cases,
changing property values or invoking methods can cause errors to be raised. It is the
responsibility of the container to trap and deal with these errors. When possible, errors that
might occur are identified for each property and method.

AutoWidth
Sets the width of columns and the height of rows to best display their content.

Syntax
object.AutoWidth
The object placeholder represents an object expression that evaluates to an instance of the
control.

CellComment
Returns the comment for an uncommitted value for a cell in the grid.

Syntax
object.CellComment(BatchIndex, ValueSetIndex)
The object placeholder represents an object expression that evaluates to an instance of the
control. The BatchIndex is the integer index of the cell's row, and the ValueSetIndex is the
integer index of the cell's column.

86
 OSIsoft DataSheet Control

Remarks
This method is not available in Build Mode.
This method returns a string value which is the comment True if the value in the cell is
questionable and False otherwise.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Batch Index out of Range Batch Index must be between 1 and the DisplayedBatchCount
property.
ValueSet Index out of Range ValueSet Index must be between 1 and the
DisplayedValueSetCount property.

CellQuestionable
Returns a Boolean value that indicates when True that the contents of the current cell are
flagged as Questionable.

Syntax
object.CellQuestionable(BatchIndex, ValueSetIndex)
The object placeholder represents an object expression that evaluates to an instance of the
control. he BatchIndex is the integer index of the cell's row, and the ValueSetIndex is the
integer index of the cell's column.

Remarks
This method is not available in Build Mode.
This method returns a Boolean value which is True if the value in the cell is questionable and
False otherwise.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Batch Index out of Range Batch Index must be between 1 and the DisplayedBatchCount
property.
ValueSet Index out of Range ValueSet Index must be between 1 and the
DisplayedValueSetCount property.

87
Programmatic Interface

CellUncomittedData
Returns the state for a cell in the grid.

Syntax
object.CellQuestionable(BatchIndex, ValueSetIndex)
The object placeholder represents an object expression that evaluates to an instance of the
control. The BatchIndex is the integer index of the cell's row, and the ValueSetIndex is the
integer index of the cell's column.

Remarks
This method is not available in Build Mode.
This method returns a Boolean value which is True if the value in the cell is waiting to be
committed and False otherwise.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Batch Index out of Range Batch Index must be between 1 and the DisplayedBatchCount
property.
ValueSet Index out of Range ValueSet Index must be between 1 and the
DisplayedValueSetCount property.

CellUnitBatch
Returns the PIUnitBatch object for a cell in the grid.

Syntax
object.CellUnitBatch(BatchIndex)
The object placeholder represents an object expression that evaluates to an instance of the
control. The BatchIndex is the integer index of the cell's row.

Remarks
This method is not available in Build Mode.
This method returns a PIUnitBatch object reference which is the current PIUnitBatch for that
Batch Index.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:

88
 OSIsoft DataSheet Control

Error Description
Batch Index out of Range Batch Index must be between 1 and the DisplayedBatchCount
property.

CellValue
Returns the current value for a cell in the grid.

Syntax
object.CellValue(BatchIndex, ValueSetIndex)
The object placeholder represents an object expression that evaluates to an instance of the
control. The BatchIndex is the integer index of the cell's row, and the ValueSetIndex is the
integer index of the cell's column.

Remarks
This method is not available in Build Mode.
This method returns a string of the current cell value. If there is no uncommitted value, the
string is the last value in the archive between the Start Time and End Time of the batch. If
there is an uncommitted value, the uncommitted value is returned.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Batch Index out of Range Batch Index must be between 1 and the DisplayedBatchCount
property.
ValueSet Index out of Range ValueSet Index must be between 1 and the
DisplayedValueSetCount property.

CellValueSet
Returns the ValueSet object for a cell in the grid.

Syntax
object.ValueSet(ValueSetIndex)
The object placeholder represents an object expression that evaluates to an instance of the
control. The ValueSetIndex is the integer index of the cell's column.

Remarks
This method is not available in Build Mode.

89
Programmatic Interface

This method returns a OSIDEValueSet object reference which is the current ValueSet for that
ValueSet Index.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
ValueSet Index out of Range ValueSet Index must be between 1 and the
DisplayedValueSetCount property.

CellWriteTime
Returns the OSIDEWriteTime enumeration value for a cell, which identifies the type of
timestamp that will be used when the uncommitted value in the cell is committed.

Syntax
object.CellWriteTime(BatchIndex, ValueSetIndex)
The object placeholder represents an object expression that evaluates to an instance of the
control. The BatchIndex is the integer index of the cell's row, and the ValueSetIndex is the
integer index of the cell's column.

Remarks
This method is not available in Build Mode.
This method returns an enumeration of OSIDEWriteTime for the current cell value. If there
is no uncommitted value, the value is WriteTimeNone.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Batch Index out of Range Batch Index must be between 1 and the DisplayedBatchCount
property.
ValueSet Index out of Range ValueSet Index must be between 1 and the
DisplayedValueSetCount property.

CellWriteTimeOther
Returns the time that the cell will be written to if the WriteTime is set to WriteTimeOther.

Syntax
object.CellWriteTimeOther(BatchIndex, ValueSetIndex)

90
 OSIsoft DataSheet Control

The object placeholder represents an object expression that evaluates to an instance of the
control. The BatchIndex is the integer index of the cell's row, and the ValueSetIndex is the
integer index of the cell's column.

Remarks
This method is not available in Build Mode.
This method returns a string value that represents the time for an uncommitted to be written
to. If there is no uncommitted value, the value is a null string.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
Batch Index out of Range Batch Index must be between 1 and the DisplayedBatchCount
property.
ValueSet Index out of Range ValueSet Index must be between 1 and the
DisplayedValueSetCount property.

Commit
Writes the unsaved data from the current cell to PI.

Syntax
object.Commit
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
If the AutoCommit property is True, calls to the Commit method are ignored.
If an error occurs when writing data to PI, that error will be propagated to the consumer.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
pseWRITEERROR Failed to write the value to the PI Server. The server error is
appended to the error object's Description property.
pseVARIANTTOPIEVENT Unable to convert the passed VARIANT to a PIValue.
pseBADPIVALUE Passed VARIANT contains an unsupported VARIANT type (e.g.
VT_EMPTY). Not all VARIANT types are supported.

91
Programmatic Interface

Error Description
pseOBJECTNOTPITIME A VARIANT passed for a time argument containing an object
(IDispatch pointer) did not contain a PITime object or one of its
derivatives.
pseVARIANTTYPEASTIME A VARIANT passed for a time argument did not contain a variant
type that is supported.
tseTIMEINVALID Invalid time value.
pseVARIANTTIMETODOUBL A VARIANT passed for a timestamp could not be converted to a
E positive number of seconds since 1970.
pseDATETOTIMESTAMP A DATE passed for a timestamp could not be converted to a PI
timestamp.

CommitAll
Writes all unsaved entered data to PI.

Syntax
object.CommitAll
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
If the AutoCommit property is True, calls to the CommitAll method are ignored.
If any error occurs when writing data to PI, the first error will be propagated to the consumer,
after an attempt to commit all values has occurred.

Trappable Errors
In addition to generic errors (such as Out of Memory), the following errors may occur when
this method is invoked:
Error Description
pseWRITEERROR Failed to write the value to the PI Server. The server error is
appended to the error object's Description property.
pseVARIANTTOPIEVENT Unable to convert the passed VARIANT to a PIValue.
pseBADPIVALUE Passed VARIANT contains an unsupported VARIANT type
(e.g. VT_EMPTY). Not all VARIANT types are supported.
pseOBJECTNOTPITIME A VARIANT passed for a time argument containing an object
(IDispatch pointer) did not contain a PITime object or one of its
derivatives.
pseVARIANTTYPEASTIME A VARIANT passed for a time argument did not contain a
variant type that is supported.
tseTIMEINVALID Invalid time value.
pseVARIANTTIMETODOUBLE A VARIANT passed for a timestamp could not be converted to
a positive number of seconds since 1970.

92
 OSIsoft DataSheet Control

Error Description
pseDATETOTIMESTAMP A DATE passed for a timestamp could not be converted to a PI
timestamp.

Confirm
Confirms a value marked as questionable in the current cell.

Syntax
object.Confirm
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
Use this method to confirm a value that is currently selected. If the proper settings are in
place, the user might be prompted for a comment and/or an E-Signature.

ConfirmAll
Confirms a value marked as questionable in the current cell.

Syntax
object.ConfirmAll
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
Use this method to confirm a value that is currently selected. If the proper settings are in
place, the user might be prompted for a comment and/or an E-Signature.

CreatePIUnitBatch
Creates a new PIUnitBatch on the current Unit.
The object placeholder represents an object expression that evaluates to an instance of the
control.
Parameters:
• BatchId — BatchId of new batch
• StartTime — Time the Batch Starts
• EndTime — Time the Batch Ends
• Product — String identifying the product to be stored in the BatchDB

Remarks
The data being sent to the function must be compatible with the data required for a Batch.

93
Programmatic Interface

• Start and End time are required,

• The StartTime must be before the EndTime.
• PIUnitBatches must not overlap.
Batches created with this method may not show up. The data being sent to the function must
be compatible with the data required for a Batch.

NewValueDialog
Opens the New Value dialog for the currently selected cell.

Syntax
object.NewValueDialog
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
Use this method to open the New Value dialog for the currently selected cell. If the cell has
already been edited, but not committed, the dialog will populate with the current values. If no
editing session for the cell has been initiated, then the dialog text boxes will be empty.

Refresh
Forces a complete repaint of the control.

Syntax
object.Refresh
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
Painting the control is handled automatically when no events are occurring. However, there
may be situations where you want the visual appearance of the control updated immediately,
and it is in these situations when the Refresh method should be invoked.

ResetColumnWidth Method
Sets the column width property of the control to equally divide the available horizontal space
across the displayed columns.

Syntax
object.ResetColumnWidth
The object placeholder represents an object expression that evaluates to an instance of the
control.

94
 OSIsoft DataSheet Control

ResetSearchTimes Method
Resets the search start and end times.

Syntax
object.ResetSearchTimes
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
After the Scroll Forward or Scroll Backward methods have been fired, either
programmatically or through the right-click menu, this method an be used to restore the
original search time criteria.

Revert
Discards any uncommitted data in the current cell.

Syntax
object.Revert
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
If the current cell does not hold uncommitted data, calls to the Revert method are ignored.
When uncommitted data is discarded, the content of the cell will revert to what was
previously displayed.

RevertAll
Discards all uncommitted data.

Syntax
object.RevertAll
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
If there is no uncommitted data in the control, calls to the RevertAll method are ignored.
When uncommitted data is discarded, the contents of the cells that had held uncommitted data
will revert to what they previously displayed.

95
Programmatic Interface

ScrollBack
Moves visible set of batches backwards. If the control is set for DataInclusion of All, the
ScrollTimeBackward event will fire when this method is invoked.

Syntax
object.ScrollBack
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
Invoking this method will force a control refresh. If any uncommitted data exists, the user
will be prompted to save or throw away the changes.

ScrollForward
Moves visible set of batches forwards. If the control is set for DataInclusion of All, the
ScrollTimeForward event will fire when this method is invoked.

Syntax
object.ScrollForward
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
If no more batches exist in the archive, no columns will be displayed. Invoking this method
will force a control refresh. If any uncommitted data exists, the user will be prompted to save
or throw away the changes.

Update
Ensures that displayed values are up-to-date, and that the proper set of PI Unit Batches is
displayed.

Syntax
object.Update
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
The Update method is automatically called each time the Interval elapses.

96
 OSIsoft DataSheet Control

Validate Method
Validates the ValueSets and Range aliases that are configured for the control and returns an
array of strings, where each string in the returned array is a warning or error in the
configuration.

Syntax
object.Validate
The object placeholder represents a DataSheet object.

Remarks
Used to see if any aliases are invalid against the current context. Returns aliases that are
invalid against the current unit. Also checks valid numbers for Fixed type ranges. During
rendering invalid aliases are ignored. ValueSets are not rendered and Ranges are not
calculated if either the Maximum or Minimum are invalid. Custom Names are ignored for the
error messages.

Example
Dim aErrors() As String
aErrors = DataSheetControl1.Validate()

Events

The control will raise events when interesting things happen, providing you an opportunity to
respond.

AfterCommit
Occurs after manually entered data in the selected cell is written to PI.

Syntax
Private Sub object_AfterCommit()
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
If the AutoCommit property is True, the AfterCommit event will not fire. If the AutoCommit
property is False, the AfterCommit event fires when the Commit method is invoked, or when
the Commit item in the popup menu is clicked.

AfterCommitAll
Occurs after all pending manually entered data is written to PI.

Syntax
Private Sub object_AfterCommitAll()

97
Programmatic Interface

The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
If the AutoCommit property is True, the AfterCommitAll event fires when a cell where data
has been manually entered loses focus. If the AutoCommit property is False, the
AfterCommitAll event fires when the CommitAll method is invoked, or when the CommitAll
item in the popup menu is clicked.

AfterCommitCell
Occurs after each cell with uncommitted data is committed to the PI Archive .

Syntax
Private Sub object_AfterCommitCell(BatchIndex as Integer,
ValueSetIndex as Integer)
The object placeholder represents an object expression that evaluates to an instance of the
control. BatchIndex is the numerical index of the batch being committed to. ValueSetIndex
is the numerical index of the ValueSet being committed.

Remarks
The AfterCommitCell is fired after each value is committed to the archive. The BatchIndex
and ValueSetIndex can be used to locate the cell. Futher information about the cell can be
retrieved with CellUnitBatch, CellValueSet and other methods.

AfterConfirm
Occurs after questionable data is confirmed.

Syntax
Private Sub object_AfterConfirm()
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
The AfterConfirm event fires when the Confirm method is invoked, or when the Confirm
item in the popup menu is clicked.

AfterConfirmAll
Occurs after all pending manually entered data is written to PI.

Syntax
Private Sub object_AfterConfirmAll()

98
 OSIsoft DataSheet Control

The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
The AfterConfirmAll event fires when the ConfirmAll method is invoked, or when the
ConfirmAll item in the popup menu is clicked.

AfterConfirmCell
Occurs after each cell with unconfirmed data is confirmed in the PI Archive .

Syntax
Private Sub object_AfterConfirmCell(BatchIndex as Integer,
ValueSetIndex as Integer)
The object placeholder represents an object expression that evaluates to an instance of the
control. BatchIndex is the numerical index of the batch being committed to. ValueSetIndex
is the numerical index of the ValueSet being committed.

Remarks
The AfterConfirmCell event is fired after each value is committed to the archive. The
BatchIndex and ValueSetIndex can be used to locate the cell. Futher information about the
cell can be retrieved with CellUnitBatch, CellValueSet and other methods.

AfterRevert
Occurs after the manually entered data in the selected cell is discarded.

Syntax
Private Sub object_AfterRevert()
The object placeholder represents an object expression that evaluates to an instance of the
control.

AfterRevertAll
Occurs after all manually entered data is discarded.

Syntax
Private Sub object_AfterRevertAll()
The object placeholder represents an object expression that evaluates to an instance of the
control.

99
Programmatic Interface

BeforeCommit
Occurs before manually entered data in the selected cell is written to PI.

Syntax
Private Sub object_BeforeCommit(cancel As Boolean)
The object placeholder represents an object expression that evaluates to an instance of the
control. If the cancel value is set to True during the BeforeCommit event procedure, the
entered data will remain in the control, but will not be written to PI.

Remarks
If the AutoCommit property is True, the BeforeCommit event will not fire. If the
AutoCommit property is False, the BeforeCommit event fires when the Commit method is
invoked, or when the Commit item in the popup menu is clicked.
If the BeforeCommit event is canceled, the manually entered data that was to be committed
will remain in the control, and will be included in the next attempt to commit all entered data.
To cancel the Commit, set the Cancel argument of the BeforeCommit event procedure to
True before the event procedure ends.

BeforeCommitAll
Occurs before all pending manually entered data is written to PI.

Syntax
Private Sub object_BeforeCommitAll(cancel As Boolean)
The object placeholder represents an object expression that evaluates to an instance of the
control. If the cancel value is set to True during the BeforeCommitAll event procedure, the
entered data will remain in the control, but will not be written to PI.

Remarks
If the AutoCommit property is True, the BeforeCommitAll event fires when a cell where
data has been manually entered loses focus. If the AutoCommit property is False, the
BeforeCommitAll event fires when the CommitAll method is invoked, or when the
CommitAll item in the popup menu is clicked.
If the BeforeCommitAll event is canceled, the manually entered data that was to be
committed will remain in the control, and will be included in the next attempt to commit all
entered data. To cancel the CommitAll, set the Cancel argument of the BeforeCommitAll
event procedure to True before the event procedure ends.

BeforeCommitCell
Occurs before each cell with uncommitted data is committed to the PI Archive .

Syntax
Private Sub object_BeforeCommitCell(BatchIndex as Integer,
ValueSetIndex as Integer, cancel As Boolean)

100
 OSIsoft DataSheet Control

The object placeholder represents an object expression that evaluates to an instance of the
control. BatchIndex is the numerical index of the batch being committed to. ValueSetindex is
the numerical index of the ValueSet being committed. If the cancel value is set to True
during the BeforeCommitAll event procedure, the entered data will remain in the control, but
will not be written to PI.

Remarks
The BeforeCommitCell is fired before each value is committed to the archive. The
BatchIndex and ValueSetIndex can be used to locate the cell. Futher information about the
cell can be retrieved with CellUnitBatch, CellValueSet and other methods.
If the BeforeCommitCell event is canceled, the manually entered data that was to be
committed for that cell will remain in the control, but other cells being committed at the same
time (using the CommitAll command or method) will be attempted. To cancel a CommitAll
event use the BeforeCommitAll event.

BeforeConfirm
Occurs before questionable values in the grid are confirmed.

Syntax
Private Sub object_BeforeConfirm(cancel As Boolean)
The object placeholder represents an object expression that evaluates to an instance of the
control. If the cancel value is set to True during the BeforeConfirm event procedure, the
Confirm method will be canceled.

Remarks
The BeforeConfirm event fires when the user selects Confirm from the popup, or the Confirm
method is executed.
To cancel the Confirm, set the Cancel argument of the BeforeCommit event procedure to
True before the event procedure ends.

BeforeConfirmAll
Occurs before all Questionable data is confirmed.

Syntax
Private Sub object_BeforeConfirmAll(cancel As Boolean)
The object placeholder represents an object expression that evaluates to an instance of the
control. If the cancel value is set to True during the BeforeConfirmAll event procedure, the
entered data will remain Questionable.

101
Programmatic Interface

Remarks
The BeforeConfirmAll event fires when the user selects ConfirmAll from the popup, or the
ConfirmAll method is executed. If no unconfirmed values exist in the control, the event will
not be raised.
To cancel the ConfirmAll, set the Cancel argument of the BeforeCommitAll event procedure
to True before the event procedure ends.

BeforeConfirmCell
Occurs before each cell with unconfirmed data is confirmed in the PI Archive .

Syntax
Private Sub object_BeforeConfirmCell(BatchIndex as Integer,
ValueSetIndex as Integer, cancel As Boolean)
The object placeholder represents an object expression that evaluates to an instance of the
control. BatchIndex is the numerical index of the batch being committed to. ValueSetindex is
the numerical index of the ValueSet being committed. If the cancel value is set to True
during the BeforeCommitAll event procedure, the data will remain questionable.

Remarks
The BeforeConfirmCell is fired before each value is confirmed in the archive. The
BatchIndex and ValueSetIndex can be used to locate the cell. Further information about the
cell can be retrieved with CellUnitBatch, CellValueSet and other methods.
If the BeforeConfirmCell event is canceled, the data in that cell will remain questionable, but
other cells being confirmed at the same time (using the ConfirmAll command or method) will
be attempted. To cancel a ConfirmAll event use the BeforeConfirmAll event.

BeforeRevert
Occurs before the manually entered data in the selected cell is discarded.

Syntax
Private Sub object_BeforeRevert(cancel As Boolean)
The object placeholder represents an object expression that evaluates to an instance of the
control. If the cancel value is set to True during the BeforeRevert event procedure, the
entered data that was to be discarded will remain in the selected cell.

Remarks
If the BeforeRevert event is canceled, the manually entered data that was to be discarded will
remain in the selected cell. To cancel the Revert, set the Cancel argument of the BeforeRevert
event procedure to True before the event procedure ends.

BeforeRevertAll
Occurs before all manually entered data is discarded.

102
 OSIsoft DataSheet Control

Syntax
Private Sub object_BeforeRevertAll(cancel As Boolean)
The object placeholder represents an object expression that evaluates to an instance of the
control. If the cancel value is set to True during the BeforeRevertAll event procedure, all
entered data that was to be discarded will remain in the control

Remarks
If the BeforeRevertAll event is canceled, all manually entered data that was to be discarded
will remain in the control. To cancel the RevertAll, set the Cancel argument of the
BeforeRevertAll event procedure to True before the event procedure ends.

Change
Occurs when a data cell whose content has been edited loses focus.

Syntax
Private Sub object_Change()
The object placeholder represents an object expression that evaluates to an instance of the
control.

Click
Occurs when the user presses and then releases a mouse button while the mouse pointer is
atop the control.

Syntax
Private Sub object_Click()
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
Clicking an instance of the control generates MouseDown and MouseUp events in addition to
the Click event; to determine which mouse button was clicked (left, right, or middle), use the
MouseUp or MouseDown event instead of the Click event.

DblClick
Occurs when the user presses and then releases a mouse button, then presses and releases the
same button again, all while the mouse pointer is atop the control.

Syntax
Private Sub object_DblClick()
The object placeholder represents an object expression that evaluates to an instance of the
control.

103
Programmatic Interface

Remarks
To determine which mouse button was clicked (left, right, or middle), use the MouseUp or
MouseDown event instead of or in addition to the DblClick event.
If two successive clicks do not occur within the operating system's double-click time limit,
the control will trigger two successive Click events, and a DblClick event will never be
triggered. The double-click time limit may vary, because the user can set the double click
speed in the Control Panel.

EditSessionEnd
Occurs when the editing box is hidden by either pressing the Enter key or when the Edit box
loses focus.

Syntax
Private Sub object_EditSessionEnd()
The object placeholder represents an object expression that evaluates to an instance of the
control.

EditSessionStart
Occurs when a cell is edited.

Syntax
Private Sub object_EditSessionStart()
The object placeholder represents an object expression that evaluates to an instance of the
control.

KeyDown
Occurs when the user presses a key while the control has focus.

Syntax
Private Sub object_KeyDown(keycode As Integer, shift As Integer)
The object placeholder represents an object expression that evaluates to an instance of the
control. The keycode value is an integer that uniquely identifies a key on the keyboard, and
can be evaluated using the KeyCodeConstants enumeration set. The shift value is a packed
integer that identifies the state of the SHIFT, CTRL, and ALT keys at the time the KeyDown
event was triggered, respectively using the three least significant bits, where a one indicates
that the corresponding key was pressed, and a zero indicates not pressed.

Remarks
The KeyDown event is particularly useful when there is interest in function keys, navigation
keys, and distinguishing between the numeric keypad and the rest of the keyboard.

104
 OSIsoft DataSheet Control

The ShiftConstants enumeration set can be used as bit masks against the shift argument, to
determine the state of the SHIFT, CTRL, and ALT keys at the time of the event; the SHIFT
key has a value of 1, the CTRL key a value of 2, and the ALT key a value of 4. Any
combination of these three keys can be pressed at the same time, meaning that the minimum
value of the shift argument is 0, and the maximum value is 7.

Note: The KeyDown event is not triggered when the TAB key is pressed, and will not
trigger when the ENTER key is pressed if there is a Default control on the same
form, or when the ESC key is pressed if there is a Cancel control on the same
form.

KeyPress

Occurs when the user presses and releases an ANSI key while the control has focus.

Syntax
Private Sub object_KeyPress(keyascii As Integer)
The object placeholder represents an object expression that evaluates to an instance of the
control. The keyascii value is an integer that returns a standard numeric ANSI keycode. The
keyascii value is passed by reference; changing it sends a different character to the control,
and setting it to 0 cancels the keystroke so that no character is sent to the control.

Remarks
The KeyPress event can involve any printable keyboard character, the CTRL key combined
with a character from the standard alphabet or one of a few special characters, the ENTER
key, or the BACKSPACE key. As stated, changing the value of the keyascii argument in the
event procedure changes the character sent to the control.
Use the KeyDown and/or KeyUp event procedures to handle any keystroke not recognized by
the KeyPress event, such as function keys, navigation keys, editing keys. Unlike the
KeyDown and KeyUp events, the KeyPress event does not indicate the physical state of the
keyboard, it simply passes a character; KeyPress interprets the uppercase and lowercase of
each character as separate characters.

Note: The ANSI value for the combination of CTRL+@ is 0. Since the KeyPress event
allows you to cancel the keystroke by changing the value of the keyascii argument
to 0, it is impossible to change a keystroke to CTRL+@.

KeyUp
Occurs when the user releases a key while the control has focus.

Syntax
Private Sub object_KeyUp(keycode As Integer, shift As Integer)

105
Programmatic Interface

The object placeholder represents an object expression that evaluates to an instance of the
control. The keycode value is an integer that uniquely identifies a key on the keyboard, and
can be evaluated using the KeyCodeConstants enumeration set. The shift value is a packed
integer that identifies the state of the SHIFT, CTRL, and ALT keys at the time the KeyUp
event was triggered, respectively using the three least significant bits, where a one indicates
that the corresponding key was pressed, and a zero indicates not pressed.

Remarks
The KeyUp event is particularly useful when there is interest in function keys, navigation
keys, and distinguishing between the numeric keypad and the rest of the keyboard.
The ShiftConstants enumeration set can be used as bit masks against the shift argument, to
determine the state of the SHIFT, CTRL, and ALT keys at the time of the event; the SHIFT
key has a value of 1, the CTRL key a value of 2, and the ALT key a value of 4. Any
combination of these three keys can be pressed at the same time, meaning that the minimum
value of the shift argument is 0, and the maximum value is 7.

Note: The KeyUp event is not triggered when the TAB key is pressed, and will not trigger
when the ENTER key is pressed if there is a Default control on the same form, or
when the ESC key is pressed if there is a Cancel control on the same form.

MouseDown
Occurs when the user presses a mouse button while the control has focus.

Syntax
Private Sub object_MouseDown(button As Integer, shift As Integer,
x As Single, y As Single)
The object placeholder represents an object expression that evaluates to an instance of the
control. The button value is a packed integer that identifies the mouse button that was pressed
to cause the event, using the three least significant bits for the left button (bit 0), right button
(bit 1), and middle button (bit 2). The shift value is a packed integer that identifies the state of
the SHIFT, CTRL, and ALT keys at the time the MouseDown event was triggered,
respectively using the three least significant bits, where a one indicates that the corresponding
key was pressed, and a zero indicates not pressed. The x value is a single-precision floating
point number that specifies the horizontal location of the mouse pointer at the time of the
event, relative to the coordinate system of the container, and the y value is a single-precision
floating point number that specifies the vertical location of the mouse pointer at the time of
the event, relative to the coordinate system of the container.

Remarks
Unlike the Click and DblClick events, the MouseDown and MouseUp events tell you which
mouse button was clicked and the status of the keyboard modifiers (SHIFT, CTRL, and ALT)
at the time of the event.
The ShiftConstants enumeration set can be used as bit masks against the shift argument, to
determine the state of the SHIFT, CTRL, and ALT keys at the time of the event; the SHIFT
key has a value of 1, the CTRL key a value of 2, and the ALT key a value of 4. Any

106
 OSIsoft DataSheet Control

combination of these three keys can be pressed at the same time, meaning that the minimum
value of the shift argument is 0, and the maximum value is 7.
The MouseButtonConstants enumeration set can be used as bit masks against the button
argument, to determine which mouse button was pressed. The left button has a value of 1, the
right button a value of 2, and the middle button a value of 4. When the MouseDown event is
triggered, it can only be specific to a single mouse button; therefore the only possible values
of the button argument are 0, 1, 2, and 4.

Note: Whereas the MouseUp and MouseDown events are specific to a single mouse
button, the MouseMove event can occur when any combination of mouse buttons
are pressed. Consequently, the button argument has a different meaning and
different possible values for the MouseMove event as opposed to MouseUp or
MouseDown.

MouseMove
Occurs when the user moves the mouse atop the control.

Syntax
Private Sub object_MouseMove(button As Integer, shift As Integer,
x As Single, y As Single)
The object placeholder represents an object expression that evaluates to an instance of the
control. The button value is a packed integer that identifies the state of the mouse buttons at
the time the event was triggered, using the three least significant bits for the left button (bit
0), right button (bit 1), and middle button (bit 2). The shift value is a packed integer that
identifies the state of the SHIFT, CTRL, and ALT keys at the time the MouseUp event was
triggered, respectively using the three least significant bits, where a one indicates that the
corresponding key was pressed, and a zero indicates not pressed. The x value is a single-
precision floating point number that specifies the horizontal location of the mouse pointer at
the time of the event, relative to the coordinate system of the container, and the y value is a
single-precision floating point number that specifies the vertical location of the mouse pointer
at the time of the event, relative to the coordinate system of the container.

Remarks
The MouseMove event is generated continually as the mouse pointer moves across the
control.
The ShiftConstants enumeration set can be used as bit masks against the shift argument, to
determine the state of the SHIFT, CTRL, and ALT keys at the time of the event; the SHIFT
key has a value of 1, the CTRL key a value of 2, and the ALT key a value of 4. Any
combination of these three keys can be pressed at the same time, meaning that the minimum
value of the shift argument is 0, and the maximum value is 7.
The MouseButtonConstants enumeration set can be used as bit masks against the button
argument, to determine the state of the mouse buttons at the time of the event. The left button
has a value of 1, the right button a value of 2, and the middle button a value of 4. Any
combination of the three mouse buttons can be pressed at the time of the event, meaning that
the minimum value of the button argument is 0, and the maximum value is 7.

107
Programmatic Interface

Note: Whereas the MouseUp and MouseDown events are specific to a single mouse
button, the MouseMove event can occur when any combination of mouse buttons
are pressed. Consequently, the button argument has a different meaning and
different possible values for the MouseMove event as opposed to MouseUp or
MouseDown.

MouseUp
Occurs when the user releases a mouse button while the control has focus.

Syntax
Private Sub object_MouseUp(button As Integer, shift As Integer, x
As Single, y As Single)
The object placeholder represents an object expression that evaluates to an instance of the
control. The button value is a packed integer that identifies the mouse button that was
released to cause the event, using the three least significant bits for the left button (bit 0),
right button (bit 1), and middle button (bit 2). The shift value is a packed integer that
identifies the state of the SHIFT, CTRL, and ALT keys at the time the MouseUp event was
triggered, respectively using the three least significant bits, where a one indicates that the
corresponding key was pressed, and a zero indicates not pressed. The x value is a single-
precision floating point number that specifies the horizontal location of the mouse pointer at
the time of the event, relative to the coordinate system of the container, and the y value is a
single-precision floating point number that specifies the vertical location of the mouse pointer
at the time of the event, relative to the coordinate system of the container.

Remarks
Unlike the Click and DblClick events, the MouseDown and MouseUp events tell you which
mouse button was clicked and the status of the keyboard modifiers (SHIFT, CTRL, and ALT)
at the time of the event.
The ShiftConstants enumeration set can be used as bit masks against the shift argument, to
determine the state of the SHIFT, CTRL, and ALT keys at the time of the event; the SHIFT
key has a value of 1, the CTRL key a value of 2, and the ALT key a value of 4. Any
combination of these three keys can be pressed at the same time, meaning that the minimum
value of the shift argument is 0, and the maximum value is 7.
The MouseButtonConstants enumeration set can be used as bit masks against the button
argument, to determine which mouse button was released. The left button has a value of 1,
the right button a value of 2, and the middle button a value of 4. When the MouseUp event is
triggered, it can only be specific to a single mouse button; therefore the only possible values
of the button argument are 0, 1, 2, and 4.

Note: Whereas the MouseUp and MouseDown events are specific to a single mouse
button, the MouseMove event can occur when any combination of mouse buttons
are pressed. Consequently, the button argument has a different meaning and
different possible values for the MouseMove event as opposed to MouseUp or
MouseDown.

108
 Supporting Classes

SelectionChange
Occurs when a cell receives focus.

Syntax
Private Sub object_SelectionChange()
The object placeholder represents an object expression that evaluates to an instance of the
control.

Remarks
The SelectionChange event is raised every time focus within the control moves to a different
cell. You can use the CurrentValueSet and CurrentUnitBatch properties to retrieve
information about the cell to which focus has advanced.

Supporting Classes

OSIDEValueSet Class

An OSIDEValueSet (OSIsoft Data Entry ValueSet) object can be used to display header
information or read-only values, or to allow data entry.

Name Property
Returns or sets the name of the ValueSet.

Syntax
object.Name [= string]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDEValueSet class. The string value is an expression that evaluates to the name used to
uniquely identify the ValueSet within the containing collection, and to therefore retrieve the
ValueSet from the containing collection.

Settings
If specified, the Name property must be unique across all members of a collection of
ValueSets.

Remarks
The ValueSet's name is displayed in the header for the ValueSet.

Ranges Property
Returns the collection of OSIDERange objects for the ValueSet.

109
Programmatic Interface

Syntax
object.Ranges
The object placeholder represents an object expression that evaluates to a OSIDEValueSet
object.

Remarks
The index value may be an integer index or a string key (if one was provided when the range
was added to the collection).
When the RowType of the ValueSet is 2 or greater, the ValueSet's Ranges collection has no
bearing on the ValueSet.

SetType Property
Returns or sets the type of the ValueSet.

Syntax
object.SetType [= value]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDEValueSet class. The value determines if the ValueSet is blank, displays header data,
displays read-only data, or allows data entry.

Settings
The settings for value are:
Constant Description
0 (Default) Read/Write. Displays archive data and supports data
entry.
1 Read-Only. Displays read-only data.
2 Blank. Displays no data.
3 Batch ID. Displays the ID for each PI Unit Batch.
4 Batch State. Displays the state of each PI Unit Batch.
5 Product. Displays the product code for each PI Unit Batch.
6 Start Time. Displays the start of the applicable time range.
7 End Time. Displays the end of the applicable time range.

Remarks
You can use the members of the OSIDEValueSetType enumeration set to compare values to
and assign values to the SetType property.

110
 Supporting Classes

ValueAlias Property
Returns or sets the path to the PI Alias that is relative to the control's unit, and that determines
the PI Point from which data should be displayed, and to which entered data should be
written, for each cell in the row.

Syntax
object.ValueAlias [= name]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDEValueSet class. The name value is a string that specifies the path to the PIAlias,
relative to the PI Unit Module to which the ValueSet's parent control is bound, that identifies
the PIPoint from which data should be displayed, and to which data should be written.

Settings
The ValueAlias property is a string that should be the path to a PI Alias that is a descendant
of the PI Unit Module to which the OSIsoft DataSheet Control is bound.

Remarks
The path to the alias may include one or modules, delimited by backslashes. When modules
are included in the path, the alias name should be at the end of the path, separated from the
last module by a vertical bar.
When the type of the ValueSet is greater than one (not Read-Only or Read/Write), the
ValueSet's ValueAlias property has no bearing on the ValueSet, and is ignored.

OSIDEValueSets Class

An OSIDEValueSets (OSIsoft Data Entry ValueSets) object is a collection of

OSIDEValueSet objects.

Count Property
Returns the number of ValueSets in the collection.

Syntax
object.Count
The object placeholder represents an object expression that evaluates to an instance of the
OSIDEValueSets class.

Remarks
This property is read-only. The minimum value that can be returned is zero, and the
maximum value is the number of ValueSets.

Add Method
Adds a new ValueSet to the collection, and returns a reference to the added ValueSet.

111
Programmatic Interface

Syntax
Set valset = object.Add(name, valueAlias[, before][, after])
The object placeholder represents an object expression that evaluates to an instance of the
OSIsoft DataSheet Control. The valset value is a reference to the OSIDEValueSet object that
is created and added to the collection. The name value is a unique string identifier for the
ValueSet added to the collection, that could be used later to retrieve a reference to it. The
valueAlias value is a string expression that evaluates to the name of a PIAlias on the PI Unit
Module to which is bound the control that owns the collection of ValueSets to which a
ValueSet is being added. The optional before and after values are mutually exclusive—one or
the other may be provided, but not both—and must be a positive long integer, representing
the index of an existing member of the collection, and used to order the ValueSet being
created within the collection.

Remarks
If both a before and an after argument are passed, this method will raise an error.

Item Method
Returns a reference to a specific ValueSet in the collection.

Syntax
object.Item(index)
The object placeholder represents an object expression that evaluates to an instance of the
control. The index value identifies the ValueSet that should be retrieved from the collection.

Remarks
The index value may be an integer index, or a string key that corresponds to the value of the
Name property of a ValueSet in the collection.

Remove Method
Removes a specific ValueSet from the collection.

Syntax
object.Remove(index)
The object placeholder represents an object expression that evaluates to an instance of the
control. The index value identifies the ValueSet that should be removed from the collection.

Remarks
The index value may be an integer index, or a string key that corresponds to the value of the
Name property of a ValueSet in the collection.

Clear Method
Removes all ValueSets from the collection.

112
 Supporting Classes

Syntax
object.Clear
The object placeholder represents an object expression that evaluates to an instance of the
control.

AddedValueSet Event
Indicates that a ValueSet has been added to the collection.

Syntax
Private Sub object_AddedValueSet(AddedSet As
OSIDataEntryControls.OSIDEValueSet)
The object placeholder represents an object expression that evaluates to an instance of the
control. The AddedSet value identifies the ValueSet that has been added to the collection.

RemovedValueSet Event
Indicates that a ValueSet has been removed from the collection.

Syntax
Private Sub object_RemovedValueSet()
The object placeholder represents an object expression that evaluates to an instance of the
control.

ValueSetChanged Event
Indicates that a ValueSet in the collection has been modified.

Syntax
Private Sub object_ValueSetChanged()
The object placeholder represents an object expression that evaluates to an instance of the
control.

OSIDERange Class

An OSIDERange (OSIsoft Data Entry Range) object provides a range of valid values for a
ValueSet.

Name Property
Returns or sets the name of the range.

113
Programmatic Interface

Syntax
object.Name [= string]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The string value is a string expression that evaluates to the name of the
range.

Maximum Property
Returns or sets the relative path to a PIAlias that determines the PIPoint from which the
maximum value for the range is drawn.

Syntax
object.Maximum [= value]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The value is an expression that evaluates to either a fixed numeric value,
or to the relative path to a PIAlias used to identify the PIPoint from which a maximum value
for the specification range is drawn.

Remarks
When the MaximumLimitType property is 0 (Alias), the value of the Maximum property is a
string that holds the path to the alias, relative to the control's unit. The path to the alias may
include one or modules, delimited by backslashes. When modules are included in the path,
the alias name should be at the end of the path, separated from the last module by a vertical
bar.

MaximumBackColor Property
Returns or sets the background color applied to data values displayed in the corresponding
ValueSet that most closely exceed this specification range's maximum value.

Syntax
object.MaximumBackColor [= color]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The color value is a long integer expression specifying what background
color should be used for all data cells in the corresponding ValueSet that most closely exceed
this specification range's maximum value.

MaximumForeColor Property
Returns or sets the foreground color applied to data values displayed in the corresponding
ValueSet that most closely exceed this specification range's maximum value.

Syntax
object.MaximumForeColor [= color]

114
 Supporting Classes

The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The color value is a long integer expression specifying what foreground
color should be used for all data cells in the corresponding ValueSet that most closely exceed
this specification range's maximum value.

MaximumLimitType Property
Returns or sets whether the value of the Maximum property should be interpreted as the name
of an alias, or as a fixed value.

Syntax
object.MaximumLimitType [= type]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The type value is a long integer expression specifying how the value of
the Maximum property should be interpreted, as described in Settings.

Settings
The settings for type are:
Constant Description
0 (Default) Alias. The Maximum property is expected to be the name of an alias.
1 Fixed. The Maximum property is expected to be a fixed value.

Remarks
You can use the members of the PIDELimitTypes enumeration set to compare values to and
assign values to the MaximumLimitType property.

MaximumName Property
Returns or sets the display name for the range's maximum.

Syntax
object.MaximumName [= string]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The string value is the display name that is used to identify the maximum
for the range.

MaximumValue Method
Returns the value of the Range's Maximum at the given time.

Syntax
value = object.MaximumValue(timestamp)

115
Programmatic Interface

The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The timestamp is the time for which the maximum value should be
returned. The value is the Range's maximum value at the given timestamp.

Minimum Property
Returns or sets the relative path to a PIAlias that determines the PIPoint from which the
minimum value for the specification range is drawn.

Syntax
object.Minimum [= value]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The value is an expression that evaluates to either a fixed numeric value,
or to the relative path to a PIAlias used to identify the PIPoint from which a minimum value
for the specification range is drawn.

Remarks
When the MinimumLimitType property is 0 (Alias), the value of the Minimum property is a
string that holds the path to the alias, relative to the control's unit. The path to the alias may
include one or modules, delimited by backslashes. When modules are included in the path,
the alias name should be at the end of the path, separated from the last module by a vertical
bar.

MinimumBackColor Property
Returns or sets the background color applied to data values displayed in the corresponding
ValueSet that come closest to this specification range's minimum value without exceeding it.

Syntax
object.MinimumBackColor [= color]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The color value is a long integer expression specifying what background
color should be used for all data cells in the corresponding ValueSet that most come closest
to this specification range's minimum value without exceeding it.

MinmumForeColor Property
Returns or sets the foreground color applied to data values displayed in the corresponding
ValueSet that come closest to this specification range's minimum value without exceeding it.

Syntax
object.MinimumForeColor [= color]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The color value is a long integer expression specifying what foreground
color should be used for all data cells in the corresponding ValueSet that come closest to this
specification range's minimum value without exceeding it.

116
 Supporting Classes

MinimumLimitType Property
Returns or sets whether the value of the Minimum property should be interpreted as the name
of an alias, or as a fixed value.

Syntax
object.MinimumLimitType [= type]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The type value is a long integer expression specifying how the value of
the Minimum property should be interpreted, as described in Settings.

Settings
The settings for type are:
Constant Description
0 (Default) Alias. The Minimum property is expected to be the name of an alias.
1 Fixed. The Minimum property is expected to be a fixed value.

Remarks
You can use the members of the PIDELimitTypes enumeration set to compare values to and
assign values to the MinimumLimitType property.

MinimumName Property
Returns or sets the display name for the range's minimum.

Syntax
object.MinimumName [= string]
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The string value is the display name that is used to identify the minimum
for the range.

MinimumValue Method
Returns the value of the Range's Minimum at the given time.

Syntax
value = object.MinimumValue(timestamp)
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERange class. The timestamp is the time for which the minimum value should be
returned. The value is the Range's minimum value at the given timestamp.

117
Programmatic Interface

OSIDERanges Class

An OSIDERanges (OSIsoft Data Entry Ranges) object is a collection of OSIDERange

objects.

Count Property
Returns the number of ranges in the collection.

Syntax
object.Count
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERanges class.

Remarks
This property is read-only. The minimum value that can be returned is zero, and the
maximum value is the number of ranges for the ValueSet.

Add Method
Adds a new range to the collection, and returns a reference to the added range.

Syntax
object.Add(name, minimum, minimumName, minimumType, maximum,
maximumName, maximumType[, minimumForeColor, minimumBackColor,
maximumForeColor, maximumBackColor])
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERanges class. The name string is the name of the range. The minimum and maximum
arguments are either fixed values or names of PI Aliases, depending on the minimumType and
maximumType argument values respectively, as described in Settings below. The
minimumForeColor, minimumBackColor, maximumForeColor and maximumBackColor
arguments are all long integer expressions representing the colors to be used.

Settings
The settings for minimumType and maximumType are:
Constant Description
0 Alias. The type is expected to be the name of an alias.
1 Fixed. The type is expected to be a fixed value.

Remarks
If an optional key is not provided, the range can only be retrieved from the collection through
its index, or by iterating through all collection members.
You can use the members of the PIDELimitTypes enumeration set for the minimumType and
maximumType arguments.

118
 Enumeration Sets

Item Method
Returns a reference to a single range in the collection.

Syntax
object.Item(index)
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERanges class. The index value identifies the range that should be retrieved from the
collection.

Remarks
The index value may be an integer index or a string key (if one was provided when the range
was added to the collection).

Remove Method
Removes the indicated specification range from the collection.

Syntax
object.Remove(index)
The object placeholder represents an object expression that evaluates to an instance of the
OSIDERanges class. The index value identifies the range that should be removed from the
collection.

Remarks
The index value may be an integer index or a string key (if one was provided when the range
was added to the collection).

Enumeration Sets
An enumeration set is a named set of long integer constant values, where each integer in the
set has a unique symbolic name. The members of the set usually have an implied relationship
(typically implied by the name of the set), and are often used to scope the possible values of a
property. For example, the Alignment property for a simple Label control in Visual Basic 6 is
of the long integer data type, but only three values apply, and each has a specific meaning: 0
means left justify, 1 means right justify, and 2 means center. The AlignmentConstants
enumeration set is provided by Visual Basic to identify the allowable values for the
Alignment property of the Label control, and to allow them to be represented in code as
symbolic constants (for example, vbLeftJustify, vbRightJustify, and vbCenter respectively)
that have more obvious meaning than their corresponding literal integer values.
The OSIsoft DataSheet Control provides several enumeration sets that may be used to make
code written against its programmatic interface more readable.

119
Programmatic Interface

PIDEDataInclusions

The members of the PIDEDataInclusions enumeration set can be used to assign values to and
compare values with the control's DataInclusion property.

Members
Constant Value Description
IncludeAll 0 Display all PI Unit Batches within the time range.
IncludeFirst 1 Display the first specified number of PI Unit
Batches within the time range.
IncludeLast 2 Display the last specified number of PI Unit
Batches within the time range.

PIDEEnterNavigationTypes

The members of the PIDEEnterNavigationTypes enumeration set can be used to assign

values to and compare values with the control's EnterNavigation property.

Members
Constant Value Description
EnterNavigateRight 0 Advance focus first from left to right, then from top
to bottom.
EnterNavigateDown 1 Advance focus first from top to bottom, then from
left to right.
EnterNavigateNone 2 Pressing the enter key does not advance focus.

PIDELimitTypes

The members of the PIDELimitTypes enumeration set can be used to assign values to and
compare values with the MinimumLimitType and MaximumLimitType properties of the
OSIDERange class.

Members
Constant Value Description
LimitAlias 0 Limit is expected to be the name of an alias.
LimitFixed 1 Limit is expected to be a fixed value.

PIDELogLevel

The members of the PIDELogLevel enumeration set can be used to assign values to and
compare values with the control's LogLevel property.

120
 Enumeration Sets

Members
Constant Value Description
LogNone 0 No logging.
LogErrors 1 Only log error information.
LogAll 2 Log all information.

OSIDERangeEnforcements

The members of the OSIDERangeEnforcements enumeration set can be used to assign values
to and compare values with the control's RangeEnforcement property.

Members
Constant Value Description
EnforceNone 0 Do not enforce range limits on entered data.
EnforcePrompt 1 Prompt the user to confirm data entered outside range limits.

PIDEScrollBars

The members of the PIDEScrollBars enumeration set can be used to assign values to and
compare values with the control's ScrollBars property.

Members
Constant Value Description
ScrollNone 0 None. No scroll bars will be displayed.
ScrollHorizontal 1 Horizontal. A horizontal scroll bar will be displayed.
ScrollVertical 2 Vertical. A vertical scroll bar will be displayed.
ScrollBoth 3 Both. Both vertical and horizontal scroll bars will be displayed.

OSIDEValueSetType

The members of the OSIDEValueSetType enumeration set can be used to assign values to
and compare values with the RowType property of the OSIDEValueSet class.

Members
Constant Value Description
TypeReadWrite 0 Displays archive data and supports data entry.
TypeReadOnly 1 Displays read-only data.

121
Programmatic Interface

Constant Value Description

TypeBlank 2 No data is displayed (empty).
TypeBatchID 3 Display the batch ID for each PI Unit Batch.
TypeBatchState 4 Display the state for each PI Unit Batch.
TypeProduct 5 Display the product code for each PI Unit Batch.
TypeStartTime 6 Display the start of the applicable time range.
TypeEndTime 7 Display the end of the applicable time range.

OSIDEWriteModes

The members of the OSIDEWriteModes enumeration set can be used to assign values to and
compare values with the WriteMode property of the OSIDataEntryControls.OSIDataSheet
control.

Members
Constant Value Description
WriteModeInsert 0 Will always insert a new value even if one with the same
timestamp already exists.
WriteModeReplace 1 If a value already exists at the same timestamp, it will be
overwritten with the new value.

OSIDEWriteTime

The members of the OSIDEWriteTime enumeration set can be used to assign values to and
compare values with the WriteTime property of the OSIDataEntryControls.OSIDataSheet
control.

Members
Constant Value Description
WriteTimeNone 0 Write time is unspecified.
WriteTimeBatchStart 1 The value will be written at the start time of the batch.
WriteTimeBatchEnd 2 The value will be written at the end time of the batch
WriteTimeOther 3 A different time has been identified.

122
Chapter 8

Glossary

ActiveX
ActiveX is a set of object-oriented programming tools and technologies from Microsoft,
including COM and DCOM. The chief concept of the set is the idea of a component, called
an ActiveX control, which is a self-sufficient program that can be run anywhere in your
ActiveX network.

ANSI
American National Standards Institute. ANSI is a non-profit, private industry association
which governs most standards-setting agencies in the United States of America.

Batch Database
The PI Batch Database relates batch identifiers to the time series data collected for a batch.

COM
COM is an acronym Component Object Model, Microsoft's framework for developing and
supporting the component objects that make up a software solution. COM includes COM+,
the Distributed Component Object Model (DCOM), and ActiveX interfaces and
programming tools.

Component Object Model

See COM.

123
Glossary

IsPIUnit Property
The IsPIUnit property of the PIModule object is a Boolean value that indicates (when True)
that PIUnitBatch objects may be created that are specific to that PIModule. See the PI-SDK
Help for more information.

MDB
MDB is an acronym for the PI Module Database. See Module Database.

Module
As it refers to the PI Module Database, a Module is a standardized, often interchangeable
component of a system or construction that is designed for easy assembly or flexible use.

Module Database
The PI Module Database is actually a set of high-level server databases exposed through the
PI-SDK object model.

PI Batch Database
See Batch Database.

PI Module Database
See Module Database.

PI Unit Module
See Unit Module.

Property Pages
Property Pages enable a control to display its properties in a tabbed dialog, where tabs are
used to group the control's properties into meaningful sets. Property Pages often simplify the
configuration of an instance of a control, by providing graphical means to perform

124
 System Colors

configuration, and using user-interface constructs that are not typically available in standard
Properties windows.

System Colors
A set of colors provided by the Microsoft Windows family of operating systems, which may
be customized by each individual user, and are used when displaying any window.

Unit Module
In this document, the terms "PI Unit Module" and "Unit Module" are used to refer to a PI
Module that is a unit; that is, a PI Module for which the "IsPIUnit" property is True.

125
Index
HeaderFont • 28, 73, 76, 77
A HeaderForeColor • 29, 74, 76, 78
Auto Config • 20
I
AutoCommit • 41, 45, 60, 61, 81, 95, 101, 103
AutoScroll • 35, 61 Interval • 24, 35, 78
AutoWidth • 90
M
B Message Logging • 13
BackColor • 29, 40, 62, 73, 77 Module Database • 5, 7, 8, 20, 128
BaseColor • 29, 62
Batch ID • 20 N
Batch State • 20 NavigationOrder • 74, 123
BeforeCommit • 101, 103, 106 NewUnitBatches • 79
BorderStyle • 63
P
C
PI Unit Module • 5, 7, 8, 20, 86, 87, 114, 115, 128,
CellsPerDataRow • 64 129
ChangesPending • 64 PI-SDK • 11, 128
ColumnWidth • 64, 65 ProcessBook • 5, 11, 15, 35
COM Connector • 5, 6 PromptChangesPending • 36
Commit • 24, 45, 49, 61, 81, 95, 101, 103 PromptComment • 50, 81
CommitAll • 81, 95
CurrentDataRow • 59, 60, 65, 66, 67, 68, 69, 75, 87, R
112
CurrentUnitBatch • 67, 68, 112 RangeEnforcement • 6, 81, 124
Refresh • 78, 97, 98, 100
D Revert • 49, 98
RevertAll • 99
Data Source • 22, 38 RowHeight • 83
DataRow • 5, 6, 7, 9, 39, 40, 46, 66, 67, 68, 76, 81,
87, 113, 114, 115, 116, 117, 118, 119, 120, 121 S
DataRows • 5, 7, 8, 33, 35, 36, 88, 89, 113, 115
ScrollBars • 84, 124
E ShowGridlines • 85
ShowPopupMenu • 33, 49, 85
Enabled • 71 StartTime • 64, 68, 86
EndTime • 64, 68, 72
EnteredBackColor • 29, 40, 62, 73 V
EnteredFont • 28, 40, 45, 73
EnteredForeColor • 29, 40, 45, 74 Value Alias • 20, 46

F
ForeColor • 29, 40, 74, 76, 78

H
HeaderBackColor • 29, 62, 73, 77

127