Professional Documents
Culture Documents
Version 3.1
Sales Outlets/Distributors
Middle East/North Africa South America/Caribbean
Republic of South Africa Southeast Asia
Russia/Central Asia South Korea Taiwan
www.osisoft.com
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System,
PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned
in this book that are known to be trademarks or service marks have been appropriately
capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the
property of its owner and use herein in no way indicates an endorsement, recommendation, or
warranty of such party's products or any affiliation with such party of any kind.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in
subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at
DFARS 252.227-7013
Published: 9/25/2008
Table of Contents
Introduction.....................................................................................................................................1
What Can You View with PI ProcessBook? .......................................................................1
System Requirements ........................................................................................................4
Installation ..........................................................................................................................4
Trends............................................................................................................................................77
Create a Trend .................................................................................................................77
Define Trend Dialog .........................................................................................................80
Configure Trend Scale .....................................................................................................84
Trend Analysis Tools........................................................................................................85
Change Time Range ........................................................................................................88
How Trends Refresh ........................................................................................................88
Trend Appearance............................................................................................................88
Ad Hoc Trends .................................................................................................................94
OpenVMS Trends and Graphics ......................................................................................95
XYPlots ..........................................................................................................................................97
Draw an XYPlot ................................................................................................................99
Linear Regression by Least Squares .............................................................................109
Correlation Coefficient....................................................................................................109
Interpreting an XYPlot ....................................................................................................110
Zoom/Revert Functions ..................................................................................................110
Change Time Range Feature.........................................................................................112
XYPlot Cursors...............................................................................................................112
Bad Status Indicators .....................................................................................................113
Out of Range Indicators .................................................................................................114
Too Many Points ............................................................................................................114
Examples of XYPlots......................................................................................................114
iv
Item Definition ................................................................................................................151
Status Report for Dynamic Symbols ..............................................................................152
Status Flags for Unusual Data .......................................................................................153
Data Sets .....................................................................................................................................155
PI Calculation Data Sets ................................................................................................156
Custom Data Sets ..........................................................................................................159
ODBC Data Sets ............................................................................................................160
Placeholders...................................................................................................................162
Is a Data Set in Use? .....................................................................................................164
Data Set Details .............................................................................................................164
Add a Data Set to a Trend .............................................................................................165
Time Intervals for Plotting Tags and Data Sets .............................................................166
Refresh a Trend Containing a Data Set .........................................................................166
Add Data Sets to Bars or Values in a Display................................................................166
Run PI ProcessBook When Data Sets Are Included .....................................................167
Edit a Data Set ...............................................................................................................167
Delete a Data Set ...........................................................................................................168
Copy a Data Set to Another ProcessBook .....................................................................168
Loading Custom Data Sets ............................................................................................169
Embedding and Linking.............................................................................................................171
Overview of PI ProcessBook OLE Compound Documents ...........................................171
OLE Automation in PI ProcessBook ..............................................................................171
Object Linking and Embedding ......................................................................................172
ActiveX Controls.............................................................................................................173
Example of Embedded and Linked Objects in a ProcessBook Display.........................174
Icons vs. Graphics..........................................................................................................174
Embedding in ProcessBook ...........................................................................................175
Windows Drag and Drop ................................................................................................176
Link a File to a ProcessBook Display.............................................................................176
Dynamic and Manual Updates of a Linked Object.........................................................177
Edit, Update, or Break Links ..........................................................................................177
How Links Are Stored.....................................................................................................177
Select a New Source Link ..............................................................................................178
Edit the Appearance of an OLE Object ..........................................................................178
Commands That Ignore OLE objects.............................................................................178
Placement of OLE objects..............................................................................................178
OLE Object Colors .........................................................................................................179
Edit the Contents of OLE objects ...................................................................................179
Edit the Contents of an Embedded Object.....................................................................179
Edit the Contents of a Linked Object..............................................................................179
Delete an OLE Object from a Display ............................................................................180
Display an OLE Object with an Icon...............................................................................180
Convert Objects to Icons................................................................................................180
Share ProcessBook Displays with Other Applications...................................................181
Link a ProcessBook to Another Application ...................................................................182
OLE Container/Server ....................................................................................................182
ODBC ...........................................................................................................................................185
ODBC Driver Manager ...................................................................................................185
ODBC Drivers.................................................................................................................185
ODBC Data Sources ......................................................................................................185
ODBC Data Access........................................................................................................185
ODBC Data Source Administrator..................................................................................186
Prepare for ODBC ..........................................................................................................187
Configure the ODBC Data Source .................................................................................187
Use MSQuery to Build Data Sets...................................................................................188
Assumptions about Timestamps and Data Sets ............................................................188
Stored Procedures in Queries........................................................................................188
Troubleshoot ODBC Data Sets ......................................................................................189
Trace ODBC Calls..........................................................................................................189
Delete an ODBC Driver ..................................................................................................190
Delete an ODBC Data Source .......................................................................................190
Edit an ODBC Data Source............................................................................................190
Index ............................................................................................................................................215
vi
Chapter 1
Introduction
PI ProcessBook is a PC application for displaying plant information stored in the PI Data
Archive (page 2) or in relational databases.
The PI ProcessBook application displays one or more ProcessBooks (page 8), which are
collections of display (page 8) entries. These display entries show your process data from one
or more PI Systems as well as other static and dynamic information from outside sources
such as schematic drawings, laboratory data, or specifications. Displays can also be saved as
independent files.
ProcessBook displays may be linked to other displays within the same ProcessBook or to
displays in a separate ProcessBook or independent file. You can also include buttons that
launch other applications.
You can share ProcessBooks among users, thereby eliminating the need to build duplicate
displays, however, only one user at a time can open individual display files. On networks, an
unlimited number of users may access the same ProcessBook at the same time. Furthermore,
you can have up to six simultaneous sessions of the application active on a computer.
The PI ProcessBook application incorporates Microsoft Visual Basic for Applications (VBA),
so that you can automate special activities or routine chores.
OSIsoft produces several add-in products for PI ProcessBook, including PI BatchView and PI
Statistical Quality Control (SQC).
ProcessBook displays may be linked to other displays within the same ProcessBook, or to
displays in a separate ProcessBook. You can also include buttons that launch other
applications.
Most displays include a number of tags from one or more PI Systems. The connection to a PI
Server allows you to view process data at the current time or at other, discrete points in time.
Displays update dynamically whenever values on the PI Server change.
PI Data Archive
The PI Archive is a time-series database that collects, stores, and retrieves numerical and
string data. The PI Archive resides on a host computer and is connected to your PC via the PI
Server and your network.
When you open a display (page 8) containing dynamic symbols, PI ProcessBook retrieves
data from the PI Archive.
PI ProcessBook also notifies the PI Server that it would like to receive data whenever the
readings for the dynamic symbols change. Each time a reading changes for points in the
display, the information is recorded in the PI Server. This new information is sent to your
displays and all the new values are added to trend traces. This is true even if you reduce the
display to an icon (page 58).
If you open a display but are not connected to a PI Server, PI ProcessBook automatically tries
to connect to the servers in the display. If multiple servers are accessed, the application tries
to connect to each disconnected server used in the display and the message Attempting
to Connect displays on the Status Bar. If security is enabled on the server, you may be
prompted to log in to the server.
Updates to PI Data
When a display is opened, current values of PI tags are used for dynamic elements other than
trends and XY plots. For trends and XY plots, the time scale is configurable on a plot-by-plot
basis. See Changing the Time Range (page 14) for information on viewing historical values.
Displays are updated whenever values change. Every five seconds, PI ProcessBook displays
any new values for tags in open displays from each PI Server. You can modify the update
rate. See Procbook.ini (page 196) for more details.
For trends, new values are added to the trend traces. This update by exception algorithm has
two benefits:
Values that do not change are not sent over the network at every update. This can be a
significant efficiency improvement over traditional scanning.
Values that change more than once within five seconds are shown accurately on trends
because all of the changes are delivered to PI ProcessBook.
Values from PI calculations and custom data sets are also updated dynamically.
2
What Can You View with PI ProcessBook?
PI ProcessBook Datasets
PI ProcessBook can plot data from relational databases through Open Database Connectivity
(ODBC), which means that you can retrieve and display dynamic data from other ODBC-
compliant databases based on fixed or variable criteria.
You can also view data from data sets based on PI Performance Equations or standard
functions, such as minimum or maximum value. These are called PI Calculation data sets.
If you have custom data sets, these may be available to PI ProcessBook using a VBA add-in
and will update dynamically.
PI ProcessBook OLE
PI ProcessBook provides the capability to use OLE linking and embedding (page 172). You
can embed or link OLE objects from other Windows applications into a ProcessBook display.
The data might be derived from a wide variety of OLE-compliant applications, such as
spreadsheets, documents, graphics objects, etc.
PI ProcessBook is an OLE Automation server. Programmers can write scripts that manipulate
and retrieve PI data.
OSIsoft licenses Visual Basic for Applications (VBA) from Microsoft in order to provide an
integrated development environment. This is the same VBA that is used in Microsoft Office,
Visio, AutoCAD, Great Plains Dynamics, and many other applications.
In PI ProcessBook, each display has a VBA project associated with it. You can write scripts
that execute in response to events in PI ProcessBook, either from user actions or data updates.
Also use VBA to automate routine tasks or to cause changes in a display when data changes.
The Visual Basic toolbar includes three buttons: Visual Basic Editor, Run Macro, and
Design Mode.
Use of VBA in PI ProcessBook is documented in the VBA language reference. Choose Help
> PI ProcessBook VBA Language Reference to open this reference guide.
You can find existing custom VBA scripts available for free download at the OSIsoft
Developer Network (http://osidn.osisoft.com/) Web site. Many of the files available there
were contributed by PI System users, but are not fully supported by OSIsoft, Inc.
You can connect to more than one PI Server, and build displays to show data from multiple
servers at the same time.
System Requirements
You can use PI ProcessBook with Windows 2000, XP, Vista, 2003 Server, 2000 Server, and
on Intel platforms. The 3.1 release of PI ProcessBook is shipped in a 32-bit version.
As more advanced PI ProcessBook features are added, your system may require more
memory.
Installation
If you have a previous version of PI ProcessBook installed on your computer, you should
upgrade that version, rather than uninstall it. During the installation of PI ProcessBook 3.1,
your previous version of PI ProcessBookis removed; however, .ini files settings are
retained.
If you have created or edited displays and ProcessBooks with other versions of PI
ProcessBook, those files will work with PI ProcessBook 3.1.
If you have other client products, such as PI DataLink, PI ODBC-PC, PI SDK, or PI API, the
same root path is used for installation, often C:\Program Files\PIPC. Otherwise,
incompatibilities in the .dll files shared by the applications could occur.
If you have PI BatchView or PI SQC installed on your system, Setup installs a PI
ProcessBook Batch group and/or PI ProcessBook SQC symbol that is compatible with the
current version of PI ProcessBook. You can also install PI BatchView 3.x after installing PI
ProcessBook 3.x, and the correct Batch Trend symbol is loaded.
If you install PI SQC 1.1 before installing PI ProcessBook 3.x, you have to rerun the PI SQC
1.1 setup program after installing PI ProcessBook 3.x.
4
Installation
Installation Test
You can view the results of the installation process by examining the setup log:
PIPC\DAT\SetupProcessBook.log
This log also contains information pertaining to the directory structure, node, .dlls, user
name, and installation of various PI ProcessBook files. If the log file is not found in the
\PIPC\Dat folder, look in the root directory of your system drive (e.g., C:\).
Once you install PI ProcessBook, you can see the words PI System on the Windows
Start menu under Programs. At this point, you are ready to use PI ProcessBook.
Call OSI Technical Support (page 211) if you experience problems with your software.
Installed Files
Upon completion, Setup installs PI ProcessBook under the root directory PIPC.
Setup also installs online help files and Release Notes.
See the Release Notes (readme.htm) for a complete list of files. The Release Notes are
normally installed at:
C:\Program Files\PIPC\procbook\readme.htm
You can look at SetupProcessBook.log in the Dat directory of your PI ProcessBook
installation to see a list of files installed by PI ProcessBook's Setup on your computer.
SetupProcessBook.log does not show the files installed by VBA.
PI ProcessBook Essentials
Process data is stored in the PI Server Archive, part of the foundation of the PI System. The
Archive handles the collection, storage, and retrieval of numerical and string data.
PI ProcessBook provides access to these data. When you log in to PI ProcessBook, you
obtain values from the Archive via the PI Server or servers to which you are connected.
Starting PI ProcessBook
To use PI ProcessBook you need to start the application, log in to the PI Server, open a
specific ProcessBook file, and open a display.
1. Either double-click on the PI ProcessBook icon on the desktop, or select the Start button
> Programs > PI System > PI ProcessBook. If security is not configured at your site,
you automatically log into PI ProcessBook. If security is configured, the PI Server
Login dialog appears.
2. Enter your PI user name or host user name and password (if prompted).
3. If the PI Server to which you want to connect is not shown, enter the desired PI Server
name (sometimes called the node).
4. Click OK to begin the login process. This may take a few seconds while the application
connects to the specified server. The status bar displays the message, Attempting to
Connect. When the application connects to the server, the status bar displays the
message, Connection Was Successful.
Note: If you click Cancel, PI ProcessBook starts, but is not connected to the server.
Whenever you open a display containing tags from a PI Server, the application
attempts to connect again and you may see the login dialog.
Workspace
When you start PI ProcessBook, it appears as an open window or workspace on the desktop.
Depending on your settings, you may initially see an empty workspace, or an open
ProcessBook (page 8) in either Book or Outline view.
Within the PI ProcessBook workspace you can open a ProcessBook or independent display.
ProcessBook (PIW)
In PI ProcessBook we refer to a ProcessBook as the container for the information and
analysis of the process you are monitoring. A ProcessBook may appear as either a tabbed
book - Book view (page 41), or an outline - Outline view (page 44), and is saved as a separate
file with a PIW extension.
A ProcessBook is a collection of individual displays of data and analysis. Use a ProcessBook
to organize data from the PI System and other sources so that you can analyze the processes
you monitor or the tasks you perform.
A ProcessBook and its displays are stored in a single file.
Display
The main unit for creating presentations of data in PI ProcessBook is the display. A display
may stand on its own (.pdi or.svg), or it may be part of a ProcessBook (.piw). A display
contains all the symbols used to represent an operational environment using real-time,
production data from PI as well as data from other sources. In addition to containing this
collection of data elements, the display has its own set of features and properties that affect
the collection of data elements.
Displays can show a variety of elements, such as a schematic representation of a production
line, a plot of readings taken from a production line, or a comparison of lab data and batch
specifications. Displays can also be linked to other ProcessBooks, displays in other
ProcessBooks, or other applications.
Run mode is used to open entries and execute commands once the ProcessBook is
built. Working in Run mode also keeps you from accidentally changing items in a
display.
You switch between modes by clicking the Run mode pointer (an arrow) or the Build mode
pointer (a hammer), which are located on the Tools menu and the Drawing toolbar. Your
preferred mode of operation is set as a default in your Preference settings.
8
Servers and Connections
Connect to a Server
1. Choose File > Connections. The PI Connection Manager dialog appears. The dialog
lists the configured servers to which you can connect and the PI Version used by each
server. It also shows the server you have chosen as the default server.
2. Select the check box next to a server name. You may select more than one, or
Choose Server > Connect to <server name>.
3. Click Close.
Note: If you select more than one server, the application tries to connect to each
server using the same user ID and password. If it fails, a new PI Server Login
dialog appears. If you already are logged in to the server from a different PI
application, such as DataLink or Control Monitor, the application uses the user
ID and password with which you logged in. See the PI-SDK Controls and
Dialogs User Help for more detail.
Note: You automatically disconnect from all servers when you exit PI ProcessBook
unless you have other PI client software running.
Network Errors
Network Errors update the Status Report dialog, rather than displaying error messages on
your monitor. When a display is opened but the server is not found, only one Select New
Node dialog appears. The dialog appears once for each server that is not in the Known
Servers table.
If the connection to your data is not successful, the display is still drawn, but data in dynamic
elements are replaced with indicators signifying that no data is available.
Trends are labeled Invalid and no information is plotted.
Values are replaced with pound signs (###) and the message Disconnected appears.
Bar graphs are drawn using hash marks (//////).
Note: See the PI-SDK Controls and Dialogs User Help for more detail.
A Node Identifier is stored with each tag name used in a display to point to the correct server.
If you define PI Server nodes in the PI Connection Manager dialog, the identifiers will be
the same on each PC on the network as long as the node names for the PI System are the
same.
Time Concepts
PI Time
PI Time abbreviations and PI time expressions allow you to specify times and time ranges for
PI data using constants, variables, and short expressions.
PI Time Abbreviations
An interval is a unit of time that can be used in time entries. Intervals that support fractional
values are listed below. For intervals where the Fractions column indicates No, fractional
amounts cannot be used in time strings.
Name Short name Plural name Member names Fractions
second s seconds no yes
minute m minutes no yes
hour h hours no yes
day d days no no
month mo months yes (for example, no
December)
year y years no no
week w weeks no no
10
Time Concepts
You can spell out month and weekday names, or enter the first three letters (for example,
Dec, Tue).
PI Times can also be expressed using certain constants:
Constant Result
* The current time.
Today or t 12:00 am of the current day.
Yesterday or y 12:00 am of the previous day.
Sunday or sun 00:00:00 (midnight) on the most recent past Sunday (in
reference to the PI Server).
PI Time Expressions
PI allows three types of time expressions: relative time, combined time, and absolute time.
These time expression types are defined in the following table.
Expression Description Examples
Relative Time Relative time expressions specify a number of days, +1d
hours, minutes, or seconds with either a leading plus -24h
sign or a leading minus sign. -3m
The reference time, or starting time, for the relative time +24s
expression is the current time if both start and end times
are relative.
Combined A combined time expression is a specific reference time *+8h
Time followed by a relative time expression. 18-dec-02 -
3m
t+32s
Absolute Time An absolute time expression is any time expression that *
is neither a relative nor a combined time expression. 14-Dec-97
11-Nov-96
2:00:00.0001
t
y
The Time Range toolbar is used for working with dynamic symbols. In general, the
commands on this toolbar affect only the symbols selected on the display. If no symbols are
12
Time Concepts
selected, all symbols are affected. This toolbar, which must be used in Run mode, contains
three buttons:
Revert (page 13)—returns the trend or other dynamic symbol to its original setting.
Change Time Range (page 14)—opens a dialog to set new, temporary start and end
times. For Bars, Values, and Multi-State symbols, there is no start time, only an end time.
Scroll Bar (page 15)—scrolls through time values.
To discard any of the changes you have made to the time range of a trend or the effective
time of a Bar, Value, or Multi-State symbol and return it to its original or saved setting:
In Run mode, choose View > Revert, or
Click the Revert button.
New Dialog
In order to create a new ProcessBook, an entry within the ProcessBook that is currently open,
or an independent display, choose File > New to launch the New dialog.
New ProcessBook
When you create and save a new ProcessBook, the application initially gives it the title
Untitledn where n represents the number of ProcessBooks created during the current
session.
You may specify a better title, including up to 43 characters and spaces, such as
Filtration Plant Number 5. This title is displayed in the title bar of the window
listing the contents of your ProcessBook.
PI ProcessBook also creates a file name for the new ProcessBook. It suggests the first word
or first eight characters from your title and an extension of .piw. For example, PI
ProcessBook may suggest Filtrati.piw. If you plan to build a whole set of
ProcessBooks, you might choose to modify the title to something that sorts your set of
ProcessBooks within the Windows Explorer in some meaningful order, such as
05FiltrP.piw. Using Windows Explorer, you may also change the file name after the file
is closed.
The Time Range command lets you enter new starting and ending times for dynamic
symbols. When you specify a time range for a single-time dynamic element, such as a Multi-
State symbol, bar or value, only the end time is used.
Note: The time represented on your display is the time relative to the PI Server, unless
you have selected the client time zone setting for your display. If the PI Server to
which you are connected is in a different time zone, time on your display
represents the distant time zone, not the local one.
1. In Run mode, select the dynamic symbol or symbols for which you want to change the
time range. If no symbols are selected, the time range change affects all dynamic symbols
on the display.
2. Click the Time Range button on the Time Range toolbar, or
14
Time Concepts
3. Select new starting and ending times from the drop-down lists or define your own starting
and ending times. Time ranges can be relative, absolute, or combined.
4. Click OK. The selected elements change to reflect the new time range.
1. In Run mode, select the dynamic symbol or symbols for which you want to change the
time range. If no symbols are selected, the time range change affects all dynamic symbols
in the display.
2. On the Time Range toolbar, click the forward or backward Scroll Time button, or
Click and drag the Scroll Time slider, or
Click the space on either side of the Scroll Time slider to increment or decrement by a
time span.
If the slider is dragged, a ToolTip is updated with the end time that is applied when you
release the mouse button.
3. Release the mouse button. Selected symbols are refreshed with the new time range.
Note: You can scroll the time for all items in a display or selected items. If no trend is
included in the selected items, the scroll buttons are disabled.
Use the time backward and forward buttons to scroll the time range forward or backward. To
do this:
1. Click on the desired symbols with the Run Mode pointer.
2. Click the Time Forward or Time Backward button.
Trends scroll by the time range specified in the trend definition. When you select multiple
trends, each trend maintains its time range as it is scrolled. If you select a trend and a
dynamic element such as a value, the non-trend symbol scrolls by the time range specified in
the trend definition.
For example, if the trend displays data from 1:00 to 4:00 (three hours) and the value has a
timestamp of 5:00, scrolling backward shows trend data from 10:00 to 1:00. The value's
timestamp also changes by three hours (2:00).
Future Trends
It is possible to set trends with an end date in the future by choosing an end time of the
present (*) plus an amount of time, such as 4 hours or 8 days. These trends update if they are
less than the update time limit. The default update time limit is 24 hours, but that duration
limit can be changed.
You can set the time range for a trend into the future by using * + an amount of time no more
than 7 days greater than the start time. A trend can also be scrolled into the future using the
time range buttons, but then it does not update.
Command Menus
The active components of menu bars change depending on the active window and current
selections. There are now five different collections of menu commands.
Toolbars
16
Menus and Toolbars
Customize Toolbars
Toolbars may be displayed or omitted as follows:
1. Choose View > Toolbars. The Toolbars tab of the Customize dialog opens.
2. Check the toolbars you wish to display, and click OK.
3. To move a toolbar, click on the double vertical bar at the left end and drag to the new
location. If the toolbar has no move handle, click on the title bar instead.
4. To reshape a floating toolbar (one without move handles), grab one of its edges and drag
to a new shape.
Toolbar Buttons
Preference Settings
You can reach the ProcessBook Preferences dialog by choosing Tools > Preferences.
Preference settings determine how the ProcessBook entries look, what colors are available
when you draw, and whether your ProcessBook opens in Book View or Outline View.
Note: Preference settings are stored in the file procbook.ini. Before you change the
Preference settings, consider creating a back-up copy of procbook.ini so that
you can restore PI ProcessBook to the original settings.
General Preferences
Choose Tools > Preferences > General tab to configure application-wide settings. These
settings are stored in and retrieved from the [STARTUP] section of your procbook.ini
(page 196) file.
Author—Determines the name used as the creator of new files and the person who lasted
edited the file. See Summary Information in Processbook (page 47) for more information.
This field is blank by default when PI ProcessBook is first installed on a computer.
Startup File—The file name and path in this field determine which, if any, file is open when
the application is launched. The default value when PI ProcessBook is first installed is
<installation path>\procbook\pidemo.piw.
Library File—The file name and path in this field determine which, if any, file is opened
when the original symbol library command is used. The default value when PI ProcessBook
is first installed is <installation path>\procbook\symlibry.piw.
Prefer Run Mode—Determines whether ProcessBook starts up in Run mode or Build mode
by default. By default, this option is enabled when PI ProcessBook is first installed on a
computer.
18
Preference Settings
Create Backup Files—Determines whether backup files (with a .bak extension) are
automatically created when a PI ProcessBook file is opened. By default, this option is turned
off when PI ProcessBook is first installed on a computer.
Retain snapshot values on updating plots—Determines whether the archive event pipe is
used for updating trends, discarding any snapshot values between stored, archive values. This
setting is stored as PB2TraceCompatibility in the [STARTUP] section of your
procbook.ini. By default, this option is turned on when PI ProcessBook is first installed
on a computer. Leaving this option selected results in a more jagged trace that gets smoothed
when the display is reopened or the trend is reverted.
Date and Time Format—Settings in this area determine how time is displayed in PI
ProcessBook. Previews of each format are shown to help you select the desired option.
The Use local Windows format option uses the current Regional Options settings in the
Windows Control Panel on the client machine to determine how dates and times are
displayed. Dates are shown using the currently configured Short Date format and Times
are shown using the current time format settings.
The Use PI Time Format option displays timestamps in the default PI format of dd-
mmm-yy HH:mm:ss.ssss, where dd is the day of the month, mmm is a the short text
abbreviation of the month name (e.g., Jan for January), yy is the two digit year, HH is the
hour in 24-hour format, mm is the minute and ss.sss is the second, including sub-
seconds, if present.
Default Time Zone—Determines whether timestamps reflect the time zone of the PI Server
used to retrieve data (PI Server time zone), or the time zone of the local computer (Client
machine time zone), when a new display is created. By default, the PI Server option is
selected when PI ProcessBook is first installed on a computer. This setting can also be
changed and is stored with each display.
Choose Tools > Preferences > Table of Contents tab to configure the default view of Table
of Contents windows for ProcessBook(PIW) files, as well as the font applied to each level of
entry in those files. These settings are stored in and retrieved from your procbook.ini
(page 196) file.
Default View—Settings in this area determine how ProcessBook entries are displayed by
default. The default is Book view.
Font Settings—The controls in this area determine the font settings applied to each entry
level in a ProcessBook. The font settings control the display of entry names in Table of
Contents windows.
The Entry level field allows you to select the level to configure. You can only select one
level at a time.
The Font field lists all the fonts installed on the computer running PI ProcesBook.
The Size field determines the size of the text. The first time ProcessBook is installed, the
current Windows system font determines the default font settings to use.
The Font style group determines whether text is shown in bold or italic.
Preview—This read-only field displays font settings for each level in a ProcessBook. Each of
the 10 possible entry levels is listed and displayed with its current font name, and style
settings.
20
Preference Settings
Display Window
Choose Tools > Preferences > Display Window tab to set options that apply to display
windows. These settings are stored in and retrieved from your procbook.ini (page 196)
file.
Color Palette—These fields present the 16 colors selected for use throughout the application
as the basic colors for the color well control.
Use the Modify button to launch the Color dialog, where you can select additional
colors.
Use the Reset button to return the Color Palette to system default values.
Default Display Background Color—Determines the default color used for new displays.
The color well control is used to select a color. This color is also set when the Background
color of the current display is changed.
Symbol Defaults—contains fields to set the default formatting values for new symbols.
These defaults are also changed when the Formatting controls are used and no symbols are
selected.
Trend Preferences
Choose Tools > Preferences > Trend tab to set default settings for trend symbol display
options.
22
Preference Settings
Multiple Scales—Add a value scale for each data point when selected. When the check
box is cleared, only a single value scale appears.
Markers—Select the Markers check box if you want markers to indicate data points on
the trend. If you do not select the Markers check box three markers display on each line.
These markers help you match a line to a tag.
Legend—Select or clear these options to configure what information appears in the trend
legends. The information that can fit in the legend is determined by the size of the trend.
Consequently, not all of the information in the legend may be visible:
If the width of the legend is more than the width of the trend the legend does not appear.
If the height of the text in the legend is longer than the total height of the trend, items are
removed in this order: engineering units, tag name, then value.
Options include:
Tag Name
Server Name
Value
Description
Eng Units
Sample—Use this display area to view a preview of selected trend preferences.
Choose Tools > Preferences > Trend Elements tab to set what colors, LineStyles, etc., are
used in individual traces.
Plot Elements—Use the drop down list to select from pens, text, grids, and backgrounds,
Multi-State on Ad Hoc—Select this check box to draw an ad hoc (instant) trend of a
Multi-State symbol. When this option is cleared, data from a multi-state configruation is
not included on instant trends.
Traces per Ad Hoc Trend—Select the number of traces to have per plot on an ad hoc
(instant) trend. The default is 3, the maximum is 8. Once this number is reached,
additional plots are created to show the remaining tags selected for the instant trend.
For each plot element, select a Marker Type, Line Style, Line Weight, and Color.
Note: You may select one of several line styles for each trace. You can also specify the
line thickness. Select none to omit a grid line.
Sample—See your changes previewed in the Sample area at the bottom of the dialog.
24
Add-Ins
Add-Ins
By default, PI ProcessBook installs with the following add-in components:
Details (page 135)—Enables a docking window that displays data from dynamic symbols
in a tabular format.
Module Context (page 72)—Gives you access to the Module Database, allowing you to
use aliases as a data source for dynamic symbols.
ProcessBook SVG File Converter—Enables you to save displays as SVG files, which can
then be used by RtWebParts.
ToolTip Statistics (page 68)—Allows you to see ToolTip statistics directly in dynamic
symbols.
Data Favorites (page 26)—Provides a way to configure symbols in ProcessBook by
dropping a PI tag name (or other data reference) from a list onto the symbol.
Other add-ins are installed with PI ProcessBook, however, don't become available until you
add additional applications:
PI Notifications (page 26)—Enables a docking window that contains the notification
viewer control.
Add-In Manager
The Add-In Manager lists the Add-Ins (page 25) available in your PI ProcessBook
installation. Use this dialog to control whether the add-ins are loaded whenever you use PI
ProcessBook.
1. Choose Tools > Add-in Manager. The Add-In Manager dialog appears.
Note: If the add-in is unloaded and then reloaded, you must click the Revert toolbar
PI Notifications in ProcessBook
The Data Favorites add-in is delivered with PI ProcessBook version 3.1 or higher. It provides
a way to configure symbols in PI ProcessBook by dropping a PI tag name (or other data
reference) from a list onto the symbol.
The add-in can be unloaded or set not to load at startup by changing the options in the Add-in
Manager dialog box. When the Data Favorites add-in is first loaded, its window appears in
the upper left corner of the PI ProcessBook application window. The window is only
accessible in Build mode. If the window is closed, it can be re-opened by selecting Data
Favorites from the View menu.
26
Add-Ins
Note: The Favorites list is saved per user, so when a different user opens PI
ProcessBook on the same machine, their list may be different.
Keyboard Shortcuts
A keyboard shortcut is a combination of keystrokes to use for frequent actions. Several of
these are already assigned in PI ProcessBook. They appear to the right of the corresponding
menu command on the drop-down menus.
PI ProcessBook lets you assign new combinations of keystrokes or change existing ones.
For example you can:
Assign a keyboard shortcut for inserting symbols without needing multiple mouse clicks.
Assign more than one keyboard shortcut to a specific action.
Change an existing shortcut, such as Ctrl+S, to another sequence you prefer.
28
Print
2. Under Select a macro, click the appropriate macro (menu item). The description for that
item and its assigned shortcuts, if any, appears.
3. Click the Create Shortcut button.
Note: If you choose a combination already in use, the current assignment appears
in the dialog. If you click OK, the previous assignment is voided.
5. Click OK.
The new shortcut appears in the Assigned shortcuts box.
Note: If you want to reset all the keyboard shortcuts to their original positions when
PI ProcessBook was installed, click the Reset All button, and then the OK
button.
1. In the Shortcut Keys dialog, under the Select a macro list, select the appropriate macro
(menu item). The description for that item and its assigned shortcuts, if any, appears.
2. Under Assigned shortcuts, select the shortcut you want to remove, and then click the
Remove button.
3. Click OK.
Print the entire contents of a display or selected items from that window.
You can also set various printing options, such as the number of copies.
Each topic in the help file may be printed separately or you can print them all at once.
The Print command is accessible from the File menu, CTRL+P, or the print button. You can
print the contents of the active window or if you select items within a display before you open
the Print dialog, then you can choose to print only those items.
Note: On a non-color printer, symbols are printed in shades of gray, but trends revert to
black and white.
On some printers, when you print a trend with cursors, the value and time stamp
boxes of the cursor does not hide the information beneath them. However, other
trend cursors and the trend time scale may show through the trend cursor boxes,
making the values hard to read.
You can select the particular printer, the orientation of the paper, the paper size, and the
source within the printer of the paper. Use the Properties button to fine-tune the quality of
output or the performance of the printer.
The settings you choose in Page Setup become the defaults for all your printing.
Note: PI ProcessBook supports dot matrix, HP PCL (LaserJet), Postscript, and color
printers. However, all Windows print drivers may not be compatible. If you are not
sure if your printer is supported or you observe any printing problems, contact
OSIsoft Technical Support (http://techsupport.osisoft.com).
Print Preview displays your selection as it will look when it is printed. Note that the Print
Preview shows colors even though you may be using a black and white printer.
Once you select the item you want to preview, choose File > Print Preview. Zoom in or out
of the selection by clicking on the selection with the magnifier cursor or by clicking the
Zoom buttons. To print the selection, click the Print button.
Printer Setup
Select Print Setup to choose a printer, page orientation, and paper size. In addition, you can
fine-tune the quality of output or the performance of your printer. The settings you choose in
Print Setup become the defaults for all your printing.
1. Choose File > Page Setup. The Print Setup dialog appears.
30
About PI ProcessBook
Note: PI ProcessBook supports dot matrix, HP PCL (LaserJet), Postscript, and color
printers. However, all Windows print drivers may not be compatible. If you are
not sure if your printer is supported or you observe any printing problems,
contact OSIsoft Technical Support.
3. Click the Properties button to select printer-specific options. Refer to your printer
documentation for additional information about these options.
About PI ProcessBook
You can launch the About PI ProcessBook dialog by clicking Help > About PI
ProcessBook.
The dialog provides version and build information, as well as a link to the OSIsoft tech
support site.
Click Copy Info to copy the contents of the grid control to your Windows clipboard where it
can be pasted into a spreadsheet or text editor.
Click System Info to launch the Microsoft System Information dialog.
32
Chapter 3
Note: In some installations, the System Administrator may set your PI ProcessBook to
View Only (page 205) mode. If so, you cannot create and save new
ProcessBooks.
Note: If you typed a name in ProcessBook Name box, then the name appears on the
ProcessBook title bar. If you did not type a name, then Book1 appears on the title
bar.
PI ProcessBook keeps track of the four most recently opened ProcessBooks or independent
display files. Instead of using File > Open, you may select a file name from the bottom of the
File menu.
You can place this button on a toolbar and use it to open another ProcessBook of your choice.
1. Choose View > Toolbars.
2. Select the Commands tab.
3. Under Categories, select Supplemental toolbar.
4. Drag the icon shown above to one of your toolbars.
5. Choose Tools > Preferences. The ProcessBook Preferences dialog opens.
6. Click the General (page 18) tab.
7. In the Library File box enter the location of a ProcessBook and click OK. This links the
button to that ProcessBook.
Note: By default, this button links to Symlibry.piw, which opens the original Symbol
Library (page 131) book.
34
Run Mode Pointer
You can work in multiple ProcessBooks and/or independent display files at the same time.
Open additional ProcessBooks using the File menu.
Use the Windows menu to select the ProcessBook title and switch among them.
Click inside a ProcessBook window to make it active.
Switch among the open windows by pressing CTRL+F6.
To obtain a Run Mode pointer, on the Drawing toolbar, click the Run button , or
Choose Tools > Run.
The mouse cursor appears in the shape of a small arrow.
Note: You can choose Build mode as your preferred mode of operation by setting this
preference in the General tab (page 18) of the ProcessBook Preferences dialog.
Note: You can add entry titles to a ProcessBook and then complete the detailed design
of the entries later.
When you add entries to a ProcessBook in either Outline or Book View, the entries are
arranged hierarchically. Subentries are indented under main entries. The name you give each
new entry is the name that shows in the ProcessBook.
When you create a new entry, it is placed in the ProcessBook just before the selected entry. If
no entries are selected, the new entry appears at the end of the current tab section in Book
View or at the end of the Outline View. You can press the ESC key to clear all entries.
Use text entries to add labels and clarify text in a ProcessBook. Display entries represent a
display in a ProcessBook.
1. Choose File > New. The New dialog appears.
2. Under Type, select ProcessBook Entry.
3. Click OK.
4. The Define ProcessBook Entry dialog appears.
5. In the Label dialog, type a name.
Note: There is no limit to the number of characters you may use, but for headings,
you should try to be as brief and descriptive as possible.
Note: If you are creating the first entry in the ProcessBook, the level is automatically
set to 1 and cannot be changed.
36
Add ProcessBook Entries
8. Click OK. The entry is added to the ProcessBook. If the entry is at Level 1 and you are in
Book view, a tab is created using the name of the entry.
9. Click the Save button on the toolbar, or
Choose File > Save. If you are creating several entries in one session you may wait to
save until the last one is created.
A Linked Display allows you to use a display name to link to an entry elsewhere in the
ProcessBook or in another ProcessBook or independent display file. This means that you
create and store only one copy of the display.
You can then access the same entry from several different locations in one ProcessBook. Or,
while you are in one ProcessBook, you can open an entry from another one without having to
close the first ProcessBook.
The linked entry is not a copy; it is a way of opening the original. The Book View or Outline
View shows the title of the linked entry, but the actual display window shows the title of the
original entry.
If you edit the original from any linked entry, the original is updated and automatically
appears updated from all the ProcessBooks in which it is linked.
To prevent unexpected updates, you can restrict access to an entry so that only the original
entry can be edited and all others to which it is linked are read-only. If the entry resides on a
server, you can write-protect the file on the server. If you need more information on
restricting access to files, see your System Administrator.
Before you create a link to an original entry in a different ProcessBook, the ProcessBook that
contains the original (target) entry must be open. Once the link is established, you only need
to open the ProcessBook with the Linked Entry.
If you want to link to an entry in a second ProcessBook, open the second book. If you want to
link to an entry in the current ProcessBook, create the original first and then the link.
Note: There is no limit to the number of characters you may use, but for headings,
you should try to be as brief and descriptive as possible.
Note: If you are creating the first entry in the ProcessBook, the level is automatically
set to 1 and cannot be changed.
12. Clear the Options check box if you want the absolute path used first.
Note: By default, ProcessBook attempts to open a linked display from its relative
path first. If the relative path fails, then the absolute path is checked. Clearing
the Use relative path check box reverses the order in which the paths are
resolved. For new displays, this option is checked by default.
13. Click OK. A linked display entry icon is added to the outline and book view of the
ProcessBook you are developing.
14. Click the Save button. If you are creating several entries, you may wait to save until the
last one is entered.
Note: If you need to move the original entry to another directory or ProcessBook,
you must redefine the link between the ProcessBooks. If you move both the
original and the linked item and the relationship between the two file paths is
unchanged, you do not need to relink.
38
Add ProcessBook Entries
An operating system command is used to start another application, such as Microsoft Excel,
in addition to PI ProcessBook.
For example, you can use an operating system command to link to PI DataLink reports or
calculations. You can also create links to CAD drawings, modeling packages, or statistics
packages.
When you have reports created on a different system, you can convert them to ASCII and,
using an operating system command, create a link to Notepad to read the reports.
If your company has online Help files for certain procedures, you can create a link to those
help files.
Your computer must have enough memory to run the applications you want to use in addition
to PI ProcessBook. The applications also must be installed on your system. If you do not
know whether or not your computer has enough memory, contact your System Administrator.
Note: There is no limit to the number of characters you may use, but for headings,
you should try to be as brief and descriptive as possible.
Note: If you know the name of the .exe file for the application, such as
C:\excel\Excel.exe for Excel or the path and name of a data file, such as
C:\document\report.xls, then you can type the path directly in the
Action box.
9. If you need to specify the location of the executable for the application, click the Browse
button to the right of the Working folder box. The Browse for Folder dialog appears.
10. Locate and select the folder that you want to specify for this operating system command,
and click OK.
Note: If you know the name of the working folder for this application, then you can
type it directly in the Working folder box.
11. In the Level list, click the level at which you want to position the entry in the
ProcessBook hierarchy of entries, or
Type a number between 1 and 10.
Note: If you are creating the first entry in the ProcessBook, the level is automatically
set to 1 and cannot be changed.
12. By default, ProcessBook attempts to launch an OS command from its relative path first.
If the relative path fails, then the absolute path is attempted. To reverse the order, clear
the Use relative path before absolute path check box. For new displays, this option is
checked by default.
13. If the file specified in the Action box is associated with one application and you want to
open it with another, select the Ignore the default shell command for recognized file
types check box. This option is normally only used with files such as displays saved as
SVG so that they can be opened in PI ProcessBook instead of the associated Viewer
application.
Note: If the file type is supported by ProcessBook (either natively or through an add-
in), then it is opened directly when this option is selecte for a Link or OS
command entry. For example, an .svg file is opened using the .svg File
Converter in ProcessBook, even if you have Adobe SVG Viewer installed.
Clearing this check box disables this behavior, so the default shell command
is used to open the file instead.
14. Click OK. An icon for the program you are launching is added to the outline and book
view of the ProcessBook and the application opens. Close the application.
15. Click the Save button. If you are creating several entries, you may wait to save until the
last one is entered.
Note: If you need to move the original entry to another directory or ProcessBook,
you must redefine the link between the ProcessBooks. If you move both the
original and the linked item and the relationship between the two file paths is
unchanged, you do not need to relink.
40
Arrange ProcessBook Entries
Book View
section. The boiler, the condenser, and the pump may be separate displays that are arranged
underneath the summary display. Each of these displays can have several displays for their
components.
Book View
Resize a ProcessBook
1. Click and drag on the frame of a ProcessBook until the window is the size you want.
As you make a window smaller, the ProcessBook is resized so you can still see all of the
tabs. If the window becomes too small to display all the members of a group of displays,
the displays are moved to new pages.
2. If the ProcessBook window becomes too small, all the tabs behind the first tab are
collapsed into one tab labeled More. Click the More tab to display a pop-up list of the
other tab sections.
42
Arrange ProcessBook Entries
Outline View
Outline View
-or-
Click the transparent plus sign to collapse the list of subordinate displays.
44
Arrange ProcessBook Entries
Expanded View:
Note: You can change the font for each level in Outline View in the ProcessBook
Preferences (page 18) dialog.
Note: If you highlight an entry first, the new entry is placed above the highlighted entry.
Remove an Entry
1. In Build mode, select an entry title in either Book View or Outline View.
2. Press the DELETE key. The entry is removed from the ProcessBook.
Note: If you accidentally delete the wrong entry choose Edit > Undo.
If you frequently work with several specific displays in a ProcessBook, open the displays and
arrange them in the workspace as you would like them. Save the ProcessBook. When you
reopen the displays, they will be in the same position as when you closed them.
After creating a ProcessBook, it is a good idea to name the file and save it immediately. It is
also important to save a ProcessBook periodically while you are working in it.
When you save a ProcessBook, all changes to all entries and to the organizational structure
are stored permanently. The ProcessBook remains open in your workspace so you can
continue working.
1. To save a ProcessBook for the first time, choose File > Save or Save As. The Save As
dialog appears.
2. Type a name for the ProcessBook file. A .piw extension is automatically added.
3. Select the drive and directory where you want to save it.
4. Click OK.
46
Properties
Properties
Choose File > Properties to display the Summary Information dialog for a file. The
Summary Information dialog you see is the same for the ProcessBook as a whole or for the
individual displays.
The following table describes the fields in the Summary Information dialog:
Field Name Description
Author Extracted from the Author field on the Start tab in the ProcessBook
Preferences dialog at the time the ProcessBook is first saved.
Title Name of the ProcessBook (extracted from the original creation of the
ProcessBook).
Subject May be used to explain the title more fully.
Keywords May be added at any time. There will soon be search capabilities
associated with keywords.
Comments May be used for any text entry. You can revise this field at any time.
Properties button Clicking the Properties button displays the PI ProcessBook Properties
(page 48) dialog, which gives information about the view currently in the
active window.
1. Choose File > Properties to display the Summary Information (page 47) dialog.
2. Click the Properties button. The PI ProcessBook Properties dialog appears.
Note: If you click the Properties button while an display is open, you launch the Display
Properties dialog.
The following table describes the fields in the PI ProcessBook Properties dialog:
Field Name Description
Last Saved By Name of the person who saved the ProcessBook most recently. (Extracted
from the Author field on the Start tab in the ProcessBook Preferences
dialog.) If this field is blank, the PC login name of the author is used. This is
useful for tracking who made which revisions.
Revision Number of times the ProcessBook has been revised and saved.
System Commands Total number of operating system command entries in the ProcessBook.
48
Properties
Note: The ProcessBook title is different from the file name established in the New
dialog when you created the new ProcessBook. The title bar on the
ProcessBook window displays the file name, which ends in .piw, rather than
the title.
4. Click OK.
1. With a display window selected, choose File > Properties to display the Summary
Information (page 47) dialog.
2. Click the Properties button. The Display Properties dialog appears.
The following table describes the fields in the Display Properties dialog:
Field Name Description
Created By Extracted from the Author field on the Start tab in the ProcessBook
Preferences dialog box. Shows the original author, unless the author’s
name has been modified in the Summary Information dialog.
Last Saved Most recent revision date and time.
Last Saved By Name of the person who saved the ProcessBook most recently. (Extracted
from the Author field on the Start tab in the ProcessBook Preferences
dialog.) If this field is blank, the PC login name of the author is used. This is
useful for tracking who made which revisions.
Revision Number of times the ProcessBook has been revised and saved.
Dynamic Symbols The number of display symbols that are dynamic symbols.
Static Symbols The number of display symbols that are static symbols.
Note: Depending on the size, some files may take several minutes to import.
50
File Sharing Capability
When a trend is successfully imported, a new Text display showing the full file name is
added to the ProcessBook. Each trend is added as a subordinate display and retains its
original trend name. For graphics, the VAX display name becomes the Display name. Once
converted, graphics and trends can be edited like any other display.
Static Symbols
Static symbols are symbols that do not automatically change as time passes, such as a process
diagram or descriptive text.
Static symbols include all items in a display that do not connect to the PI Server or other
application to retrieve data, and do not start any application. Text labels and flow lines are
examples of static symbols. Other types include rectangles, circles, arcs, and images.
Dynamic Symbols
Dynamic symbols are values, bars, trends, XYPlots, and Multi-State Symbols (such as a
pump) that change over time, that are based on the value of a tag in the PI Archive. If you
wish to see how a dynamic symbol was defined, select it and click the Item Definition button
on the Drawing toolbar.
Dynamic symbols may also report data from outside databases through queries.
If you rest your mouse on a value, bar, or Multi-State Symbol, you can see a ToolTip with the
current value, tag name, and time stamp.
Icons for questionable, substituted, and annotated PI data can also appear on your displays.
Most point types can be used with any dynamic symbol. There are some restrictions on string
and timestamp data. PI ProcessBook handles a full range of PI Server data types, as shown in
this table:
Buttons
Buttons are elements that create a link to other applications, such as a calculator or word
processor, or other ProcessBooks or displays. You can also use buttons to execute a script.
For example, if you find you work in a particular display and frequently need to update a
report with the information you are monitoring, you can add a button that automatically opens
a spreadsheet program. You also can use a button to connect to frequently used displays,
other ProcessBooks, or Web sites.
OLE Objects
OLE objects include information from outside applications, such as text, spreadsheets, or
graphics. This information may be configured to update dynamically. OLE objects may be
either linked (page 176) or embedded (page 175) into displays.
54
Manage Displays and Independent Display Files
Open a Display
Use any of these procedures to open a display from either Book View (page 41) or Outline
View (page 44) of a ProcessBook:
Click on the display title, then on the New button to open the selected display in a new
window.
Click on the display title, then on the Open button to open the display into the last
display window you used. If none are open, a display window opens.
With the Run Mode pointer, double-click the display. The display opens and appears
within an existing window, if possible.
Click and drag the display title to an unused area in the application workspace and release
the mouse. This opens a new display in addition to already opened displays. If you drag
the display on top of an open display, it closes that display while opening the dragged
display.
To use the keyboard instead of the mouse, use CTRL+F6, to select the ProcessBook, then
use the up or down arrow keys to select the display title. Press Enter. If you have more
than one display open, it replaces the open display with the new display. Pressing
CTRL+N is the same as clicking the New button.
If the display is a Display, Linked Display, or Linked ProcessBook, the display is opened and
the contents are displayed on your workspace. If the display is an Operating System
Command, the command is executed or the application is started.
Note: If you click on an Operating System Command more than once in the same
session, it may run the application repeatedly. This depends on the application
and how it has been set up.
Displays re-open in the same position, size, and shape as when they were last saved.
Window > Cascade—The titles of all open displays and ProcessBooks appear in a
cascaded list down the screen.
Window > Tile—All open displays and ProcessBooks appear in a tiled view.
Window > <display title>—The selected display is active.
You can select a .pdi file and look at it in Internet Explorer. PI ProcessBook menus and
toolbars appear in the Internet Explorer window. This is similar to embedding a display in
Excel, except that the display becomes the entire Internet Explorer document.
The display is updated as it would be within a PI ProcessBook.
Use the Zoom command to change the size of the drawing within a display window.
Note: There is also a zoom level combo box on the Standard toolbar . Use
this to enter or select a scale factor, or choose Fit All.
To resize the window to fill the monitor, click the Maximize button in the upper right
hand corner of your display window. When you maximize a display, all open windows
are maximized. You can also drag the edge or corner of the window to the desired size.
To minimize the display again, click the Minimize button in the upper right hand corner
of your display window.
56
Manage Displays and Independent Display Files
Note: If you have your Preference setting for Preserve Aspect Ratio check box
selected, the contents of the display resize as you resize the window. If this option
is not enabled, the size of each element in the display does not change as you
change the window size.
1. Click the Full Screen button on the Full Screen toolbar . Other toolbars vanish and
the display enlarges to fit the screen.
2. Click the Full Screen button again to restore your toolbars. A default keyboard shortcut
of F11 also toggles between Full Screen and Normal presentations.
Note: You can customize the Full Screen toolbar to contain other buttons to use with a
Full Screen display.
3. In the Name box, type one or more of the letters of the display name.
4. In the Look in drop-down list, click the location you want to search.
-or-
In the drop-down list, click Browse, and then locate the appropriate folder.
5. Select the Look in subfolders check box (optional).
6. Click the Search button.
7. The search results are displayed under Results.
8. Under Filename, click the display you want to open and then click OK.
If you find your work area cluttered with many open displays, you can reduce a display to an
icon by clicking its Minimize button. Even though the display is minimized, it continues to
be updated with information from the PI Server, however the results are not shown until the
window is restored. When you want to use the display, double-click the icon.
Save a Display
Display Settings
58
Manage Displays and Independent Display Files
Double-click the Time Zone setting in the Status bar. The Display Settings dialog appears.
Background Color—The color applied to the area of the display where there are no symbols.
This field uses a color well control to provide color choices. The color selected in this field
also becomes the default background color for new displays.
Time Zone—This field determines whether the local computer or PI Server time zone is used
for interpreting dates and times.
Connectors—The Enable Connector Attachments check box allows a symbol dragged and
dropped on a Connector symbol to be attached to that Connector. Clearing the check box
disables this functionality for the Display. Note that even if this feature is disabled for the
Display, the you can still use the Connectors dialog to attach Symbols to Connectors.
OK—Clicking this button accepts the changes made and closes the dialog box. These settings
are saved as part of the Display object.
Run mode scrolling—Determines the scroll bar behavior of display windows in Run mode.
Build mode scrolling—Determines the scroll bar behavior of display windows in Build
mode.
On Display contains scroll bars all the time.
Off Scroll bars never appear.
Automatic Scroll bars appear when needed (this is the default setting for new displays).
Drawing Area
The drawing area of a display is actually much larger than your monitor. There are scroll bars
on the display window for moving around this area.
You should plan to set a few options before you begin drawing:
Consider turning on grid snap and setting the grid size, font style, and default colors of
lines, backgrounds, and fills before you begin. It is usually easier to work with a grid
when laying out a display. Symbols in your drawing automatically align themselves with
the grid lines or the intersections of grid lines. Grid lines not only make it easier to place
objects in the drawing, but it helps keep the objects proportional. You can start with one
grid size and then modify it as your work gets more detailed.
Select a font and font size for any values, trends, or text boxes you might add to the
drawing.
Select colors for lines, fills, and backgrounds that are easy on the eyes.
While you are drawing, you can use the zoom feature to zoom in on an area that requires
more attention. Zoom out if the drawing is larger than your monitor.
Tags
A tag, which may also be called a point, is any measurement or calculation that is received or
generated periodically. It can consist of transmitter readings, manual inputs, status, or control
limits.
There are three types of tag searches you can perform: Basic, Advanced, and Alias. Searches
can be defined and then saved for future use.
Click the Tag Search button to open the Tag Search dialog (page 61).
For more information on tags click the Help button from any Tag Search dialog in PI
ProcessBook, or
open the PISDKToolsUsr.chm Help file, typically located here:
C:\Program Files\PIPC\HELP
Either action launches the PI SDK Controls and Dialogs user help.
60
Display Point Attributes
The Tag Search dialog is used to locate tags (page 60) (a name of a point that is a
measurement or calculation received or generated periodically). The Tag Search dialog box
contains three tabs (Basic Search, Advanced Search, and Alias Search).
These categories include all the attributes from the Base PointClass. The Base PointClass
attributes are common to all PI Points. If the PI Point that is being displayed is not from the
Base PointClass, there is one additional category. This category is given the name of the
PointClass to which the displayed PI Point belongs. The PointClass-specific attributes are
displayed in this category.
The Alphabetic tab displays the attributes alphabetically.
Drawing Tools
PI ProcessBook includes a drawing environment with features that allow you to create
symbols and graphics within an entry.
You can use the drawing tools to:
Create ellipses, polygons, rectangles, arcs, lines, and polylines
Add dynamic elements such as values, bars, trends, buttons, and graphic files
Add ActiveX controls
The Drawing toolbar contains a set of buttons used for creating drawings and the Draw
menu contains the corresponding commands.
To use the drawing tools, click the appropriate button.
When you draw a line or other shape, the tool uses the current formatting attribute (page 63)
preferences.
Each of these objects is considered a symbol by PI ProcessBook. In Build mode, when you
select a symbol by clicking it with your mouse, you see small squares around the bounding
rectangle of the symbol. These are called selection handles and allow you to resize the
symbol. For arcs, polygons, and polylines, there are also reshaping handles at the intersection
of the line segments.
Each symbol has a name, reflecting the order in which it was added to the display, such as
Rectangle1, Rectangle2, etc.
In Build mode (or VBA Design mode), an identifying ToolTip (page 68) appears whenever
your mouse hovers over a symbol.
Note: If you are drawing multiple objects, press the CTRL key while selecting the
drawing tool. This lets you continue to work with that tool until you select a
different tool.
Organizing Symbols
PI ProcessBook provides several tools to help you organize your drawings. These tools
include a drawing grid, flip and rotate capabilities, and the ability to change the order in
which objects overlap each other. You can move and resize drawing objects. You can also
divide a display into layers so that you can segregate various elements. For example, you
might separate HVAC elements from Electrical elements in a display.
62
Formatting
Any of these functions can be performed on a single screen element or group of them. For
information on grouping objects, see Grouping Symbols (page 141).
Make sure you have selected the item or items with the Build Mode pointer.
OLE objects behave somewhat differently; their behavior is discussed under Commands that
Ignore OLE Objects (page 178).
Drawing Grid
The grid is a system of vertical and horizontal lines spaced at regular intervals on the drawing
area. Dots are placed at the intersection of the grid lines. The grid helps you align drawing
objects.
When you move an object to a location on the drawing area, the corners or edges of the object
are aligned with the closest grid intersection. This is called snap-to-grid or grid snap. When
you turn off grid snap, you can move an object to any location within the drawing area.
You determine the interval at which you want the grid lines to be spaced by setting the grid
size.
Note: The size of a unit as displayed on your monitor varies according to the
monitor's resolution and driver software.
5. Select the Snap to Grid check box. Once grid snap is on, any symbols you draw are
automatically aligned to the grid.
Note: The Snap to Grid command also appears on the Arrange menu.
6. Click OK.
Formatting
Each symbol you draw and place on a display has attributes that determine how the symbol
looks. The fill and line attributes that are currently selected on the Display Window (page
21) tab of the ProcessBook Preference dialog are applied to any new drawing symbol. You
may configure these attributes for individual symbols or for all selected symbols as a group.
New in version 3.1, the Symbol Formatting toolbar contains buttons for formatting fonts,
colors, and line styles. PI ProcessBook also includes the older Formatting toolbar to support
backwards compatibility
Line X X X X
Rectangle X X X X
Text X X
Ellipse X X X X
Arc X X X X
Value X X
Polygon X X X X
Polyline X X X
Bar X X X X
Trend X X X X
Font
To determine what type of formatting is applicable for each symbol, refer to the table of
editable formatting attributes.
1. In Build mode, open a display, and click the symbol(s) whose font you want to change.
2. On the Symbol Formatting toolbar, click a name in the Font box.
Note: When choosing fonts, plan to use fonts that other PI ProcessBook users are
likely to have. If another user does not have the fonts you used, PI
ProcessBook attempts to match the font to an existing font. However, the
match may make it difficult for another user to read the entry.
64
Formatting
Line Color
To determine what type of formatting is applicable for each symbol, refer to the table of
editable formatting attributes.
1. In Build mode, open a display, and click the symbol(s) whose line color you want to
change.
Fill Color
To determine what type of formatting is applicable for each symbol, refer to the table of
editable formatting attributes.
1. In Build mode, open a display, and click the symbol(s) whose fill color you want to
change.
2. On the Symbol Formatting toolbar, click the Fill Color button . The interior color
of the selected symbol(s) changes.
Note: The Fill Color button is disabled if the selected symbol has no interior.
3. Click the arrow on the right side of the Fill Color button to display the color palette.
Choose from the 16 colors available or click on one of these two buttons:
• Custom Color—Launches the Color dialog where you can choose additional colors
from a color well of options
• None—Disables fill color. Setting the fill color to None shows the display
background color.
Background Color
To determine what type of formatting is applicable for each symbol, refer to the table of
editable formatting attributes.
1. In Build mode, open a display, and click the symbol(s) whose background color you
want to change.
2. On the Symbol Formatting toolbar, click the Background Color button . The
background of the selected symbol changes.
Note: The Background Color button is disabled if the selected symbol has no
background.
3. Click the arrow on the right side of the Background Color button to display the color
palette. Choose from the 16 colors available or click on one of these two buttons:
• Custom Color—Launches the Color dialog where you can choose additional colors
from a color well of options
• None—Disables background color. Setting the background color to None shows the
display background color.
Line Weight
To determine what type of formatting is applicable for each symbol, refer to the table of
editable formatting attributes.
1. In Build mode, open a display, and click the symbol(s) whose line weight you want to
change.
2. On the Symbol Formatting toolbar, click the Line Weight button . A list of six line
weight options appears below the button.
3. Select a line weight. The thickness of the selected symbol's line weight changes.
Line Style
To determine what type of formatting is applicable for each symbol, refer to the table of
editable formatting attributes.
1. In Build mode, open a display, and click the symbol(s) whose line style you want to
change.
2. On the Symbol Formatting toolbar, click the Line Style button . A list of six line
style options appears below the button. Options include solid, dash, dot, dash-dot, dash-
dot-dot, and none. Selecting None for a trend Pen element hides the trace line, but not the
marker.
3. Select a line option. The symbol's line pattern changes.
66
Formatting
Line Ends
To determine what type of formatting is applicable for each symbol, refer to the table of
editable formatting attributes.
1. In Build mode, open a display, and click the symbol(s) whose line ends you want to
change.
2. On the Symbol Formatting toolbar, click the Line Ends button . A list of four line
ends options appears below the button. These options determine whether arrows appear at
the end of lines.
3. Select a line ends option. The selected symbol's line pattern changes.
Formatting Paintbrush
To determine what type of formatting is applicable for each symbol, refer to the table of
editable formatting attributes.
1. In Build mode, open a display, and click the symbol(s) whose font, color, or line
formatting you want to replicate.
Note: Double clicking the Formatting Paintbrush button allows you to apply
formatting to more than one symbol. To turn off the Formatting Paintbrush
selection, click the button again or press ESC.
3. Click another symbol. The formatting of the first symbol is copied to the selected
symbol(s).
ToolTip Statistics
In Run mode, hover your mouse over a point on a dynamic symbol to display a ToolTip with
summary statistics. Engineering units are shown next to the value followed by the timestamp
paired with the value. If you hover your mouse over a point where there is more than one
trace, each trace's data is shown on a separate line.
Choose Tools > ToolTip Statistics to launch the ToolTip Statistics dialog, where you can
select what type of data you want to see when viewing ToolTips.
68
Layers within Displays
Create Layers
1. Open a display.
3. Click the New Layer button to open the New Layer dialog.
A default name comprised of the word Layer prefixed to the layer number appears. The
layer number does not necessarily match the index number; it is simply the next unused
integer in the list.
A new layer is added to the end of the collection. Its index is one higher than the previous
high index number. All symbols added to this layer are displayed over symbols on lower
indexed layers.
4. Click OK to return to the Layers dialog.
• Index—specifies the index number of the layer. The index is used in determining the
display order (Z Order) of overlapping symbols. A layer with a lower index number
is lower in the stack than one with a higher number. Higher layers may obscure
symbols in lower levels.
• Count—this is a read-only value that contains the number of symbols on a layer. A
composite symbol is counted once and each of its subordinate individual symbols is
also counted.
• Up/down arrows—buttons at the right side of the dialog box are used to move the
relative position of one layer to another within a display. As a layer is moved down
the list, its index number becomes larger, and vice versa. Symbols on layers with
higher index numbers may hide or cover symbols with lower-index numbers. Locked
layers cannot be reordered.
5. Select the appropriate check boxes:
• Visible—makes the elements in the layer visible in Run mode. New layers are
visible by default.
• Active—accepts all new symbols as you add them to the display. Inactive prevents
symbols from being added automatically. New layers are Active by default.
• Locked—prevents you from adding symbols to a layer. Existing symbols on locked
layers cannot be cut, copied, pasted, deleted, or moved. New layers are not locked by
default.
6. Repeat steps 3-5 as needed. Click OK to accept changes and close the Layers dialog.
If you have at least one layer in a display, you can assign symbols to it.
1. Select a symbol, right-click, and select Assign Layers.
The Assign Layers dialog appears and displays all of your existing layers.
70
Layers within Displays
2. Select or clear the checkbox next to a layer name to add or remove the selected symbol
from a layer. If a layer name is grayed out, the layer is locked and you cannot add or
remove symbols. You may add the same symbol to more than one layer.
3. Click OK.
To link symbols and create composite symbols choose Arrange > Group, or click the
Group button on the Layout toolbar. The symbols may be on different layers when they
are grouped.
Assign a composite symbol to any layer(s) regardless of its component symbols.
You can not group symbols on locked layers into a composite symbol, but the layers may
be locked after the symbols are grouped.
You can not delete a composite symbol that contains symbols on locked layers, however,
you can delete an unlocked layer.
Normally, a symbol existing only on one layer is deleted if the layer is deleted, but when
the symbol is inside a composite symbol it is not deleted. It stays in the composite
symbol.
If a composite symbol is hidden, all its parts are hidden. If the composite symbol is
visible its individual parts may still be hidden if the layers they are assigned to are
hidden.
Since you can not individually select the parts of a composite symbol you must first use
the Ungroup button to separate them in order to change their layer assignments
individually.
The Layers icon on the Status Bar shows whether or not the display has more than one layer.
This icon appears in the status bar at the bottom of your application, indicating one or more
layers in the display currently in focus. Double-clicking the icon displays the Layers dialog.
If no layers have been defined, the icon appears with a slash through it.
Hovering the mouse over the icon displays a tooltip with the names of any active layers,
beginning with the top layer.
Module-relative Displays
The Module Context Display PI ProcessBook add-in is designed to give you a way to create
dynamic symbols in a display for a general structure, and then to apply data to the display
symbols using different instances of the structure. For example, you can use the same
dynamic symbol, such as a trend, and scroll through the Available Modules window to
display that trend with different data points representing the selected item in the Available
Modules window.
The add-in gives PI ProcessBook access to the PI SDK Module Database, taking advantage
of its contents as well as its structure.
The Module Context Add-in:
Allows you to use aliases as a data source for dynamic symbols so that a tag can be
changed without redefining a symbol that uses it indirectly through its alias.
Allows you to use properties in dynamic symbols to show user-defined supplementary
information.
Allows you at run-time to switch among different PI SDK Module Database Nodes using
the existing display symbols.
The PI SDK Module Database organization is similar to a file directory structure. Each node
(which is like a directory) is called a Module, and can contain:
Properties, which are variables containing any kind of data (including arrays, and
collections of more properties)
Aliases (like variables for a tag name)
Modules (sub-modules, like sub-directories in a file directory)
Properties and aliases in the Module Database are time-dependent. See the PI SDK
Online Help for more information on the Module Database.
Features
The Module Context Add-in supports the following features:
Use of Module Database Aliases in dynamic symbols.
Use of Module Database String and Numeric PI Properties in dynamic symbols.
A user option at design time (Select Available Modules dialog) to choose Contexts to
make available at run time. Contexts are saved with the display or independent display,
not with a ProcessBook or the application.
A Configuration Dialog (Select Items dialog) for assigning these Aliases and Properties
to dynamic symbols in ProcessBook.
Use of Current Context String in dynamic symbols. This provides a mechanism to show
the currently selected context in a display.
A way to change the context at run-time (Available Modules Window).
Programmatic access to the Available Context values.
72
Module-relative Displays
When the Module Context Add-in is loaded in ProcessBook a Module Context menu item is
added to the Tools menu. This menu item provides one submenu option, Add Module.
Available modules for the current display are also listed in a docked window at the left of the
display.
Note: When you change focus from a display to a table of contents window, there are no
available modules listed.
At least one module must be selected using the Select Available Modules dialog before a
dynamic symbol can be configured to use a module alias or property. More modules may be
added later.
Unresolved contexts display as NO DATA. An unresolved context occurs when a dynamic
symbol is configured to show a property and the active context doesn't have the property. For
example, suppose you select Module1 and Module2 as the available contexts. Module1
contains PropertyA and Module2 contains PropertyB. A dynamic symbol is
configured to display PropertyB. If Module1 is the current context, NO DATA appears in
the dynamic symbol.
74
Module-relative Displays
Note: Click the Add Modules button to open the Select Available Modules (page
73) dialog.
3. To display the current module context in the dynamic symbol, click the Current Context
check box above the Selected Items list.
4. Click OK.
Note: When you shift focus from a display to a table of contents window, there are no
available modules listed. If you select a different display window, the list of
available modules is likely to be different.
76
Chapter 5
Trends
A trend is a type of dynamic element that lets you plot values against time. Use trends to
show the value of one or more tags over a time period. You may also use trends to show the
results of a data set query or to combine data from the PI Server and other sources. Generally,
trends are used to graphically display time series data, although you may also include non-
time series data.
Some components of trends include:
Traces—Lines drawn on a trend to represent a series of data points, either from a PI Tag
or a data set column.
Pens—Formatting components used to determine the presentation of trends.
Plot—The title of the trend being configured. The plot title can be blank, but a title is
supplied by default.
Grid lines—Used to mark intervals along the time and value scales.
If the Plot Time continues through the current time, the trend updates as information changes,
unless the length of the overall time period exceeds the limit set by your System
Administrator. The default limit is 24 hours.
Create a Trend
1. Open a display.
4. In the Plot box, type a name. Click the New Plot button if you want to build a trend with
multiple plots (page 80).
5. In the Tags in Plot box, type the name of the tag, or
Click the Tag Search button to locate the tag, or
Click the Tag Search arrow to see more search options.
6. If you manually enter tag names, select the appropriate PI server from the Server drop-
down list. Normally, the default PI Server is listed.
7. You can rearrange, add to, or delete the selected tags by clicking one of the buttons above
the Tags in Plot box.
8. Under Scale, select Single Scale or, if you have more than one trace, you may select
Multiple Scales. The multiple scales option shows a value range for each trace. There is
only one time scale.
9. Consider checking the following check boxes:
• Logarithmic—to display the data in a logarithmic scale. If you have multiple scales,
you may set this option differently for each trace. This option is disabled for digital
tags.
Note: You may use logarithmic and non-logarithmic scales for traces in the same
trend when you select the Multiple Scales option. In this case, the minor grid
lines associated with a logarithmic plot may confuse the plot. You can turn off
the minor grid lines by setting the vertical minor grid color or line style to none.
78
Create a Trend
Min Settings:
• Autorange—The trend displays with the value scale starting at the closest available
major axis. If the minimum is Autorange and the maximum is not, the scale starts at
the lowest data value in the trace (not on a major axis) and ends on the closest major
axis.
• Database—The tag's Zero attribute is used to specify the minimum plot value. If the
Zero value is <= 0, the minimum is re-interpreted as Autorange.
• 0 (absolute value)—The value you type is used as the first value on the value scale.
Max Settings:
• Autorange—The trend displays with the value scale ending at the closest available
major axis. If the maximum is Autorange and the minimum is not, the plot starts on
the minimum value and ends on the largest trace value (neither min nor max will be
on a major axis).
• Database—The tag's Zero + Span attributes are used to specify the maximum plot
value.
• 0 (absolute value)—The value you type is used as the value scale maximum.
11. From the Format drop-down list, select the number format for the scale. Database is the
default format. This number format is also applied to legend, cursor, and ToolTip
numbers.
• Database—Database format looks at a PI Tag's display digits attribute and displays
the value scale numbers in standard format. If the length of the number exceeds the
display digits value, scientific notation is used.
• Scientific—Scientific notation is used for all values. There is no change to the
scientific format used for trends. It displays in the format: 0.00E+00.
• Standard format (do not switch to scientific format for large numbers)—The
significant digits are ignored for logarithmic plots, for example, format 0.0 does not
truncate 0.0000001 to 0.0. Because of precision issues, any number with more than
DBL_DIG (15) significant digits is rounded off at significant digit DBL_DIG. A
value of 12345678901234567890 is displayed as 12345678901234600000.
• General—The number is displayed with standard formatting with the exception of
numbers with more than DBL_DIG (15) digits. In this case, scientific notation is
used. The program logic uses 1.0e+15 and 1.0e-15 as the maximum and minimum for
standard formatting.
12. Under Plot Time, from the Start and End drop-down lists, select a time. An asterisk (*)
represents the current time.
13. In the Style drop-down list, select Full time stamp, Partial time stamp, or Relative
time stamp to indicate how time is displayed on the time axis.
14. Click OK.
Note: PI ProcessBook allows you to create custom placeholders for a symbol based on
a summary Data Set. Placeholders are not allowed for expression Data Sets. The
Custom Placeholders button in symbol definition dialog boxes allows you to
specify different PI Tags for a PI Summary Data Set. The change applies only to
the configured symbol. See Add or Edit Placeholders (page 163) for details.
For new trends, you can add additional plots so that many trends are created and configured
without dragging additional symbols on the display. Once the plots are created they are no
longer associated in any way and are configured, moved, and sized individually.
1. Follow the steps to create a trend (page 77).
2. To create additional plots, click the New Plot button and select tags. Repeat as necessary.
To view the tags you have selected, you can click each plot name in the Plot box.
3. To adjust the arrangement matrix for the plots you are creating, click the Layout tab
(page 83).
Note: These matrix options are available only when you create the trend and cannot
be edited later. However, you can revise the traces on each plot individually.
Move a Plot
If you have created more than one plot in the trend, you can move each plot separately.
In Build mode simply click the plot you want to move. Selection handles appear around the
plot. Use these handles to drag the plot to its new location.
Note: Once you have drawn a trend, and you want to delete a plot, you can select the
plot and then press DELETE.
80
Define Trend Dialog
As you create a new trend, you can specify the desired tags, the colors and fonts for traces,
legends, and backgrounds, as well as how much tag information is displayed with the trend.
Use the Symbol Formatting (page 63) toolbar to make trend formatting changes.
The Define Trend dialog has a General tab where you create a trend (page 77), and the
following additional tabs for formatting and layout:
Display Format (page 81)—options for the elements to be included in the trend.
Trace Format (page 82)—provides an alternate way to choose colors and line styles for
each trace (plot line) as well as the axes, background, and text.
Layout (page 83)—options determine the arrangement of rows and columns for multiple
plot trends. This tab only appears when you first create a trend symbol.
1. In Build mode, open a display, and click the trend whose attributes you want to change.
3. In the Legend group box, check or uncheck options for displaying the tag name, server
name, description, value, and engineering units. Your choices are reflected in the sample
trend at the bottom of the dialog.
The information that can fit in the legend is determined by the size of the trend.
Consequently, not all of the information in the legend may be visible.
• If the width of the legend is more than 50 percent of the width of the trend, the legend
does not display.
• If the length of the text in the legend is longer than the total height of the trend, the
items on the bottom are not shown.
4. In the Display box, check or uncheck the following options. The sample trend reflects the
changes you make.
• Plot Title
• Vertical Scale Inside Axis—Draws the value scale inside the plot area
• Grids—Shows grid lines on the trend
• Markers—When checked, markers indicate data points on the trend. If the Markers
box is not selected, three markers appear on each line to help you match a line to a
tag.
5. Choose a trend orientation from the three radio button options at the top of the dialog:
Now at right (horizontal), Now at top (vertical), or Now at bottom (vertical). New in PI
ProcessBook 3.1, this feature allows you to orient your trend in a horizontal or vertical
direction.
As of PI ProcessBook 3.1, you can use the buttons on the Symbol Formatting (page 63)
toolbar to configure plot elements such as pens (traces), text, and background.
The Trace Format tab gives you an alternate way to update formatting changes.
1. In Build mode, open a display, and click the trend whose attributes you want to change.
2. Open the Define Trend (page 80) dialog and click the Trace Format tab.
82
Define Trend Dialog
Layout Tab
The plot arrangement in a multi-plot trend is established by setting up the number of rows
and columns of plots in the Layout tab.
To revise the proposed plot arrangement matrix:
1. Follow the steps to build a trend with multiple plots (page 80).
2. In the Define Trend dialog, click the Layout tab.
3. Under Plot Arrangement, select the number of rows and columns you want. The
following example shows four plots, to be arranged in 2 rows of 2 columns each. Tab
past the matrix to see the sample of your new selection display in the Preview area.
4. When you are satisfied with the matrix arrangement, click OK to draw the plots.
Note: The Layout tab only appears when you initially create a trend (page 77). Once the
layout is set, you cannot revise it because the plots are no longer associated when
the symbol is created. However, individual plots can be moved on the display in
Build mode.
84
Trend Analysis Tools
Note: To return the trend scale to its original settings, choose View > Revert.
Drag Zoom
Drag Zoom lets you expand or contract the time scale of a trend.
1. With the Run Mode pointer, click an area in the trend at which you want a closer look.
2. Drag the pointer diagonally to create a rectangle.
3. When you release the mouse, the trend displays the data within the rectangle.
Click the Zoom In or Out button at the bottom of a trend to reduce or expand the time range
of that trend by a factor of 2. In other words, if your time range is 8 hours, Trend Zoom 2x
In divides the time range by 2 and displays the trend for a 4 hour time period. Trend Zoom
2x Out multiplies the time range by 2 and displays the trend for a 16 hour time period.
You can remove changes to the time range by clicking the Revert button .
Note: If the trend is too small these buttons may not appear. Simply expand the trend's
size to display hidden buttons.
If there are no trend cursors, the Trend Zoom 2x command zooms in or out of the last
portion of the time period. For example, if the initial time range is 60 minutes and you select
Trend Zoom 2x In, the trend displays the last 30 minutes. Trend Zoom 2x Out displays 120
minutes adding 60 minutes to the beginning of the trend.
When a trend cursor is displayed, the command uses the trend cursor as the center of the
zoomed trend. If several cursors are used, the last one set is used as the center of the zoomed
trend. See Trend Cursor (page 87), for more information on trend cursors.
Expand a Trend
When you double-click a trend in Run Mode, the trend is redrawn so that it occupies the
entire display window. Double-click again to reduce the trend to its original size.
While the trend is expanded, the Drawing toolbar is disabled. If you switch to another
display, the Drawing toolbar will work there.
All descriptive information (title, tag descriptor, tag value) is shown on an expanded trend.
86
Trend Analysis Tools
Trend Cursor
A trend cursor lets you read tag values for a particular time. When you select a trend cursor, a
vertical line indicates the cursor position. The box at the top of the line indicates the value
and status. The box at the bottom displays the time and date of the value.
You may display several trend cursors at one time.
Note: A trend does not update while trend cursors are visible.
If the trend is too small, the Trend Cursor command is disabled and the mouse pointer does
not change when you move over the left axis. You can expand the trend by double-clicking it.
Trend cursors may be automated.
2. With the Run mode pointer, click the Trend Cursor button . A cursor appears at the
right edge of the trend. When the mouse pointer changes to a double-headed arrow over
the trend cursor, click the vertical line and drag left to position the trend cursor, or
Choose View > Trend Cursor. An indented icon in front of the command indicates that
trend cursors are on.
3. Move the mouse pointer over the left axis of the trend. The pointer changes to a trend
cursor symbol. As you drag to the right, a new trend cursor is added to the trend
4. Move the trend cursor back and forth across the trend by dragging it. As you move it, the
time stamp, status, and value appear in a box at the top right of the trend.
5. When you release the cursor, the values appear in boxes at the top and bottom of the
cursor. You can add additional cursors by grabbing the trend cursor icon at the left axis.
Note: To remove one trend cursor but not all of them, click the trend cursor and drag it to
the left or right until it moves off of the trend.
on the time scale. These time changes are not saved with the symbol.
Use the Revert button , located next to the time scale, to return the trend to its configured
settings.
Note: If the trend is too small these buttons may not appear. Expand the trend's size to
display hidden buttons.
You can also use buttons on the Time Range (page 12) toolbar to modify time configurations
settings.
Note: If desired, a PI System Manager can change the one-day limit to another interval
on your computer.
PI ProcessBook uses an algorithm to identify the peaks so that no information is lost when
the trend time range is large. It ensures that the plot is not under- or over-sampled and that the
correct amount of information is sent from the PI Archive.
Unlike data from a PI Archive, data from an ODBC data set refreshes according to a
stipulated refresh rate.
Trend Appearance
A trend appears according to the format established in the Preference settings (page 22). You
may override this format by selecting the Trend Formatting (page 81) button .
Typically, the title of the trend appears at the upper left, and the current timestamp appears at
the upper right. The selected tag names, current or end value, and engineering units appear in
the legend opposite the value scale.
88
Trend Appearance
Trends are formatted according to certain defaults. Use the Trend Elements tab in the
ProcessBook Preferences dialog to create default formats for new trends. You can set
options like line colors and point markers, and set the types of point information included
with a trend.
Grid Lines
Horizontal and vertical grid lines align with even units (whole numbers) on the scales. Grid
lines for the value scale line up with whole numbers at intervals of 1, 2, 5, 10, or powers of
10 times those intervals. Grid lines for the time scale line up with time intervals such as
weeks, days, hours, minutes, etc. The lines then scroll as time passes on an updating trend.
Configure the labels for the time axis using a full timestamp, partial timestamp, or a relative
timestamp:
Full timestamp Displays a complete timestamp for the start and end times. The time range of
the trend is in the middle of the time axis.
Partial Labels most grid lines in the units of the time range. Displays the full
timestamp timestamp for the end time of the trend at the top right edge of the plot.
Relative Displays the offset from the end time limit in weeks, days, hours, etc. and the
timestamp full timestamp for the end time of the trend at the top right edge of the plot.
Note: Labels for the grid lines appear unless the trend rectangle is too small.
Grid lines are shown in value scale intervals of 1, 2, 5, 10, or powers of 10 times those
intervals.
The value axis at the left is scaled by one of four methods:
Autorange scale
Database scale
Logarithmic scale
Manually Defined scale
Autorange Scale
The value scale is determined by a calculation based on minimum and maximum values in
the trend. As new data are received from the server, the high and low values may change, and
the scale is recalculated accordingly.
For example, if the original scale ranged from 5 to 100, but the new data has a high of 103,
then the new plot shows a range from 5 to 105 (the nearest number divisible by 5 and larger
than the high value).
If more than one tag is plotted on a single scale, the value scale is calculated from the highest
and lowest values for all the tags.
Database Scale
If the scale is set to Database, the range is the same as the limits for the point on the server.
The minimum value is termed zero, and the maximum value is the sum of the zero value plus
the span value.
For example, suppose the tag attributes for a point are Zero = 3 and Span = 6. The plot range
therefore is based on making the minimum and maximum values 3 to 9.
Logarithmic Scale
If you prefer a logarithmic scale, check this option. This option is disabled for digital, string,
timestamp, or integer tags.
Value scales are labeled whenever there is enough room. Configured these labels with either
single or multiple scales.
For a single scale label, the union of the ranges for all the pens appears.
For multiple scale labels, the range for the first pen appears next to the value axis. Ranges
for the other pens appear in increasing distance from the axis in the order the tags are
listed in the trend legend.
Note: On a single scale trend, traces that contain only one value (a flat line) or have no
data are governed by special scaling rules. When a trend is composed of only flat
or no data traces, the default value scale range is inflated to prevent showing a flat
plot area. These default ranges are not applied if the trace in question is on a
single scale trend that contains other visible traces that do not fall into either of the
aforementioned categories.
90
Trend Appearance
A single scale trace containing one flat trace with a constant value of 0.
A single scale trend containing a flat trace and a non-flat trace. The default range for the flat trace is not
applied.
Grid lines for the time scale line up with whole units of time, such as days, hours, minutes,
etc. On a trend that receives updates, the grid lines scroll as time passes. For an updating
trend, the current time is indicated by a dotted vertical line.
Configure labels for the time axis in one of three ways:
Full Timestamp—labels the start and end time limits with the date and time. When
space permits, the elapsed time between these lines is also shown.
Partial Timestamp—labels each grid line in whole units, such as hours. For example,
the grid lines might be labeled 9:00, 10:00, and 11:00. A full timestamp showing the plot
end time is shown at the upper right.
Relative Timestamp—labels each grid line with the amount of time preceding the right
time limit in days, hours, minutes, or seconds. For example, the grid lines might be
labeled -4, -3, - 2, -1, meaning 4, 3, 2, and 1 hours previously. A Full Timestamp for the
last reading is shown at the upper right. A full timestamp showing the plot end time is
shown at the upper right.
Traces
A Trace, also referred to as a pen, is a single line on a trend. When a trace is continuous, a
line is drawn from measurement to measurement. When a trace is discrete, the value is
propagated forward until a new value is recorded in the database. This results in horizontal
and vertical lines for the tag (staircase trace).
Digital points are discrete type measurements, producing staircase traces. For digital points,
the offset from the starting digital state code is plotted. When the value is shown in a trend
cursor, ToolTip, or legend, the text translation is displayed (for example, ON or OFF).
Staircase traces are used for points from a PI Server that have a Step Flag set to TRUE.
ODBC queries may produce either curved or staircase traces, depending on the Stepped Plot
check box setting in the ODBC Data dialog.
Hide Traces
You can hide one or more traces on the trend in Run mode so that an area of concern is more
easily viewed.
1. Open a trend in Run mode.
2. Hover your mouse pointer over the trend's legend. The mouse pointer changes to a hand
cursor , and the trace in the trend is highlighted.
3. Click on the legend item to hide or show the trace on the plot. If the trace has a regression
line configured, the regression line is also hidden. When a trace is hidden:
• the trace name is dimmed in the legend and the description, value, and engineering
units are hidden (if they were shown before).
92
Trend Appearance
• the space reserved on the legend for the description, value, and engineering units
collapses so that the trace under the hidden trace is moved. This clearly shows the
visible traces on the legend, especially on a trend with many traces.
• on a multi-scale trend, the scale associated with the hidden trace is hidden.
• on a single scale trend, the minimum and maximum values shown on the scale may
be adjusted.
You can show hidden traces by clicking their names a second time in the legend, or by
clicking the Revert button. All hidden traces are shown in Build mode.
Note: You can also right click on a trend and select Show All or Hide All to make traces
visible or invisible.
Markers
Markers indicate data points and allow you to differentiate between traces on a trend. There
are three types of markers:
actual data
trace markers
bad data markers
At least three markers are shown on a trace, unless the plot is too small.
Trace Markers
If there are too many values to plot based on the size of the trend, the display resolution and
the density of the plotted data, actual data markers do not appear and trace markers are used
instead. Trace markers are also used if the trend configuration does not specify Markers.
Trace markers help you identify the legend information for each trace; they do not indicate
actual plot values. Up to three trace markers are used per trace.
X Markers
When a value is outside the limits defined for the trend, it is plotted as over- or under-range.
When a value is out of range or has a bad value, it is not shown on the plot. An X marker is
placed on the trend at the beginning and end of the time when data are not plotted. When the
data are missing, (for example, not connected to a server) they are given the value No Data
and are not plotted.
Ad Hoc Trends
Create a trend on an ad hoc basis for tags represented by dynamic symbols in a display within
a ProcessBook.
Ad hoc trends are like any other trends in that you can scroll the time forward and backward,
view cursors, zoom, view point attributes, use multiple scales, or change the time range.
To create an ad hoc trend, use either the Trend tool or Trend Display tool . The
Trend tool allows you to add a trend to an existing display. The Trend Display tool creates a
separate, new display with the instant trend.
Note: You can build a trend display before you open any displays.
If you create an ad hoc Trend Display and then choose to save it for future use, it appears on
the Book or Outline View as subordinate to the original display.
Click the Trend button . The mouse pointer changes to a trend pointer. Click in the
display and drag to create a rectangle. It is given the name Ad Hoc Trend.
The trend appears in the rectangle, using the default format.
Note: If you select more tags than the default set in your Preference settings, usually 3,
then you will have more than one plot in your trend or trend display.
If you create an ad hoc trend display and wish to save it for future use, then you must use the
Save or Save As command before you close the instant trend. There are several options:
Save an ad hoc trend display as an independent display by clicking it and using the Save
As command with a .pdi filename extension.
94
OpenVMS Trends and Graphics
If you had a display entry from a ProcessBook open when the instant trend was created,
the instant trend can be saved as a subordinate of the display by using the Save
command.
You may save an ad hoc trend as another file type, such as a bitmap (.bmp) file, using
Save As.
Convert Trends
This process is used to convert VAX graphics for use with a PC.
1. On the VAX or Alpha at the DCL prompt, type $ Run PISysExe:PIDisDIFF
2. Select option 1 List Master Display Library from the PI Display Data Interchange File
Format Builder.
3. Direct the output to a file.
4. Enter a file name. If your file name is more than 8 characters and a 3-character extension
(xxxxxxxx.xxx), the name is truncated during the download process.
5. Accept the defaults for display mask, group numbers and unit numbers (*).
6. Select the trend display types you are importing. For optimum performance select only
options 1 (horizontal), 2 (vertical), 3 (composite), and 8 (overview).
7. Quit the PIDisDIFF application (option Q).
8. Transfer the file from the VAX or Alpha to the PC using any ASCII text file transfer
program you have available.
Convert Graphics
This process is used to convert VAX graphics for use with a PC.
On the OpenVMS computer, copy a graphic file to your working directory. Graphic files are
named PISysDat:PIGP_xxxxxxxxxx.dat, where xxxxxxxxxx is the display
name.
1. At the DCL prompt, type $ RUN PISysExe:GPAB
2. Select option 1 Convert Binary to ASCII from the PI Graphics Package ASCII/Binary
File Conversion menu.
3. Type the display name of the graphic you want to convert and press Enter. Repeat for
each file you want to convert.
4. Select option Q to quit the application.
5. Transfer the file from the VAX or Alpha to the PC using any ASCII text file transfer
program you have available.
Your PI ProcessBook Install disks include an OpenVMS command file which performs Steps
1 - 5 for all graphics. The file is named GPPBConv.com.
96
Chapter 6
XYPlots
An XYPlot shows a correlation between one or more paired sets of data. On an XYPlot (also
called a scatter plot), the X scale shows possible values for one of the items in the pair and
the Y scale shows the value of the other item in the pair. A basic scatter plot looks like the
following:
Uncorrelated data
This case plotted 10-minute intervals of two points, A and B, for the last hour. Point A had 12
point values; Point B had 16 point values. The number of points plotted equals the number of
pairs. Since A had fewer point values, the plot shows only 12 point pairs. The extra data from
point B is ignored. You can configure the method by which pairing occurs.
Correlation is a measure of the strength of the relationship between two variables. Correlation
is indicated graphically by the spread of the data points around a fitted straight line (for
example, a straight line that indicates the trend of the data). In general, the closer the points
are to the fitted line, the stronger the correlation. The two PI tags shown in figure 1 are not
strongly correlated. Another plot shows perfectly correlated data:
Perfectly correlated
Somewhat correlated
In the case of the third plot, a regression line with a slope (M) of 1 and an offset (B) of 0
drawn diagonally across the plot would show all points lying close to the line, some above it,
some below it. This line formula is appropriate in this case because both scales are the same
and the points appear to have values very close to each other. In other cases, one value may
be two or three times the other value (for example) and the regression line would fall on a
different slope, depending upon how the scales are configured. If the scales are the same, the
slope of the line determines the relationship between the points. If the scales are not the same,
the slope is insignificant.
98
Draw an XYPlot
Draw an XYPlot
1. In Build mode, choose Draw > XYPlot,
-or-
On the Drawing toolbar, click the XYPlot button .
2. Drag a rectangle on the display to create the boundaries.
3. Release the mouse button.
The Define XYPlot dialog opens with the General tab open. Use the tabs to:
• General Tab (page 100)—Select tags to be plotted.
• Display Format Tab (page 104)—Choose what to show in the Legend and on the
Display.
• Plot Format Tab (page 105)—Select how to color and style the plot elements, such
as trace pens and background.
4. Click OK. The XYPlot appears.
To revise an existing XYPlot, select Build mode and double-click the XYPlot. The Define
XYPlot dialog appears. Make your changes and click OK.
General Tab
100
Draw an XYPlot
Server—Enter or select a PI Server name. This field is only used when a PI Tag name is
typed directly into the list.
Note: PI ProcessBook allows you to create custom placeholders for a symbol based on
a summary Data Set. Placeholders are not allowed for expression Data Sets. The
Custom Placeholders button in symbol definition dialog boxes allows you to
specify different PI Tags for a PI Summary Data Set. The change applies only to
the configured symbol. See Add or Edit Placeholders (page 163) for details.
Configure Pairings
Once the tags are listed in the Tags in Plot list, configure the method for pairing values
between X and Y in the Data Retrieval Methods box.
X Tag—choose either Recorded or Interpolated for the retrieval method.
• Interpolated—an interval may be entered in the Plot Time section. Interpolated is
the default for tags and is disabled for ODBC and Custom data sets. This method
retrieves interpolated values for the specified time range in regular intervals. For
example, if the time range is *-1h to * and the Interval is 10m, then six values spaced
10 minutes apart are returned.
• Recorded—Retrieves archive values between the specified start and end time.
Y Tag(s)—the Y tag data retrieval method applies to individually selected tags in the
Tags in Plot list (unless the Use for all Y tags check box is selected). The default data
retrieval method for Y tags is Synchronize.
Y Tags, paired by position in the list—To use multiple time ranges, select Recorded or
Interpolated. In this case, data is paired by position in the point list. If Interpolated is
selected for the X tag as well, the interval value for the Y tag defaults to the one for the X
tag.
When Recorded is the retrieval mechanism, the results are not skewed by minor
timestamp differences.
Y Tags, paired by timestamps—to pair values by time, rather than by list position,
choose one of these retrieval methods: Synchronize, Match, Match or Previous, or
Match or Next.
• Synchronize—synchronizes data found for X with data for Y using the timestamps
for the X data.
• Match—find the point for Y corresponding to the exact timestamp as X.
• Match or Previous—find the point for Y corresponding to the exact timestamp as X.
If there is none, find the value that is the closest but earlier in time.
• Match or Next—find the point for Y corresponding to the exact timestamp as X. If
there is none, find the value that is the closest, but later in time.
Synchronize and Match—use different PI SDK value retrieval methods. Synchronize
uses TimedValues. Match uses RecordedValues and then uses the values where the
timestamps match.
TimedValues—Match uses RecordedValues and then uses the values where the
timestamps match.
If you select Synchronize or any of the Match options, the start and end times for that
tag are set the same as for the X tag and cannot be changed.
Note: The XYPlot supports ODBC data sets that don't contain timestamps. This type
of entry must be plotted as a Y-tag, and data values must be retrieved using
the Recorded retrieval method. If a tag is changed from a Y tag to an X tag
and has a value for Retrieval Method that is only valid for Y tags, the method
is changed to Interpolated. If the tag is a data set, the method is changed to
Recorded.
In all cases, if a pair is not made, the unmatched Y points are ignored.
Use for all Y tags—Selecting this box indicates that the Y-tags data retrieval mechanism
applies for all Y-tags. If one of the tags is a Custom or ODBC data set and the selection
mechanism is Interpolated or Synchronize, the selection mechanism will be Recorded
or Match respectively for that tag only.
Scale Box
In the Scale Box, set the scale ranges for all tags.
Single Y Scale—combines all tag values onto one scale.
Multiple Y Scales—provides a separate scale for each tag. This choice does not change
the scale min and max values, but allows them to be configured independently by
selecting each Y tag and making changes.
Regardless of your selection, you may independently configure the X scale tag.
Max—Autorange uses the maximum value plotted. You may enter an absolute value here
as well. Default is Autorange. Database uses the zero plus span value of the tag in the PI
Archive to determine the max. Database with a data set plot uses the maximum value
plotted.
Min—Autorange uses the minimum value plotted. You may enter an absolute value here
as well. Default is Autorange. Database uses the zero value of the tag in the PI Archive to
determine the min. Database with a data set plot uses the minimum value plotted.
Format—Selects the number format of the Y scale, legend entries, cursor values, and
ToolTip values.
Plot Time
You can set the time for each tag as it is highlighted in the Tags in Plot box. If a Y tag is
selected and its selection mechanism is not Recorded or Interpolated, then these boxes are
disabled.
Start—The start time of the XYPlot. The list includes *-1h (minus one hour), *-4h, *-8h,
*-1d, *-7d. The default is *-8h.
End—The end time of the XYPlot. The list includes *, *-1h, *-4h, *-8h, *-1d, *-7d.
The default is * (current time).
102
Draw an XYPlot
Legend
Choose the legend elements that appear in the XYPlot.
Tag Name—Lists the entries in Tags in Plot. Selected by default.
Srvr Name—Select this check box to prepend the tag name with the server name. Cleared by
default.
Description—The tag description may be displayed on the legend. Selected by default.
Value—The last value of the tag plotted may be displayed. For digital and string tags, a
string value is shown. Selected by default.
Engineering Units—Selected by default. If the tag does not report units, they are not shown
on the legend for that tag.
Correlation Coefficient—A check indicates that the correlation coefficient should be
calculated and displayed on the legend. Selected by default.
Display
Select the optional elements to be included in the XYPlot.
Plot Title—Selected by default.
104
Draw an XYPlot
Vertical Scale Inside Axis—Check this box to show the vertical scale to the right of the
Vertical Axis, inside the plot area. Selected by default.
Grids—Check this box to include vertical and horizontal grid lines. Selected by default. On
the Plot Format Page, you can configure the appearance of the major and minor grid lines.
Linear Correlation Line—Check this to show a linear regression line. The default is
cleared, which does not draw a line.
Connecting Lines—Check this box to show the paired points connected with straight lines in
the order they are plotted. Selected by default. Clear the box to configure a scatter plot with
points only, no lines.
Sample
This area displays a sample XYPlot with the options you have selected. When you have
completed the Display Format page, click the tab for the Plot Format page.
In the Plot Format tab of the Define XYPlot dialog, you can select colors and styles for the
various elements of your plot.
Plot Element—drop-down list of the elements you can configure, such as major and
minor gridlines, background colors, text font, etc. Pens correspond to the X-and Y tags
listed in the order in the Tags in Plot box on the General tab.
Element Format—After you select an element in the Plot Element drop-down,
available formatting options appear. A drop-down arrow is grayed out if the option is not
configurable. For example, text has color but no line style options.
• Line Style—Determines the line style for the selected element.
• Line Weight—Determines the line weight for the selected element. If the selected
element does not have a line weight property, this field is disabled.
• Marker Shape—Determines the marker shape for pen elements.
• Color—Determines the color for the selected element. Pen elements apply the color
to the line and marker.
• Last Marker Color—Allows selection of a different color for the last marker for a
pen. If Match Trace is true (selected), this field is disabled. If the selected element
does not have a marker, this field is disabled.
• Next To Last Marker Color—Allows selection of a different color for the second-
to-last marker for a pen. If Match Trace is true (selected), this field is disabled. If the
selected element does not have a marker, this field is disabled.
• Match Trace—Determines whether all marker colors match the trace color (true) for
a pen. If set to false, the Last Marker Color and Next To Last Marker Color fields
are enabled so the marker color can be changed for those two plotted points. By
default, this field is selected (true). If the selected element does not have a marker,
this field is disabled.
Sample—Provides a preview of your formatting changes.
Ad-hoc XYPlots
You can draw an XYPlot in Run mode on an ad hoc basis. Click the XYPlot button to
begin, and follow the steps described in Drawing an XYPlot (page 99).
XYPlot Statistics
The XYPlot Statistics dialog [deprecated] allows you to view and export raw data values and
statistics, such as the mean and standard deviation of each tag’s data.
You can also view these statistics in the Details Window (page 135).
To open the XYPlot Statistics dialog:
1. In Run Mode, double-click the XYPlot symbol. Your cursor turns into a pointer.
2. Use the pointer to double-click an XYPlot on your display. The Statistics dialog appears.
3. In the Options drop-down list, select Raw Data or Statistics.
106
Draw an XYPlot
108
Linear Regression by Least Squares
Where m is the slope and b is the offset. To calculate m, we use the following equation:
Once m and b are known, the value of y that intersects the best-fit line can be calculated.
Correlation Coefficient
The Correlation Coefficient (r) varies between -1 and +1. Positive values indicate that as X
increases, Y also increases. Negative values indicate that as X increases, Y decreases. A
value of zero indicates no correlation in the way the sets of values vary.
The Correlation Coefficient for a set of points is calculated using the following formula: (n is
the number of points, s is the standard deviation). You can display the correlation coefficient
in the plot legend.
Interpreting an XYPlot
In PI ProcessBook the XYPlot is a dynamic symbol. It has specialized characteristics, such as
its statistical calculations, which are described in the following paragraphs.
Point Properties
Data may be retrieved from PI or from independent data sets. Use the Tag Properties button
or the right mouse menu Properties item to determine the attributes of the points in your
XYPlot .
Scroll Feature
Scrolling is available from the ProcessBook toolbar. When time scrolling is used on an
XYPlot symbol, all tags’ time ranges are changed to support the scroll duration.
Plot Values
In a typical XYPlot, the current value for X appears below the plot. The current values for the
two different Y tags appear at the upper right. Below each one is the correlation coefficient
for that XY pair. The dots and lines on the plot are colored to match the tags.
Plot values appear in a small box over the plot when the mouse cursor is hovering over an
actual plotted point pair. The following illustration shows an example.
In the figure above, if there had been more than one Y tag, each one would be displayed on a
different line. The X tag information is placed at the bottom. For digital or string tags, the text
value is displayed in the tool tip.
You can also view plot values by double-clicking the title bar and choosing the Raw Data
option, rather than the Statistics option.
Zoom/Revert Functions
You can enlarge a portion of an XYPlot by using the Zoom feature.
110
Zoom/Revert Functions
1. Place the mouse cursor on the upper left corner of the area to be zoomed.
2. Hold the left mouse button down while dragging a rectangle to cover the appropriate
area. When you release the mouse, this area is enlarged to the borders of the original plot.
Original plot
Note: The zoom area must be smaller than the plot area and cannot include the
outer 20 percent of the plot. If the mouse is dragged past the plot boundary,
the zoom rectangle stops at the border until the mouse reappears within the
boundary. If the mouse is dragged off the plot symbol boundary, the zoom is
canceled.
Revert
1. Click Undo to return the plot to its state directly before the zoom occurred.
2. Click the Revert button to return the plot to its configured appearance.
On the Time Range toolbar, click the Change Time Range button .
The Change Time Range dialog opens.
2. Enter new values in the Time Span box.
All tags are affected when you change the range in this dialog box.
3. Click the Revert (page 13) button on the Time Range tool bar to return the plot to
its configured appearance.
XYPlot Cursors
The cursor for an XYPlot includes both a horizontal and a vertical line. The mouse cursor is
at the cross point of both cursor lines. You must be in Run mode to use the XYPlot cursor.
To create a cursor, place the mouse very close to either the X- or Y-axis. Drag the cursor onto
the plot.
In the XYPlot below, you can see an XYPlot cursor at the Y axis that is not yet intersecting
any points on the plot.
112
Bad Status Indicators
You can also see an XYPlot cursor that was dropped on a point. The X and Y values appear
in small boxes outside the axes.
Using the mouse, you may position and release the cursor over any point on the XYPlot. If
the cursor is dropped on an area that contains no points, the cursor snaps to the nearest point.
Once you have dropped an XYCursor on a point, use the arrow keys to move from point to
point in time order. For example, pressing the right arrow key moves the cursor to the point
that is plotted immediately after the current point in the same series. The left arrow moves the
cursor to the point that is plotted immediately before the current point in the same series. The
up arrow moves the cursor to the first point in the previous series. The down arrow moves the
cursor to the first point in the next series. The cursor looks the same when it is dropped.
The information on the XYCursor point pair is shown in a box on each axis. If the tags are
digital or string, the text value is shown in the box rather than a numeric value. Placing the
mouse cursor over one of the cursor boxes shows the time of the point.
Examples of XYPlots
For these examples, the X-axis represents one of the values in the pair and the Y-axis
represents the other. The configuration of these axes regarding minimum and maximum
values and interval (or unit) settings is left to you.
1. On the Drawing toolbar, click the XYPlot button and drag to form the bounding
rectangle for the plot. The Define XYPlot dialog appears.
2. Enter a title for the plot and select 2 tags to be entered in the Tags in Plot list.
3. Click an option button to select one tag to be the X tag.
4. Use the default settings for time range, scale, and retrieval method.
5. Click the Display Format tab and check the box for the regression line.
6. Select the Plot Format tab and accept the default values.
7. Click OK and the plot appears.
For example, suppose an engineer has just completed some optimization work on Boiler1,
one of the four boilers in the plant. He wants to optimize the other three boilers (Boiler2,
Boiler3, and Boiler4) so that they perform at the same level. After adjusting the three boilers,
he wants to see how closely they perform to the optimized Boiler1.
114
Examples of XYPlots
An engineer wants to compare lab results from his lab to those of another lab for the same
sample of material.
The plant's quality assurance lab has instituted some new testing procedures. In order to
gauge the validity of the new testing procedures, an engineer wants to compare results from
the new process against data from an outside lab that is known to have valid testing
procedures.
1. Put the results from the in-house lab into a data set.
2. Place the results for the same test from the other lab into another data set.
3. Selects each data set as a tag in the plot, and select which one to be the X-axis.
4. Choose Recorded as the retrieval mechanism for each data set so that the results are not
skewed by minor timestamp differences.
If the XYPlot shows the results from the new process are well correlated with the outside
lab's data, the new test procedure is validated.
An engineer wants to compare sample measurements taken from one Batch run and compare
them to a fixed set of measurements he knows to be desirable.
1. Select the fixed set of measurements by choosing the appropriate tag or data set and
indicating it is to be used for the X-axis.
2. Select the appropriate tags for the comparison batches, entering their specific time ranges.
3. Use Recorded values for all retrieval mechanisms.
The data points are paired according to their position in the events list. The XYPlot shows
how closely the results correlated by how closely the points fall on a linear regression line.
Points that fall outside this line may indicate problems with the batch run.
An engineer wants to compare the performance of a Boiler unit over two time ranges. He
needs to determine whether a boiler's performance has degraded over time or whether there
are specific problems with the equipment. To do this, he creates an XYPlot that compares the
temperature tag data from two different time ranges.
1. Enter the tag twice and assign one instance as the X tag.
2. Enter separate time ranges for each tag. Values are paired by their position in the list.
If the points fall close to a linear regression line, you can assume the boiler's performance is
at least steady. If some points are far from the line, it may indicate that the equipment has a
specific problem.
116
Chapter 7
Additional Symbols
Dynamic Symbols
Values
A Value is the reading obtained at a particular moment in time for a tag in the PI Archive. A
value is shown as a number or a digital state string. The tag name and time stamp may also be
shown. The time stamp is the time stamp from the PI Archive.
4. In the Server drop-down list, select the PI Server to use. If a tag name is manually
entered in the Tag box, it is expected to be on the selected server. If both server and tag
name are entered in the Tag box, this field is updated with the entered server name. This
field has no effect for non-PI data.
5. In the Tag box, type the name of the tag you want to display in the value box.
-or-
Click the Tag Search button to locate the tag.
-or-
Click the Tag Search arrow to see more search options.
Note: The Sample area shows how the value will look.
6. In the Format drop-down list, select a number for the value, or type your own format
(page 119).
7. In the Tag drop-down list, select the location of the tag name in the value box (None,
Left, Right, Top, or Bottom).
8. In the Time stamp drop-down list, select the location of the time stamp in the value box
(None, Left, Right, Top, or Bottom).
9. Click OK to add the value to the display.
Note: PI ProcessBook allows you to create custom placeholders for a symbol based on
a summary Data Set. Placeholders are not allowed for expression Data Sets. The
Custom Placeholders button in symbol definition dialog boxes allows you to
specify different PI Tags for a PI Summary Data Set. The change applies only to
the configured symbol. See Add or Edit Placeholders (page 163) for details.
118
Dynamic Symbols
The following table describes how to create a custom number format mask.
Symbol Explanation
# Placeholder for a digit. Leading and decimal zeros
are not displayed
0 Placeholder for a digit. Leading and decimal zeros
are displayed.
Button
Add a Button
1. In Build mode, open a display.
Note: The name should be no more than one or two words, and should describe the
action the button performs when clicked.
Note: If you know the file or macro name, then you can type this directly in the
Action box.
Note: The Working folder box allows you to specify the working folder for operating
system commands. It is ignored if the Action refers to a document type
supported by ProcessBook. If you know the name of the working folder for this
application, then you can type this directly in the Working folder box.
120
Dynamic Symbols
Note: By default, ProcessBook attempts to open a linked display from its relative
path first. If the relative path fails, then the absolute path is attempted.
Clearing this box reverses the order in which the paths are resolved. For new
displays, this option is checked by default.
• Ignore the default shell command for recognized file types (for example, SVG).
Note: If the file type is supported by ProcessBook (either natively or through an add-
in), then it is opened directly. For example, an .svg file is opened using the
.svg File Converter in ProcessBook, even if you have Adobe SVG Viewer
installed. Clearing this check box disables this behavior, so the default shell
command is always used to open a file.
Bars
A Bar shows the current value of a tag as compared to a specified range of values.
For example, a bar may be used to create the effect of a vessel filling and emptying, as the
value changes.
The range of values can be the maximum and minimum values specified in the point
attributes, or, a bar can be designed to show a specific range of values.
For example, if a tag’s specified value is between 0 and 100 but it typically falls between 0
and 30, a bar can designed to show that range. However, if the value is outside the range of
the bar, the bar will appear the same as a value right at one of the limits of the bar.
The start of the bar may be within the limits of the bar. This lets you display deviations from
a standard or target value. Bad values are shown with hash marks across the entire bar.
You can draw a bar using the current line style, line color, and fill attributes.
1. In Build mode, open a display.
4. In the Server drop-down list, select the server to use for manually entered tags. If the
server and tag name are both entered in the Tag box, this field is updated to show the new
server name. This field is ignored for non-PI data.
5. In the Tag box, type the name of the tag you want to display on the bar.
-or-
Click the Tag Search button to locate the tag.
-or-
Click the Tag Search arrow to see more search options.
122
Dynamic Symbols
6. From the Upper and Lower drop-down lists, select the maximum and minimum values
you want to use for the bar. Select a constant, or choose Tag Zero() or
TagZero()+TagSpan() for either or both values.
Note: If you choose a maximum value that is too small, the bar will be fully colored
but there will be no warning that it has exceeded the maximum.
7. From the Start drop-down list, select the point on the bar from which you want to start
drawing the bar. Select a constant, or select TagZero()+TagSpan() or Tag Zero().
8. Under Orientation, select one of the options to display the bar either vertically or
horizontally.
Note: The Sample area shows how the bar will look.
Note: PI ProcessBook allows you to create custom placeholders for a symbol based on
a summary Data Set. Placeholders are not allowed for expression Data Sets. The
Custom Placeholders button in symbol definition dialog boxes allows you to
specify different PI Tags for a PI Summary Data Set. The change applies only to
the configured symbol. See Add or Edit Placeholders (page 163) for details.
Multi-State Symbols
A Multi-State symbol changes color to reflect changes in value for a particular tag or data set
value. Any symbol except a trend, XYPlot, graphic, button, or OLE object can be made a
Multi-State symbol by assigning a tag to it. String and timestamp data cannot be used to
configure multi-state behavior.
You determine the number of value ranges, and the colors assigned to each range. As the
value of the tag changes, the Multi-State symbol changes color to reflect the current value.
You can make a symbol seem to disappear by setting a state color to the background color or
to a color of none. For alarms or other purposes, you can set a state color to blink.
For example, you may have a symbol showing two states. State 1 has a value range from 0 to
50 and a color of blue assigned to it. State 2 may have a range from 50 to 100 and have red
assigned to it. When the reading is 50 or below, the symbol appears blue. Above 50, the
symbol appears red. A color and sometimes a blinking attribute are assigned for bad data. For
digital point types, a different color may be assigned to each state.
2. Click the symbol that you want to use for creating a Multi-State symbol.
4. In the Server drop-down list, select the server to use for entered tags. If a server and tag
are both entered in the Tag box, this field is updated with the new server name. This box
does not apply to non-PI data.
5. In the Tag box, type the name of the tag you want to assign.
-or-
Click the Tag Search button to locate the tag.
-or-
Click the Tag Search arrow to see more search options.
6. In the Number of States box, select the number of states to usel. If the number of states
is not entered, the number defaults to 2. (For digital tags, the number of states is
automatically set to the number of defined states for that tag.)
7. From the Color for Bad Data drop-down color palette, select a color that will be used
when the information is in bad status. You may also select the Blink check box to call
attention to the symbol when data is bad (optional).
8. In the State box, select 1.
9. In the Values box, type in a new value.
Note: The Values boxes display a range of values for each state. The total range of
the tag is automatically divided by the number of states. For digital tags, the
state name is displayed in these boxes. For other tag types, an estimate is
made based on the span of values for the tag.
124
Static Symbols
10. From the Color drop-down color palette, select a color that will be used for the state. You
may also select the Blink check box (optional).
11. Repeat Steps 9 and 10 for each state in the symbol. Your choices and the relative range of
values are displayed on the bar at the bottom of the dialog box.
12. Click OK.
Note: You can remove a Multi-State symbol definition by clicking the Convert to Static
button, which breaks the link between the symbol and the tag.
Note: PI ProcessBook allows you to create custom placeholders for a symbol based on
a summary Data Set. Placeholders are not allowed for expression Data Sets. The
Custom Placeholders button in symbol definition dialog boxes allows you to
specify different PI Tags for a PI Summary Data Set. The change applies only to
the configured symbol. See Add or Edit Placeholders (page 163) for details.
Static Symbols
Text Symbol
The text symbol allows you to put one line of text on a display. Multiple lines of text are not
supported. When this symbol is first added to the display, a text box with a blinking text
cursor is displayed.
You can add or edit text by double-clicking the Text symbol while in Build mode, which
provides the text cursor. Unlike most other ProcessBook symbols, this symbol is not sized by
dragging an area on the display. Instead, the symbol is sized to accommodate the text within.
When text is added, the symbol grows in size and when text is removed the symbol size
shrinks. The size of the font used also affects the size of the symbol.
You can format the text symbol for font and color. Text symbols have all the functionality of
other static symbols except rotating and flipping.
Note: Text block refers to the text area associated with a shape that appears when
you click the shape with the text tool or select it with the pointer tool.
5. When you finish typing, press ESC or click outside the text block.
Line Symbol
Lines within a drawing can be diagonal, horizontal, or vertical. Attributes you can change
include line color and whether a line is dotted or dashed, thick or thin, and with or without
arrowheads.
Draw a Line
1. In Build mode, open a display.
126
Static Symbols
Using the drawing tools, you can create these simple shapes:
Rectangle, Square
Arc
Ellipse, Circle
2. On the Drawing toolbar, click the Rectangle , Arc ,or Ellipse button , or
Click the appropriate tool.
The mouse pointer changes to a tool pointer. The appearance of the pointer indicates the
type of tool you have chosen.
3. Click the display to place the upper left corner of the shape, and drag down and to the
right to create a shape of the desired size.
Press SHIFT while drawing to constrain the object to a square, circle, or circular arc.
4. Release the mouse button to complete a Rectangle, Square, Ellipse, or Circle.
-or-
5. If you used the arc tool, one quarter of the shape is drawn. Click on it and resize it to the
desired shape. Click and drag the end of the arc to change the angle.
Press SHIFT to change the angle in 15-degree increments. When the arc is first drawn,
the handle for reshaping the angle is just inside the resize handle.
Example of an arc
Polygon Symbol
The Polygon tool draws irregular shapes. When you select the polygon tool the mouse pointer
changes to a polygon pointer. Polygons are drawn using the current color and line style
attributes.
Draw a Polygon
1. In Build mode, open a display.
Example of a Polygon
128
Static Symbols
Polyline Symbol
A Polyline is a set of line segments that you can draw using the Polyline tool. It uses the
current line style attributes.
Once you add a Polyline symbol, you may edit it in the same manner as the existing Polygon
symbol. You can move or resize the entire symbol, as well as move the individual endpoints
to create any desired arrangement.
Draw a Polyline
1. In Build mode, open a display.
Note: Press the Shift key while you draw to create Right Angle Polylines.
Similarly, pressing Shift during editing manipulates a point orthogonally in relation to the
next endpoint.
Graphic Symbol
Note: A drawing is display resolution dependent, which means it may look different from
one monitor to another. Test the drawing on each monitor to see how it will look.
Add a Graphic
1. In Build mode, open a display.
130
Static Symbols
Note: Stretching the image to fit the bounding rectangle may distort the appearance
of the graphic.
7. Click OK.
8. A copy of the graphic is added to the display.
Symbol Library
A large selection of symbols is available in the Symbol Library. Many of these have
characteristics such as color, fill type, orientation, or background, which you can modify.
On the installation CD, OSIsoft provides several other commonly used symbols in the
ProcessBook called SYMLIBRY.PIW. This is usually installed in C:\Program
Files\ProcessBook\ProgramFiles\pipc\Procbook\SYMLIBRY.PIW. You
can cut and paste these symbols into a display.
132
Static Symbols
Note: You can also change the symbol's fill and background color directly on a trend
2. Click the Defaults button if you want to revert to the default settings.
3. Click OK to accept the changes and return to the Symbol Library (page 132) dialog.
Symbol Properties
If you right-click a symbol in the Symbol Library, the focus box at the upper left reflects that
symbol. A small dialog appears; you can choose either Symbol Options or Properties.
If you choose Properties, you see a Symbol Properties dialog, which displays the Symbol
description, Data size, Type, and Handle information. This information could be used in VBA
automation of PI ProcessBook.
134
Chapter 8
Details Window
Beginning in version 3.1, a Details docking window is available to show data from dynamic
symbols. The window is only available in Run mode and initially appears along the right side
of your ProcessBook window, however, you can click and drag it anywhere.
The Details window is driven by selections in your display. Moving a plot cursor changes the
rows highlighted to show the range of data.
By default, the window remains open when a different display symbol is selected. The
Details window is cleared when you switch to Build mode. If you open the Details window
while in Build mode, the controls are all disabled.
Data Source—This field allows you to choose a data source, including datasets and PI
Tags(by default, the first trace or main data source for the selected symbol is shown). The
Show All entry shows data for all the data sources in the selected symbol.
Note: If a dataset or XY Plot symbol returns more than 3,500 values the Show All option
is not available. In addition, only the first 3,500 values are displayed. This value
can be increased by adding the registry key HKCU\Software\PISystem\PI -
ProcessBook\DetailsAddin\MaxPoints (type DWORD) and setting it to
the maximum number of points desired.
Option—This field allows you to toggle between three different types of information about
your data source.
• Data—shows all rows for a selected symbol's time range. By default the table is
sorted on the timestamp column in descending order. Click a heading to resort the
table on a different column.
• Statistics—shows a table of available summary values available, for example,
Average, Minimum, Maximum. Selecting this option disables the PI Annotation
Maintenance window. Available statistics vary for each symbol type.
• Point Attributes—shows an alphabetized list of PI point attribute values.
Each view option provides the following controls:
<Symbol Name>—The name of the symbol selected on the display is shown above the data
table.
Refresh —Refresh data in all tables. Data shown does not automatically change after a
symbol is first selected. You must use refresh to view any updates in the Details window.
Enlarge/Shrink Font —Makes the text size bigger or smaller. This may reduce the
number of visible rows.
Copy to Clipboard —Allows you to copy the data table to your clipboard. You can then
paste this data into another location such as a Microsoft Excel spreadsheet.
136
Details and Annotations
PI Annotations Maintenance
Annotations allow you to associate related information (such as text comments and other
binary data) with any archive value. The PI Annotation Maintenance group at the bottom of
the Details window (page 135) allows you to easily annotate values on your dynamic
symbols.
The PI Annotation Maintenance group is located at the bottom of the Details window and is
enabled so that annotations can be added, edited or viewed, provided that:
The selected data source is a PI Tag
The target PI Server can read and write annotations
A row representing an event is selected in the Data table
If the target PI Server (or collective) is unavailable or cannot accept edits from the current
user, the control is disabled. If the PI Server becomes unavailable while you are entering an
annotation and you then click the Save button, you will receive an error.
Note: If you select Show All from the Data Source drop-down box on the Details (page
135) window, the Value and Value Type fields in the PI Annotation Maintenance
group are disabled.
Add Annotations
1. Open the Details (page 135) window
2. In Run mode, select a dynamic symbol on your display.
3. Click inside the Value text box and enter the information you wish displayed in your
annotation.
4. Select a value from the Value Type drop-down box.
5. Click the Save button at the top of the PI Annotations Maintenance group. An
annotation icon appears on the dynamic symbol. Hover over this icon to read your
annotation. A record of the annotation also appears on the Details window when the
Data option is selected.
Note: You need to be running a PI Server 3.4 or higher for annotations to work correctly.
Otherwise, it is possible that an annotated event will not only be marked as
annotated, but will also be marked as substituted.
You can use the pin icon to lock the Details window on your screen. Click the pin icon
again to unpin the window and minimize it along the border of your PI ProcessBook window.
When the Details window is unpinned, a Details button appears along the side of the screen.
Hover over the Details button to expand the Details window.
138
Rotate a Symbol
• To select symbols that are stacked on top of each other, click the top symbol.
Selection handles appear. Continue clicking the top symbol to select symbols located
under the top symbol.
3. Click the symbols you want to change or move. The selected symbols display handles.
Rotate a Symbol
You can rotate a drawing symbol in 15° or 1° increments. You cannot rotate text, graphics, or
OLE objects. Symbol Library images can only be rotated in 90° increments.
1. Select the symbol you want to rotate.
2. Choose Arrange > Rotate. A rotation object appears in the center of the symbol.
3. Click a selection handle and drag in the direction that you want to rotate the symbol. The
symbol is rotated in 1° increments.
-or-
Press SHIFT while dragging to rotate in 15° increments.
Flip a Symbol
You can create a mirror image of a symbol by flipping it. You cannot flip text, graphics, or
OLE objects.
1. Select the symbol you want to flip.
2. Choose Arrange > Flip > Horizontal to flip the symbol from right to left or Vertical to
flip the symbol from top to bottom.
Delete a Symbol
When you want to delete a drawing symbol or group of symbols:
Stacking Order
Each symbol you add to a drawing occupies its own space in the drawing. The layers, and
therefore the symbols, are stacked on top of each other. By default, the first symbol you draw
is at the bottom of the stacking order and the last symbol you draw is at the top of the
stacking order.
Using the stacking commands, you can move a symbol forward or backward within the stack
(page 140). Depending on the number of objects between top and bottom, you may need to
repeat a stacking command several times to move the symbol to the desired location within
the stack.
140
Align Multiple Symbols
3. Click the alignment options you want. All the selected symbols are aligned to the symbol
you first selected, along the axis you specify.
Connect Symbols
Connector Symbol
You can connect two symbols to each other using the Connector symbol. The Connector
symbol remains attached to each of the connected symbols whenever one or both are moved.
The advantage of using a Connector, rather than a line, is that the Connector remains attached
to other symbols when you move the other symbols and avoids overlapping other symbols.
The Connector is intended for modeling and automation purposes.
Connection Points on each symbol define where the connection occurs. Connection Points
can be added, deleted, or moved on a symbol.
Connectors try to avoid objects as they are being connected between two symbols.
The Connector symbol is supported by automation within PI ProcessBook.
142
Connect Symbols
2. Click on the first symbol, called the "Source," and drag the mouse into the second
symbol, called the "Destination." The Connector arrow has a flow direction from the
Source to the Destination. Connection Points appear on both symbols.
Note: If your mouse does not touch a symbol, you do not see a Connection Point. Do not
adjust the Connector manually. If you do not see Connection Points on both
symbols, delete the Connector and draw it again.
Note: To remove an attached symbol from a connector, click the symbol and drag it
away from the connector.
Connection Points
Connection points on each symbol define where a Connector may connect. Connection Points
are visible in Build mode only and appear on symbols as small x marks. When you select one
with your cursor, it changes to an x within a bounding circle.
ProcessBook symbols are originally built without Connection Points. A Connection Point is
created automatically when a Connector is dragged into a symbol. This Point is created at the
midpoint of the nearest edge of the bounding rectangle of the symbol. The end of the
Connector is moved to the Connection Point. You may add Connection Points and move
them to specific locations.
A Connection Point can be used for either the start of the flow or the end of a flow. The same
Connection Point can be used for both. A flow can be bi-directional.
If a second Connector is dragged over a symbol, it either moves to the existing Connection
Point or creates a new one.
For irregular figures, Connection Points are placed near the midpoint of the side of the
bounding rectangle of the figure, as shown in the illustration below, rather than inside the
figure itself. You can adjust the position of the Connection Point to touch the actual figure.
Note: If a symbol is placed in front of another, the Connection Points on the ‘hidden’
symbol cannot be selected. You can solve this problem by placing the two
symbols on different layers of the display.
144
Connect Symbols
In other words, Connection Points have identifying names that are derived from the symbol
name. For example, for a rectangle named Rectangle2, two Connection Points would be
named <Rectangle3 : 1> and <Rectangle 3 : 2>.
If you are using a symbol from the Symbol Library, the Connection Point is named
<TBSymbolx : n>, where TBSymbolx represents the specific name of the symbol.
Connectors Dialog
In Build mode, if you wish to adjust a Connector's end point, you might click and drag the
end point. Unfortunately, this action stops the auto-avoidance capability of the Connector.
Alternatively, you can use the Connectors dialog to rearrange connections. To reach this
dialog:
Click the Connectors toolbar button,
-or-
Choose Edit > Connectivity,
-or-
On the right-click menu, click Connectivity.
The Connectors dialog affects Connector symbols only. It cannot be used to attach one
symbol to another symbol without a Connector. The Connectors dialog has two tabs, Flow
and Attachments. Each Connector is identified by a unique number, which is revealed by a
tooltip in your display.
Note: Use the tooltip on the display to identify the Connector(s) and Connection Point(s)
you wish to rearrange before you open the Connectors dialog.
The Auto Avoid option is checked as a default, so that Connectors route around other objects
in the display.
146
Connect Symbols
Connector Attachments on the Display Properties dialog, discussed above, you can still
attach symbols to Connectors by using this dialog.
148
Connect Symbols
Sometimes it is desirable to attach a symbol, such as a flow meter or a text label, along a
Connector so that the symbol moves as the Connector does. This subordinate symbol is called
a symbol attachment. Note that this is different from connecting a symbol to either end of a
Connector.
To attach a symbol to a Connector, follow these steps:
1. Choose Edit > Display to open the Display Properties dialog.
2. Be sure the Enable Connector Attachments option is checked. Click OK.
3. Create the subordinate symbol and drag and drop it across the Connector. The
subordinate attachment is attached to the Connector. The placement is snapped either
left/right or top/bottom depending upon the orthogonal direction of the connector at the
position where the attachment has been placed.
4. To attach symbols to Connectors, select the Connector, then choose Edit > Symbol
Attachments.
You may want to attach two or more symbols (not Connector Symbols) so that they move
together but do not become a Composite Symbol. For example, you might attach a text label
symbol to a pump symbol. The text symbol is subordinate to the pump symbol and follows
the pump symbol if the latter is moved.
The advantage of this method of attachment is that each symbol in the group retains its
identity and can be acted on individually for automation purposes.
1. Select at least two symbols. This enables the Symbol Attachments icon .
2. Click the Symbol Attachments icon, or
Choose Edit > Symbol Attachments, or
On the right-click menu, click Symbol Attachments.
The Symbol Attachments dialog appears. The symbols you selected appear in the
Attachments dialog as possible master or subordinate symbols.
3. Select the Master Symbol. As you change the Master, the title of the dialog changes
also.
4. Place a check mark for the subordinate symbol or symbols and click OK.
5. Repeat the process for each Master symbol. The Detach All bar at the top can be used to
remove all attachments from the currently selected symbol in the Master box. To detach
only one attachment, clear its check box.
6. Click OK. When you move a Master symbol, any subordinates move with it.
Note: There are two other routes to the Symbol Attachments dialog. Choose Edit >
Symbol Attachments, or, on the right-click menu, click Symbol Attachments.
You can easily detect which symbols in your display are attached and/or connected to
Connectors, or which symbols are attached to symbols. To see whether Connectors or
attached symbols exist for a particular symbol:
Click the symbol or connector and hold down the mouse button for more than one half
second.
150
Item Definition
• If there are existing Connectors, all Connectors with attached symbols for this
symbol are spotlighted and display in a different color (for example, white for black
or yellow for blue).
• If there are no Connectors, nothing happens.
When you move a symbol, its Connectors shift automatically to stay connected to the moved
symbol and avoid overlapping other symbols in the display. Connectors can overlap each
other.
If a drawing becomes complex, you can request that all Connectors be rerouted by clicking
the Reroute button. If you select specific Connectors and click Reroute, only those
Connectors are rerouted. Connectors crossing each other may be unavoidable but should be
minimized. Do not move Connectors manually.
The object avoidance feature in PI ProcessBook can either ignore or take Connectors into
account when looking for the shortest path from the source to a destination. This behavior is
controlled by the ConnectorsAvoidConnectors setting in the ProcBook.ini (page
196).
Note: Object avoidance does not occur after you drag and drop a Connector’s line
segment. If you modify the position of a Connector manually, the center point and
end points on the Connector change from green to red, indicating that automatic
object avoidance is turned off and you are responsible for all further updates to
that Connector.
Rerouting can consume significant system resources (CPU and Memory) to solve complex
problems. Factors that can increase complexity include:
A very large display
Large numbers of Connectors on a single display
Large numbers of symbols to be avoided
A high number of "Lines per Screen Unit" (set in "Arrange", "Grid Size…", "Lines per
Screen Unit"—1 equals the largest cell size; 30 gives the smallest cell size)
Routing multiple displays on the same PC
Item Definition
Use the Item Definition button in either Build or Run mode when you want to see what tags
and formatting options were used in any symbol that uses a dialog box for basic
configuration. It is the same as double-clicking on the item with the Build mode pointer. If
the symbol does not have a definition dialog box, the button is dimmed. You can change the
selections and save the new definition. This button does not open any of the formatting
dialogs (for example, Font or Color).
Note: If the Item Definition button appears dimmed the symbol you selected may
not have a definition dialog box.
3. In the appropriate dialog box, make your changes to the item's definition, and then click
OK. These changes are saved with the symbol. These changes are saved with the symbol.
or
The Status Report dialog appears when you have a display in focus and double-click the
Status icon. This report lists all the symbols in a display that have data associated with them.
You see the tag to which the symbol is connected and, if there is an issue, the error message
appears. You can sort the list by any of the column headings.
152
Status Flags for Unusual Data
For troubleshooting purposes, the Message Log button shows you the SDK Log file.
You can save this report as a .csv file by using the Save to File button.
Note: The Status Bar can be displayed or hidden from the View Status Bar item on the
View menu.
Questionable—indicates that there is some reason to doubt the accuracy of the value.
Substituted—used to indicate that the value has been changed from its original value.
This value is set only by the PI Server when an existing value is changed.
If a tag has more than one flag, the highest priority status will be shown. The priority from
high to low is: Error, Questionable, Annotated, Substituted.
If you clear the Show Value Attributes check box in your Start Preferences, you will not see
these icons. You might disable the icons to improve ProcessBook performance if you have
very high speed sub-second data.
154
Chapter 9
Data Sets
In PI ProcessBook you can build dynamic symbols using data retrieved from data sets just as
you can from specific points in the PI Data Archive.
A data set is basically the set of results of a query that addresses a specific data source. You
can use placeholders to link PI tags and ODBC data within a query.
Data sets are defined at the Book level so that they can be defined once and then shared
among different displays within that ProcessBook. Trends including data sets can be
manipulated, saved, moved, and copied in the same fashion as other trends.
Whenever a display is updated, if a trace or value using a data set is configured using relative
times, then the trace or value is updated. No updates occur if the data set is configured using
absolute times. For independent displays, the data set definition is saved with the display file.
You can edit an existing data set, either from the Tools menu or from a symbol that uses the
data set. However, if you have attached the data set to more than one symbol, editing the data
set affects all the symbols. If you move a PI ProcessBook display containing a data set to
another machine, you may need to reconfigure the data set.
include laboratory results, cost tables, or other sets of information that can be obtained
through SQL queries. Since access to ODBC sources is configured on a particular
computer, moving a display file that uses an ODBC data set may require the data source
to be configured on the new computer.
Custom (page 159) data sets built as COM objects supplied by Visual Basic or C++
programs as Add-Ins to PI ProcessBook.
156
PI Calculation Data Sets
1. Choose Tools > Data Sets. The Data Sets (page 155) dialog appears.
Note: You can also create a PI Calculation data set by clicking the dropdown arow
next to the Tag Search button in the Define dynamic symbol dialogs. By
accessing the PI Calculation Data dialog this way, you have the additional
option of selecting a previously created PI Calculation Data set, as well as the
ability to create a new one as outlined below.
The calculated value for each interval is plotted at the start of the interval. For example, if the
tag "t_min" has the following time-value pairs in a 10 minute interval, then the calculated
value for this interval would be plotted at time 1:00:00.
1:00:00 1
1:01:00 2
1:02:00 3
1:03:00 4
1:04:00 5
1:05:00 6
1:06:00 7
158
Custom Data Sets
1:07:00 8
1:08:00 9
1:09:00 10
1:10:00 11
The calculated value for the AVG, STDEV, and PCTGOOD functions includes the tag value
at the lower interval boundary time and excludes the tag value at the upper interval boundary
time. For the example above, the tag value "10" at time 1:09:00 is excluded in the function
calculation, therefore the calculated value for AVG is 4.5 and the calculated value for
STDEV is 2.872281.
The calculated value for the MIN, MAX and RANGE functions includes the tag value of
both the lower and upper interval boundary times. For the example above, the calculated
value for MIN is 1, the calculated value for MAX is 11 and the calculated value for RANGE
is 12.
You can plot additional statistics in a trend using data sets derived from PI tags. For example,
you can plot both a tag and its moving average to show a smoothed version of the same
curve. The moving average is built from the source tag using a data set that recalculates an
average point value over recurring intervals.
To create a moving average in a trend:
1. In Build mode, double-click on the trend to open the Define Trend dialog.
2. Click the Tag Search arrow and choose PI Calculation to create a data set based on a
tag.
3. Click New to add the data set and specify a Name and Description for the data set that
calculates the moving average.
4. Click Tag Search and select the tag you want to use as the basis for the calculation.
5. In the Interval field, choose the calculation period for the average. A new average tag
value is computed at each interval over the plotted time range.
6. Click Average in the Columns panel to select an average calculation, and click OK.
7. Click OK to close the Define Trend dialog.
data could be a data store (like MS SQL Server) or a data calculation engine. PI ProcessBook
will request updates to the data every few seconds and adjust its display accordingly.
Before you can access custom data sets in a display, the Data Set Add-In must be installed
through the Add-In Manager (page 25) dialog. Later, as you build a display, you select the
data set and column to be used for a symbol on a display through the symbol definition
dialogs.
Building a custom data set is beyond the scope of this user guide. It is discussed in Creating a
Custom Data Set, a white paper supplied with the PI ProcessBook software CD and also
available through the OSIsoft Web site.
1. Choose Tools > Data Sets. The Data Sets (page 155) dialog appears.
2. Click the New button, then select ODBC. The ODBC Data dialog appears.
160
ODBC Data Sets
Note: The default for the Refresh Interval list is zero minutes. This means the data
set will only refresh when the trace is first drawn or when you click the Revert
Time Ranges button on the standard toolbar. If a tag placeholder is used, the
Refresh Interval box list is disabled.
6. From the Data Source drop-down list, click the appropriate ODBC data source. If you do
not already have an ODBC Data Source configured on your computer (using the Control
Panel), click the Setup button to create or modify one.
7. Click the Design button.
The Microsoft Query application is displayed.
Note: If Microsoft Query is not installed, then the Design button is disabled. You can
key in the query manually. You can also copy and paste a query from another
query building tool.
Note: Click the Help button, if necessary, and follow Microsoft's instructions for
completing the query.
Placeholders
A Placeholder in an SQL query identifies a value that is to be provided when the query is run.
You can validate a query before the actual values are provided.
The standard SQL placeholder character is “?”. Placeholders are numbered in their order of
appearance, from left to right, in the query statement.
For example, the following query statement has two placeholders, one for a text string for a
sample ID and the other for a sample time.
Select value, sample_time from Lab_data where sample_ID=?
and sample_time>?
PI ProcessBook allows placeholders in queries. You may provide text, start, or end times, or
tag values as substitutes for placeholders.
Text placeholder values are substituted into a query when it is run. Start and End times are
determined when a display is opened and are substituted into queries at execution.
162
Placeholders
In this example, the values of the tag in the PI System that records the current product code
are retrieved. The result set of the ODBC query is built by executing the query once for each
placeholder value. In the case of this example, that would be one query execution for each
product code found between the start and end times.
Placeholders can be customized for a symbol. You can create an ODBC data set with a set of
default placeholders. When that data set is attached to a specific symbol, the query’s
placeholders can be customized for that symbol without affecting the placeholders defined for
any other symbol using that data set.
To open the Placeholders dialog, click the Placeholders button in the ODBC Data Sets
(page 160) dialog, or click the Custom Placeholders button on a symbol definition dialog. In
this dialog box, you can rename placeholders, change their type or specify values.
Note: PI ProcessBook allows you to create custom placeholders for a symbol based on
a summary Data Set. Placeholders are not allowed for expression Data Sets. The
Custom Placeholders button in symbol definition dialog boxes allows you to
specify different PI Tags for a PI Summary Data Set. The change applies only to
the configured symbol.
1. In the Placeholder Name box, select the parameter you want to configured. The
parameters are in the same order as found in the data set query. The list is limited to the
number of parameters found in the query.
2. In the Placeholder Properties group, select the Type for the selected parameter. There
are four possible types, Text, PI Tag, Start Time, and End Time. You can optionally
change the name of the placeholder to make its purpose clear.
3. Selecting a type transforms the dialog to allow you to enter the settings for the selected
type, if any.
If the query uses:
• Text input—Type the replacement text value in the Text field.
• Tag values—Type a node ID and tag name or click the Tag Search button to open
the Tag Search dialog.
• Start and/or end times—No additional configuration is used.
4. Click the Set button.
5. To configure another parameter, select it and repeat the previous steps.
6. Click OK.
164
Add a Data Set to a Trend
Note: If you want to display the ODBC Data dialog instead of the PI Calculation
Data dialog, then click the Tag Search arrow, and then select ODBC.
7. Under Saved Data Sets, click the data set you want to add to the trend.
8. Under Data Set Columns, select a column(s) to be plotted in the trend (use the SHIFT or
CTRL keys to select more than one column).
9. Click OK.
Note: Until you select a data set and at least one column, the OK button is dimmed.
10. The selected data set/column(s) is now listed under Tags in Plot in the Define Trend
dialog. Select tags as desired and format the trend. If you wish to see or edit the
definitions of placeholders, click the Custom Placeholders button in the Define Trend
dialog.
11. Click OK. Data displays on the trend.
Note: If you select the Description check box, on the Display Format tab in the Define
Trend dialog, then the description of the data set is taken from the PI Calculation
Data dialog and repeated for each column that is plotted. There are usually no
engineering units for a data set column.
166
Run PI ProcessBook When Data Sets Are Included
Note: To determine if Microsoft Query is installed, the application checks your MS-
DOS path for the existence of msquery.exe)
Note: Microsoft Query cannot edit query statements that contain placeholders.
1. Add or edit the appropriate WHERE clause in the query to edit a placeholder data set or
existing placeholders (question marks represent placeholders in the query statement).
2. Click the Placeholders button. This action causes the syntax of the query to be checked.
3. If the syntax is valid, then the Placeholders dialog displays with the current placeholders.
If the syntax is invalid, then an invalid query message is displayed.
4. Click the Check Syntax button, to complete a syntax check of your query. The status of
the query is returned.
5. When you have finished modifying the data set, click OK. If the data set is in use in a
display, the Confirm Data Set Modification dialog displays.
6. If you wish to proceed, click Continue. The Data Sets dialog appears.
7. Select the column(s) to be used and click OK to return to the dialog.
168
Loading Custom Data Sets
5. From the To Open Workbook drop-down list, select the correct target, and then click
OK.
For more information on how to write Visual Basic scripts for use with PI ProcessBook, click
Help > PI Processbook VBA Language Reference.
Embedded Objects
Embedded objects are copied from an existing file or created and then stored as an integral
part of the container application, such as PI ProcessBook. Using an embedded object
increases the file size of a ProcessBook significantly.
Formats not natively supported by PI ProcessBook, such as Windows metafiles, can now be
pasted from the Windows clipboard as objects in a ProcessBook display.
To change the contents of an embedded file, double-click it. The source application software
is invoked, and you can edit the object with the source application's commands.
ProcessBook is a time-based application. When ProcessBook is used as an embedded object,
it updates dynamically whenever you double-click it.
If you rename a ProcessBook or move it to another directory, drive, or PC, any embedded
objects in displays can still be changed as long as your system can locate the appropriate
source application software.
Linked Objects
Linked object information is not stored as a part of the destination application. Instead, the
destination file stores only the location of the linked source file. No matter how many links it
has, only one version of the linked file is stored and maintained. Using a linked file increases
the file size of a ProcessBook less than using an embedded object.
In establishing an OLE link, you may update the:
Contents of the object dynamically whenever the source file changes
Update the object only by manual command
To change the data in a linked file, such as which tags you have selected, you switch to the
source application and open the file. Changes are then reflected in the container display
according to the update method you selected.
Alternatively, if you double-click the object, the source application and the actual file open,
allowing you to edit the object. If the source application supports in-place activation, you can
edit within the container window; otherwise a source application window opens.
If you rename a ProcessBook or move it to another directory, drive, or PC, any links from displays to
source files can break. These broken links need to be re-established if you wish to continue using them.
172
ActiveX Controls
Embed—If you want to update the object data within the target document or if you want
to store all the source data within the container application.
Link—If you want the data to update dynamically or when you need to minimize file
size. The source application must continue to be available.
Note: When you link to a ProcessBook container, there is a risk of accidentally changing
the source file.
ActiveX Controls
You can insert ActiveX controls that are installed on your PC into PI ProcessBook displays.
If you move the displays to other machines, then you must also install the controls there.
Some ActiveX controls are self-contained and will work without further scripting. Most
require additional VBA code before they function correctly.
Add a Control
In Run mode, a user could change the month and date. A programmer could incorporate
the calendar into scripts associated with the display.
The equipment parts list is stored with the ProcessBook display. If your PC has an installed
copy of MSWord, you can peruse or modify the list at any time simply by double-clicking it.
The lab results are stored by the source application, not in the ProcessBook display. The
display can be set to update lab data dynamically whenever the results in the source
application changed, or it can be set to update lab data when you click an Update Now button
on the Edit Links dialog.
174
Embedding in ProcessBook
Embedding in ProcessBook
Objects may be created within a PI ProcessBook display by the source application and then
stored as embedded objects. Alternatively, you may create objects from existing files or parts
of files. In addition, you can embed an object by dragging it from another application.
Unless you are using drag and drop embedding, you must be in Build mode in order to insert
a new object. Choose Insert > Object to launch the Insert Object dialog.
Note: If you want to display an icon rather than a graphic, select the Display as Icon
check box.
Note: if you open a display and drag an object elsewhere, the display is permanently
changed, regardless of whether you save it or simply close it.
Note: If you want to display an icon rather than a graphic, select the Display as Icon
check box.
176
Dynamic and Manual Updates of a Linked Object
Note: You can select several links at once by pressing the CTRL key and clicking
each link.
178
OLE Object Colors
Note: When editing a linked object file, remember that the file may also be an object in
other applications besides PI ProcessBook.
In addition, you can reach the source application through the Links dialog.
1. Choose Edit > Links. The Links dialog appears.
2. Click the appropriate link.
3. Click the Open Source button to open the source file.
If Then
The source application permits in-place activation, Edit the object.
menus and commands for the source application Save it if it is a linked file.
appear on your screen, temporarily replacing
ProcessBook menus. Click elsewhere on the display to return to
ProcessBook or press the ESC key.
The source application does not permit in-place Edit the object.
activation, a new window containing the source Save it if it is a linked file.
application appears.
Close the window and return to ProcessBook.
180
Share ProcessBook Displays with Other Applications
Note: To switch from an icon to a graphic, clear the Display as Icon check box.
6. To select the icon to use, click the Change Icon button. The Change Icon dialog
appears.
1. Open the container application. For example, open a spreadsheet and select a cell in
which you want to place a display.
2. Choose Insert > Object. The Object dialog appears.
3. On the Create New tab, under Object type, click PI Display Document.
Note: If you want to display an icon rather than a graphic, select the Display as icon
check box.
4. Click OK.
5. The display is embedded in the container application.
Note: When you activate the dragged contents, the entire original display is drawn,
regardless of which objects were dragged to the new container.
Note: If you select the Display as Icon check box, then the Object Packager icon is
used by default, rather than the ProcessBook icon.
OLE Container/Server
A ProcessBook display may be shown in another application. For example, you could include
an updating trend in an incident report produced in a word processing application such as
Microsoft Word. Or, you could prepare a presentation for a group by using Microsoft
PowerPoint to prepare slides and including embedded displays from PI ProcessBook. To do
this, use the Insert Object command in the second application and insert an object of type PI
Display Document.
182
Appendix A
VBA Commands
Access VBA through the VBA toolbar, or by choosing Tools > Macro:
Visual Basic Editor Switches to VBA Editor window
Run Macros Opens the Macros dialog, which provides a way to select,
debug, and run existing VBA scripts
Design Mode Stops any scripts that may be running or may start running.
Useful for debugging
ActiveX Automation
ActiveX Automation refers to the technology of placing ActiveX controls (independent
software modules) within applications and using scripts to manipulate the application and/or
the controls.
Write a VB program to start PI ProcessBook, access a particular display, and then alter it
in some way.
Click on a command button in ProcessBook to make an Excel spreadsheet show the
average and raw data of the current trend in ProcessBook. Then you change the time
range of the ProcessBook, click the button again, and see the Excel spreadsheet update
with the new time range.
Use a mouse click within a PI ProcessBook display to initiate updates or adjustments in
the display.
Update a PI ProcessBook display by typing new tag names into a spreadsheet.
Although Automation scripts are not required to use a dialect of Visual Basic, at the present
time, that is the most common approach.
Automation Vocabulary
Understanding OLE automation requires some technical vocabulary. Terms used in the PI
ProcessBook VBA Language Reference Guide are defined below.
Automation Accessing an object in an application and changing it or using it without using the
user interface.
ActiveX The application that provides data. PI ProcessBook is an OLE Automation Server.
Automation It provides access to its internal objects from other applications.
Server
ActiveX The application that initiates changes through scripts. PI ProcessBook is an
Automation Automation container, as are Microsoft Excel, Microsoft Access, and a few other
Container commercial products.
Object A specific item that may be manipulated by a script. For example, a ProcessBook,
a display, or a symbol may be the object of a VB or VBA script.
Property An attribute of an object. An object with read-write properties can have variable
information assigned to it by the script. A read-only property cannot be changed.
Method An action that can be performed on an object and may or may not return a value.
Sometimes called a function.
Event A procedure that executes whenever a particular action occurs, such as a mouse
click.
184
Appendix B
ODBC
ODBC Drivers
Each DBMS (database management system), such as Microsoft SQL Server, requires a
specific ODBC Driver, provided by the vendor of the DBMS or a third party. Each driver is a
Dynamic Link Library (.dll) that implements a set of subroutine calls to retrieve data from
a particular database.
The Microsoft ODBC Driver Manager is included as a part of PI ProcessBook installation.
bar. The SQL needed to retrieve data for PI ProcessBook can be configured once and used by
many displays and symbols.
PI ProcessBook must return a time and value pair(s) for display within a symbol (trend,
value, or bar). Placeholders act as parameters to an SQL function call. They are evaluated at
run time. Placeholders can take three forms: text, start/end times, or a PI tag name. Use the
start and end time placeholders when the time limits of the query should be determined from
the trend symbol where the query is used. The PI tag name placeholder can be used to join PI
data with relational database data. A PI Value is retrieved for the PI tag and then substituted
into the query.
Using ODBC requires that you install the Microsoft ODBC Driver Manager and drivers
(most operating systems already have the Driver Manager and some standard drivers
installed). You must then configure data sources (page 187) for ProcessBook and define
individual queries, called data sets.
186
Prepare for ODBC
Note: Click the Help button, if necessary, and follow Microsoft's instructions for
completing the dialog box.
4. When you have completed configuring the data source, click OK to return to the
Microsoft ODBC Data Source Administrator dialog.
Note: To create data sources for any user of the computer, use the System DSN tab
instead of the User DSN tab.
Note: The MS Query application does not work with an ODBC query that includes
placeholders. Consequently, the Design button in the ODBC Data dialog may be
disabled.
188
Troubleshoot ODBC Data Sets
An ODBC data set is created with a set of default placeholders. When it is attached to a
specific symbol, the query's placeholders can be customized for that symbol, without
affecting the placeholders defined for other symbols using that data set.
For example, you can create a query for a database of laboratory data using a text placeholder
for the sample name. You can then use a different sample name for every trend, bar, or value,
rather than defining a new data set query for each sample name.
1. Choose Tools > Data Sets. The Data Sets dialog appears.
2. Click New. Click ODBC. The ODBC Data dialog appears.
3. Click Setup. The ODBC Data Source Administrator dialog appears.
4. Select the Tracing tab.
5. To change the file where tracing is logged, choose a new file path in the Log File Path
text box. Use the Browse button to search for files.
6. To initiate tracing, click the Start Tracing Now button. The label changes from Start
Tracing Now to Stop Tracing Now, and the Log File Path text box becomes unavailable.
7. To stop tracing, click the Stop Tracing Now button.
Note: If you delete the wrong driver you need to reload it from the vendor's diskettes.
190
Appendix C
Troubleshooting Tips
Is an XYPlot Updating?
When an XYPlot is updating, the updating tags are shown with an arrow indicator in the
legend. An XYPlot is updating if the following conditions exist:
The end time for the X tag is indicated as the current time (by using *) or is in the future
(*+N)
At least one of the Y tag end times is indicated as the current time (by using *) or is in the
future (*+N) and is not synchronized or matched with the X tag (if X is not updating).
If both the X tag and the Y tag are updating, an arrow indicator is shown in each legend entry.
Updates for retrieval methods Recorded and Interpolated are received from an event pipe that
provides the application with snapshot values. For this reason, when a tag is using recorded
values, you may see many more values while the plot is updating than are actually recorded.
Once the plot is regenerated or reverted, only recorded values are shown. When using the
interpolated retrieval method, values on the plot are interpolated using the snapshots coming
in through the event pipe.
192
ODBC Problems
ODBC Problems
If no values are found for one of the selected columns in a query, the trace will not be drawn
and the value in the legend reads No Data.
If the necessary time value is not defined in the query, either by a date/time column or by a
placeholder tag, the trace is drawn as a straight line using one value.
Occasionally, an ODBC data source cannot be found. This can occur because the data source
was deleted or because the ProcessBook .piw file has been moved to a machine that does
not have the same data source defined.
To resolve the problem, re-define the data source. The following figure shows what happens
when a Trend attempts to display a trace for which the data source no longer exists.
DEFAULT=PI
[CLIENTACCESS]
DEFAULT=RW
DYAN=R
ERIC=R
JOHN=NONE
The above entries in piserver.dat result in:
The machines named DYAN and ERIC have only read access to PI data.
The machine named JOHN does not have any access to PI data.
All other machines have both read and write access to PI.
The value for the DEFAULT entry is initially set to RW. Otherwise, existing PINet nodes will
not function properly.
If you want to restrict write access from PCs, set the default CLIENTACCESS to R and add
entries to accommodate your PINet Nodes. For example:
[USERDATABASE]
DEFAULT=PI
CLIENTACCESS
DEFAULT=R
BRIAN=RW
The preceding entry allows the PINet node BRIAN to read and to write data to the PI System.
All other nodes have read- only access.
TCP/IP node names are case-sensitive. In addition, the values for the entries in the
CLIENTACCESS section (for example, R and W) are also case-sensitive.
Machine Address
Because PI ProcessBook is a client/server application, the communication setup is essential.
The machine address, which allows the PI System to recognize your machine, is a key item.
Often, the address may be found as an alias in the TCP host file. The Network Administrator
should resolve any questions or difficulties regarding the network and addressing.
PROCBOOK.INI
The PROCBOOK.INI file contains configuration and preference settings for PI ProcessBook.
This file generally resides in two places, the user's default location, C:\Documents and
Settings\<user name>\Application Data\PISystem\PI-
ProcessBook\<language>, and the PIPC\DAT directory (on the local drive where PI
ProcessBook is installed).
196
PROCBOOK.INI
Startup Section
198
PROCBOOK.INI
Startup Example
[Startup]
Startup ProcessBook=PIDEMO30.PIW
DefaultFileLocation="C:\Program Files\PIPC\Procbook"
ModeBias=R
Retain Aspect Ratio=0
Symbol Library=SYMLIBRY.PIW
PromptForConversion=[PB_PROMPTFORCONVERSION]
Show Value Attributes=1
PB2TraceCompatibility=1
MakeBackupFile=0
ToolTipsEnabled=Y
Author=
International Date Format=1
MaxUndoStackSize=20
Build Scroll Mode=1
Run Scroll Mode=1
GridSize=12
FileAccessTimeout=5
FileAccessInterval=1
COMTimeOut=30
RunSelectorColor=0,0,0
MacroProtectionLevel=0
TBFilePath=
UserDefaultTB=
PBDefaultTB=
References=
URL Home="http://www.osisoft.com/"
MaxBitmapMB=16
ServerTimeZone=1
Processbook=PRIMARY
EnableScreenSaver=1
ConnectUsingAPI=0
EnableConnectorAttachments=1
The ProcessBook View section of the .INI file should be modified through the Tools >
Preferences dialog and should resemble this example:
[ProcessBook View]
BookView = 1
BookView controls the view in which a ProcessBook is displayed when opened (0 =
Outline, 1 = Book).
To change the font for the tabs in book view, add a section similar to this example:
[BookTab_Font]
Height=-13
Weight=0
Italic=0
Underline=0
PitchAndFamily=0
FaceName=Arial
The FaceName should be a True-Type font so that it can be rotated.
Conversion Section
The Conversion section of the .INI file identifies resources for importing other file formats
and resembles this example:
[Conversion]
Import0 = PIDisDIFF Files, impd32.dll, dat
Import1 = PI-Graphics Files, impp32.dll, dat
ImportN identifies the file types used when converting VAX-formatted trends or graphics.
N increments by one for each file type.
200
PROCBOOK.INI
The second field is the name of the file type to be imported and will appear in the List Files
of Type drop-down box in the Import File dialog box.
The third field is the DLL used to import the file type. No path is necessary, since the files
reside in the same directory as Procbook.exe.
The fourth field is the default extension for the file type. You may have more than one
extension for each import type, separated by semicolons.
The Data Manager section of the .INI file should be added by the System Manager and
should resemble this example.
[Data Manager]
TIMER = 5000
TIMER sets the poll timer, in milliseconds, for checking whether PI ProcessBook should
perform any time-related task. Time-related tasks include retrieving exception reports from PI
and re-querying sources. (60,000 is the maximum setting; the default is 5000.)
Colors Section
202
PROCBOOK.INI
Example:
[Colors]
Color1=255,255,255
Color2=255,0,0
Color3=0,255,0
Color4=0,0,255
Color5=0,255,255
Color6=255,0,255
Color7=255,255,0
Color8=0,0,0
Color9=192,192,192
Color10=128,0,0
Color11=0,128,0
Color12=128,128,128
Color13=128,0,128
Color14=0,0,128
Color15=128,128,0
Color16=0,128,128
Possible entries:
TimeRangeMin/TimeRangeMax—set the minimum/maximum time that can be scrolled to
(must be valid PI time string)
PageScrollNonlinearity—sets the factor by which clicking on and holding the mouse button
down in the page scroll area will increase the speed that the thumbwheel of the scrollbar
moves. A value of 0 indicates no acceleration.
LineScrollNonlinearity—sets the factor by which clicking on and holding the mouse button
down in the line scroll area will increase the speed that the thumbwheel of the scrollbar
moves. A value of 0 indicates no acceleration.
ThumbScrollNonlinearity—sets the factor by which clicking and holding the thumbwheel
of the scrollbar will increase the speed that the thumbwheel moves
Example:
[Time Range Scroll]
TimeRangeMin=*-100d
TimeRangeMax=*+10d
PageScrollNonlinearity=20
LineScrollNonlinearity=100
ThumbScrollNonlinearity=20
Possible entries:
DisplayBackgroundColor—Red, Green, Blue, values can range from 0 to 255, sets the
background color for any newly created display
SymbolFillColor—Red, Green, Blue, values can range from 0 to 255, sets the fill color for
newly created symbols
SymbolLineColor—Red, Green, Blue, values can range from 0 to 255, sets the outline color
for newly created symbols
SymbolBackgroundColor—Red, Green, Blue, values can range from 0 to 255, sets the
background color for newly created symbols, for example, the empty portion of a bar symbol
takes on this color.
Example:
[Display Colors]
DisplayBackgroundColor=192,192,192
SymbolFillColor = 0,0,255
SymbolLineColor = 255,255,255
SymbolBackgroundColor = 192,192,192
204
PROCBOOK.INI
Macro Protection
The primary purpose of the macro protection feature is to prevent misbehaved VBA event
code from executing. Whenever a ProcessBook display (either standalone .pdi file or table
of contents entry) is opened, ProcessBook determines whether the display has any VBA code
present.
MacroProtectionLevel may be set in the [STARTUP] section of Procbook.ini at one
of the following levels:
Value Description
The default value for this setting is 0, so that if it is not present at all in the .ini file, then
PI ProcessBook always executes macros.
Installations of PI ProcessBook can be configured so that users on a network may only view
ProcessBooks and not change them. The user has access to the Standard toolbar, including
the Trend Display feature, but cannot save an ad hoc display.
Security
Any string or integer value in PROCBOOK.INI can be overriden in the registry. Overrides
can be provided in the HKEY_LOCAL_MACHINE\SOFTWARE\PISystem\PI -
ProcessBook\Security key. Under that key there is a key for the INI file section. The
values are in that section. For example, to override the EnableScreenSaver setting in the
STARTUP section of PROCBOOK.INI, a DWORD value EnableScreenSaver with a value of
1 would be created in HKLM\SOFTWARE\PISystem\PI -
ProcessBook\Security\Startup.
If a value is found in the Security overrides section of the registry, the PROCBOOK.INI files
will not be accessed.
The PI ProcessBook setup kit does not create these registry keys; it is up to each site
administrator to create the keys if they want to override the PROCBOOK.INI settings.
IMPPIGP.INI
The IMPPIGP.INI file contains configuration settings used by the Import utility in PI
ProcessBook. The file generally resides in the PIPC\DAT directory. As with other .INI
files, SETUP.EXE creates this file with default settings.
When you import VAX-formatted graphics and graphics that include trends, the import utility
uses the settings found in this .INI file to convert items such as color, line style, and fonts.
You can edit the .INI file if you want to change these default settings. Before you edit this
file, you should make a backup copy so you can restore PI ProcessBook to its original
settings.
Note: The settings in this .INI file affect graphics and trends included in graphics only.
When importing trend displays, the format specified in the Trend Preference
setting is used.
The following is a list of the keywords in the IMPPIGP.INI file. The values shown are
examples and not necessarily the default settings shipped with PI ProcessBook:
The Color section of the .INI file maps VAX colors to PI ProcessBook colors:
[Color]
Clear=0,0,0
Black=0,0,0
White=255,255,255
Red=255,0,0
206
IMPPIGP.INI
Green=0,255,0
Blue=0,0,255
Cyan=0,255,255
Magenta=255,0,255
Yellow=255,255,0
Orange=255,128,0
GreenYellow=128,255,0
GreenCyan=0,255,128
BlueCyan=0,128,128
BlueMagenta=0,0,128
RedMagenta=255,0,128
DarkGray=128,128,128
LightGray=192,192,192
The values shown to the right of the equal sign are the red, green, blue values. Refer to
“Creating Your Own Colors” in the Windows documentation for more information on
changing these values.
The Line Style section maps the VAX line format to the PI ProcessBook line format:
[Line Style]
Supress=5
Solid=0
XShortDash=2
DotShortDash=3
LongDash=1
XLongDash=1
TwoDotDash=4
LongDotDash=3
ShortDash=1
The PI ProcessBook values to the right of the equal sign represent:
0 = solid
1 = dash
2 = dot
3 = dash dot
4 = dash dot dot
5 = suppress
The Font section maps the VAX supported fonts to PI ProcessBook fonts:
StandardFont=35,400,0,0,34,Arial
SmallVector=-29,400,0,0,34,Arial
MediumVector=-52,400,0,0,34,Arial
LargeVector=-77,400,0,0,34,Arial
Note: These default values are based on resolutions for VT340 terminals. If you are
using a terminal other than these, appearances may be different.
The values to the right of the equal sign represent these font characteristics.
Position Font Definition
Characteristic
1 Height Specifies the height of the font. If the value is greater than zero,
it specifies the cell height. If the value is less than zero, it
specifies the character height, which is the cell height minus the
leading.
2 Weight Specifies the weight of the font (for example, light, medium,
bold). Values can be from 0 to 900 in increments of 100. 100
equals the lightest; 900 the darkest.
The Marker section of the .INI file maps the VAX trend markers to the markers provided
in PI ProcessBook:
[Markers]
NoMarker=9
Dot=0
SmallPlus=6
LargePlus=7
Asterisk=0
Circle=1
LargeX=8
Box=5
Diamond=3
BoxWithDot=4
DiamondWithDot=2
BoxWithDiamond=4
The values to the right of the equal sign represent these marker types in PI ProcessBook:
0 = filled circle
1 = open circle
2 = filled diamond
3 = open diamond
4 = filled square
5 = open square
6 = filled triangle
7 = open triangle
8 = cross
9 = none
The Display section in the .INI file specifies the supported terminals in PI ProcessBook:
[Display]
Terminal Type=VT340
Keywords for supported terminals are shown below. The horizontal and vertical dimensions
are also shown.
VT340 = 800 x 500
Reflection = 800 x 500
Tektronix = 4095 x 3130
X1024 = 880 x 640
X800 = 560 x 448
If your terminal is not included in the list of keywords, you can create your own. The syntax
is:
Terminal Type=Custom,X,Y
208
SETUPProcessBook.LOG
where X equals the horizontal dimension and Y equals the vertical dimension.
SETUPProcessBook.LOG
This log tracks the setup of PI ProcessBook on your system and holds information pertaining
to directory structure, user-entered information for Node, .DLL, and User name, and the
installation of the various ProcessBook files.
Telephone support is available 24 hours a day, 7 days a week. Direct service may not be
available in some locations or during some hours; in this case, leave a message and your call
will be returned within four hours.
USA and Canada: (510) 297-5828
Outside of North America: +01 510-297-5828
FAX: (510) 352-2349
Email Support
Email technical support inquiries, including the problem description and message logs, to
techsupport@osisoft.com. You will receive a response within 24 hours.
The Online Call Center allows you to create a support call, which will be responded to in 24
hours. It also allows you to review information from your previous support calls. Choose My
Support > My Calls (Online Support) in the Technical Support Web site. The My Support
menu allows you to review My Products, My Download History, and SRP Terms, which
covers Service Reliance Program (SRP) service agreements.
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical data, as
well as a special collection of resources for system managers. For these options, click
Knowledge Center in the Technical Support Web site.
The Search feature allows you to search Support Solutions, Bulletins, Support Pages,
Known Issues, Enhancements, and Documentation (including user manuals, release
notes, and white papers).
System Manager Resources include tools and instructions that help you manage: archive
sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server
security, PI system sizing and configuration, PI trusts for interface nodes, and more.
Technical support engineers can remotely access your PI Server to provide diagnostics,
hands-on troubleshooting, and assistance. Choose Contact Us > Remote Access Options in
the Technical Support Web site.
OSIsoft provides on-site service according to SRP service level agreements. To see current
SRP status, go to My Support > SRP Terms on the Technical Support Web site.
PINet and PIonPINet require special consideration for support and upgrades. Please follow
these instructions:
212
Before You Call or Write for Help
Upgrades
To request an upgrade, provide PINet and operating system version, and platform information
to Technical Support. Follow PI2 upgrade request instructions on the Technical Support Web
site. Select Contact Us > Obtaining Upgrades.
Data Source • 164, 191, 192, 199 Rectangle, Square, Arc, Ellipse, or Circle • 131
Configuring the • 193, 196 XYPlot • 103
Definition of • 164 Driver Manager • 191
Delete a • 196 Dynamic Symbol • 55, 79, 125, 127, 155, 181
Edit a • 196 Bar • 125
Troubleshooting • 199 Button • 123
Default definition of • 155
Preference settings • 18 Multi-State symbol • 127
Trend Format • 82 Status of • 156
Delete • 48, 82, 172, 184, 196 Trend • 79
a Data Set • 172 Value • 121
a Plot within a Trend • 82 XYPlot • 101
an Entry • 48
an ODBC Data Source • 196 E
an ODBC Driver • 196 Edit • 171, 182, 183, 196
an OLE Object • 184 a Data Set • 171
Deselect a Symbol • 142 a text box • 130
Design Mode, VBA • 3, 189 an ODBC Data Source • 196
Details Window • 139, 140, 142 Embedded Objects • 183
Open • 139 Linked Objects • 183
Pin • 142 Ellipse • 130, 131
Digital values • 121 Embed • 176, 186
Disabling macros • 211 discussion of • 176
Disconnect from a Server • 9 Example of • 178
Discrete trace • 95 Existing ProcessBook Display in Another OLE
Display • 8, 55 Application • 186
as an Embedded Object • 186 ProcessBook Display in Another OLE
Can't Find Data • 197 Application • 186
Connection Failure • 9 vs. Link • 177
Data sources for • 1 Entries • 37, 43, 47
Elements of • 104, 108, 109 Arranging • 43
Manage multiple displays • 57 Change the Name of • 45, 47
Module-relative • 73 Creating • 37
Point Attributes • 63 Placement in ProcessBook • 37
Reducing to Icon • 60 Rearranging • 47
Resizing • 58 Types of • 45
Saving • 60 Expanding a Trend • 88
Display Entry • 37
Linked Display Entry • 39 F
Text or Display • 38
File
Displaying an Item's Definition • 155
How to Import • 52
Displaying an OLE object with an Icon • 184
Sharing • 53
Drag and Drop Embedding • 180
Flags for Data • 157
Draw • 62, 64, 103, 131, 132, 133
Flip command • 143
Drawing Area • 62
Floating Point values • 121
Drawing Grid • 65
Font • 66
Drawing Tools • 64
Font section of the imppign.ini file • 212
Free-form Objects • 132
Format • 65, 66, 67, 68, 69
Line • 130
Color • 67, 68
Polylines • 133
Editable Formatting Attributes • 66
216
Font • 66 Assign symbol to • 72
Line • 68, 69 Composite symbols • 72
Trend • 82, 83, 85, 86 Working with • 70
Formatting Paintbrush • 69 Z Order • 70
Full Screen • 17, 59 Layout tab • 82, 86
Full Timestamp • 95 Legend • 103, 104, 108, 109
Future Trends • 16 Level of an Entry • 45
Line • 24, 68, 85, 130, 212
G Draw • 130
Graphics • 99, 133, 134 Ends • 69
Convert from VAX to PC • 99 Style • 23, 24, 68, 85
Graphic Symbol • 133, 134 Weight • 68, 85
Icons vs. Graphics • 178 Linear Correlation Line • 108
Grid • 65 Linear Regression by Least Squares Method • 113
Grid Lines • 91 Link • 176, 177, 180, 181, 186
Size • 65 Existing File into a ProcessBook Display • 180
Group Symbols • 145 ProcessBook to Another Application • 186
Re-establishing • 182
H vs. Embed • 177
Linked Displays or ProcessBooks • 39
Handles • 142 Add • 39
Horizontal flip • 143 Logarithmic scales • 79, 91
How Trends Refresh • 90
M
I
Macros • 3, 189, 211
Icons • 60 Markers • 23, 96
Graphics vs. Icons • 178 Shapes • 24
impg32.dll • 202 Menu • 16
Import • 52, 98 Minimize • 58
Files • 52 Missing Data Sources • 191, 199
VAX-formatted trends and graphics • 98 Missing Trace • 199
imppigp.ini • 212 Mode, Run and Build • 8, 37
Independent Display files • 58 Module Context • 73, 74, 75, 76, 77
Saving • 60 Features • 74
Installation • 4 Module Context Add-in • 73
Testing • 4 Move • 41, 53, 77, 82
Integers • 121 a Display to another PI Server • 77
Internet Explorer • 58 a Plot • 82
Interpolated data retrieval method • 103, 104 a ProcessBook to another PC • 53
Interval • 103, 104 MSQuery • 194
Invisible line on a trend • 24 Multiple Objects • 142, 144, 145
Item Definition • 155, 156 Align Multiple Symbols • 145
How to Select • 142
K Stacking Order • 144
Keyboard Shortcuts • 28, 29, 30 Ungroup • 145
Multi-State Symbol • 127
L
N
Layers • 70, 72, 73
Adding a Layer • 70 Name • 35, 45, 70
218
Rotate a Symbol • 143 Rotate • 143
Run • 57 Select • 142
Entry • 57 Stacking • 144
Macro • 3 Static • 55
Mode • 37 System Administration • 201, 202, 212, 215
System Requirements • 4
S
Save • 48, 60, 98 T
Ad Hoc Trend Display • 98 Tags • 62, 63
Preferred View of Your Entries • 48 Text Symbol • 129, 130
ProcessBook • 48 Tile Windows • 57
ProcessBook Displays • 48, 60 Time • 10, 13, 15, 16
Scripting • 3, 189 Time Forward and Back • 16
Scrollbars • 13, 15, 16, 61, 90 Time Range Toolbar • 13
Search • 59, 63 Time range • 13, 15, 16
for a Specific Display • 59 Changing • 15
for a Tag • 63 Revert • 13
Select Available Modules dialog • 75 Toolbar • 13
Selected Modules list • 75 Timestamp • 95
Selection handles • 64, 82, 139, 142, 145 Title
Server • 8, 9, 10 of a trend • 90
Connect to a • 9 of ProcessBook or Display • 49
Disconnect from • 9 Too Many Points • 118
Display information about • 10 Toolbars • 16, 17, 18
Setup procedure • 31, 202, 215 Add Buttons to • 18
setup.exe • 202 Customize • 17
setup.log • 215 ToolTips • 21, 69
Single Scale for the Vertical Axis • 92 Trace • 85, 95, 96, 195
Snap to grid • 65 Definition of • 95
Span • 91 Hiding • 95
Square • 131 Markers • 96
How to Draw • 131 Missing • 199
Stacking Order • 144 Trace ODBC Calls • 195
Starting PI ProcessBook • 7 Trend • 23, 24, 79, 82, 88, 89, 90, 97, 98, 169, 197,
Startup section of Procbook.ini • 202 207
Static Symbols • 55 Ad Hoc • 97
Status Report • 156 Analysis tools • 88
Stored Procedures in Queries • 194 Cursors • 89, 197
Substituted Data Flag • 157 Data Sets in • 169
Summary Information • 49 Default Format • 82
Symbol Attachments Default Preferences • 23
Dialog Box • 153 Definition section of procbook.ini • 202
Symbol Library • 202 Delete a Plot • 82
Symbols • 55, 121, 129, 135, 139 Expand • 88
Connect • 146, 147 Formatting a • 82
Delete • 143 Grid Lines and Labels • 91
Details and Annotations • 139, 140, 141, 142 Horizontal Scale Grid Lines • 95
Dynamic • 55 Importing VAX-Formatted • 98
Flip • 143 Invalid data • 9
U
Ungroup Symbols • 145
Updates • 181, 198
Break Links • 181
by Exception • 2
for Future Trends • 16
for Trend data • 90
Links • 181
to Linked Objects • 181
to PI Data • 2
Troubleshooting • 198
Update dynamically • 176
Upgrades • 4
V
Value • 121
Value Scale • 23, 79, 91, 92, 95
VAX • 52, 98, 99, 201, 206, 212
VBA • 1, 3, 17, 177, 189, 190
View Only Mode • 212
Views • 43, 45
Book • 43
Outline • 45
Visible Layer • 70
VMS • 98, 99, 201
W
Workspace • 7
X
XY Plot • 101, 103, 104, 108, 109, 110, 113, 114,
116, 118
220