CitectSCADA Process Analyst

Process Analyst User Guide
Citect Pty. Limited

3 Fitzsimons Lane
Pymble NSW 2073
Australia
Telephone: 61 2 9496 7300
Fax: 61 2 9496 7399
DISCLAIMER
Citect Corporation makes no representations or warranties with respect to this manual and, to the maximum extent permitted by law, expressly limits
its liability for breach of any warranty that may be implied to the replacement of this manual with another. Further, Citect Corporation reserves the right
to revise this publication at any time without incurring an obligation to notify any person of the revision.
COPYRIGHT
Copyright 2004 Citect Corporation. All rights reserved.
TRADEMARKS
Citect Pty. Limited has made every effort to supply trademark information about company names, products and services mentioned in this manual.
Trademarks shown below were derived from various sources.
Citect, CitectHMI, and CitectSCADA are registered trademarks of Citect Corporation.
IBM, IBM PC and IBM PC AT are registered trademarks of International Business Machines Corporation.
MS-DOS, Windows, Windows 95, Windows NT, Windows 98, Windows 2000, Windows for Workgroups, LAN Manager, Microsoft Windows XP, Excel
and MSMAIL are trademarks of Microsoft Corporation.
DigiBoard, PC/Xi and Com/Xi are trademarks of DigiBoard.
Novell, Netware and Netware Lite are registered trademarks of Novell Inc.
dBASE is a trademark of Borland Inc.
GENERAL NOTICE
Some product names used in this manual are used for identification purposes only and may be trademarks of their respective companies.
October 2004 edition for CitectSCADA Version 6.0
Manual Revision Version 6.0.
Printed in Australia.
Contents
About this Guide
Part I Process Analyst for Operators
Chapter 1 The Process Analyst: An Overview
Chapter 2 Using the Main Toolbar
Chapter 3 Understanding Process Analyst Pens
Pens: An Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Data Compaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Data Quality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Date/Time (Horizontal) Axis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Vertical (Value) Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Gridlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Pen Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Pen Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Analog pens. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Digital pens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Alarm pens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Chapter 4 Interacting with the Process Analyst
Pen Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Locking/Unlocking Pens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Scrolling the Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Scaling the Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Using the Navigation Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Specifying a start time and end time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
About time spans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Span Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Navigating time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Synchronize to Now. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Toggle Autoscrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Zoom In/Zoom Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Contents iv
Undo Last Zoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Toggle Box Zoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Edit Span. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Edit Vertical Scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Reset to Default Span . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Using Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Using Cursor Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Using the Right-click Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Understanding Mouse Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Adding and Deleting Pens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Adding Pens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Deleting Pens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Viewing Pen Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Chapter 5 Using the Object View
Object View Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Using Object View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Chapter 6 Printing and Exporting
About Process Analyst Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Configuring Process Analyst Report Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Setting up report legends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Setting up report options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Exporting Pen Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Copying data to the Clipboard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Copying data to file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Chapter 7 Configuring the Process Analyst
Using the Process Analyst Properties Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Main page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Toolbars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Object View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Configuring Chart-wide Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Configuring general properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Configuring server paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Configuring Chart Panes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Configuring Pens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Configuring pen appearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Configuring pen gridlines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Configuring pen axes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Configuring pen quality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Configuring the pen data connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Configuring cursor labels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Contents v
Configuring Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Configuring Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Configuring Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Adding or removing toolbar commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Changing the order of toolbar commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Configuring the Object View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Object View properties page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Working with Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Saving a view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Loading a view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Chapter 8 Operator Command Reference
View Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Zoom Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Navigation Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Export Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Interface Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
General Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Part II Process Analyst for Users
Chapter 9 Integration with CitectSCADA
Configuring the Process Analyst Control from Graphics Builder . . . . . . . . . . . . . . . 77
Tag association . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Security and Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Administration privilege . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Command privilege . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Write privilege . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Multi-language Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Understanding the Process Analyst resources . . . . . . . . . . . . . . . . . . . . . . . 79
Using CitectSCADA to switch the Process Analyst language . . . . . . . . . . . . 80
Manually switching languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Specifying languages for the Web Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Creating your own Process Analyst resource.dll . . . . . . . . . . . . . . . . . . . . . . 81
Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Saving while using the Citect Graphics Builder . . . . . . . . . . . . . . . . . . . . . . . 87
Using the Save View toolbar button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Using the SaveToFile automation method . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Saving between Citect page transitions (Run-time) . . . . . . . . . . . . . . . . . . . 87
Resetting back to the default state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Backing up Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Contents vi
Chapter 10 Configuring Process Analyst Design Time Properties
Adding New Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Editing Existing Custom Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Creating or Editing Object View Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Process Analyst View Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Chapter 11 Using the Process Analyst Command System
Command System Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Custom Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
CommandExecuted. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
UpdateCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Chapter 12 Automation Model
Execution Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
IProcessAnalyst Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
IProcessAnalyst.BlockUpdates [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . 100
IProcessAnalyst.UnBlockUpdates [Method] . . . . . . . . . . . . . . . . . . . . . . . . 101
IProcessAnalyst.CopyToClipboard [Method]. . . . . . . . . . . . . . . . . . . . . . . . 102
IProcessAnalyst.CopyToFile [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
IProcessAnalyst.FreezeEvent [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
IProcessAnalyst.LoadFromFile [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . 105
IProcessAnalyst.PrintAll [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
IProcessAnalyst.SaveToFile [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
IProcessAnalyst.ShowProperties [Method] . . . . . . . . . . . . . . . . . . . . . . . . . 108
IProcessAnalyst.SubscribeForPropertyChange [Method] . . . . . . . . . . . . . . 108
IProcessAnalyst.SynchroniseToNow [Method] . . . . . . . . . . . . . . . . . . . . . . 110
IProcessAnalyst.UnsubscribePropertyChange [Method]. . . . . . . . . . . . . . . 110
IProcessAnalyst.AdminPrivilegeLevel [Property] [Get] . . . . . . . . . . . . . . . . 111
IProcessAnalyst.AutoScroll [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . 112
IProcessAnalyst.BackgroundColor [Property][Get/Set] . . . . . . . . . . . . . . . . 113
IProcessAnalyst.CommandSystem [Property][Get]. . . . . . . . . . . . . . . . . . . 114
IProcessAnalyst.ContextMenu [Property][Get/Set] . . . . . . . . . . . . . . . . . . . 115
IProcessAnalyst.Cursors [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . . . . . 116
IProcessAnalyst.DataRequestRate [Property][Get/Set] . . . . . . . . . . . . . . . 117
IProcessAnalyst.DisplayRefreshRate [Property][Get/Set] . . . . . . . . . . . . . . 118
IProcessAnalyst.Language [Property] [Get/Set] . . . . . . . . . . . . . . . . . . . . . 119
IProcessAnalyst.LastSelectedPen [Property][Get] . . . . . . . . . . . . . . . . . . . 120
IProcessAnalyst.LockedPens [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . 121
IProcessAnalyst.ObjectView [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . 122
Contents vii
IProcessAnalyst.Number of Samples[Property][Get/Set] . . . . . . . . . . . . . . 123
IProcessAnalyst.Panes [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
IProcessAnalyst.PrimaryPath [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . 125
IProcessAnalyst.SecondaryPath [Property][Get/Set] . . . . . . . . . . . . . . . . . 126
IProcessAnalyst.Toolbars [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . 127
IProcessAnalyst.WritePrivilegeLevel [Property][Get]. . . . . . . . . . . . . . . . . . 127
IProcessAnalyst.ZoomMode [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . 128
MouseDoubleClick [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
MouseClick [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
PenCreated [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
PenDeleted [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
PenRenamed [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
PenSelectionChanged [Event]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
HorizontalAxisChanged [Event]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
VerticalAxisChanged [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
CursorMoved [Event]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Error [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
PropertyChanged [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
OVItemAdded [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
OVItemRemoved [Event]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
OVItemSelected [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
OVItemChecked [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
OVColumnAdded [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
OVColumnRemoved [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
CommandExecuted [Event]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
UpdateCommand [Event] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
AlarmType [Enumeration] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
AxisLabelType [Enumeration] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
LineStyle [Enumeration] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
HatchStyle [Enumeration] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
PenNameMode [Enumeration] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
PenType [Enumeration]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
PointType [Enumeration] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
RequestMode [Enumeration]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
ToolbarButtonType [Enumeration]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
LineType [Enumeration] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
ErrorNotifyCode [Enumeration] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
QualityType [Enumeration] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
QualityCompactionType [Enumeration]. . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
FileLocation [Enumeration] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
IAnalogPen Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
IAnalogPen.LineColor [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . . . . . 150
IAnalogPen.LineInterpolation [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . 151
IAnalogPen.LineWidth [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . 152
IDigitalPen Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Contents viii
IDigitalPen.FillColor [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
IDigitalPen.LineColor [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . 154
IDigitalPen.LineWidth [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . 155
IDigitalPen.Fill [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
IAlarmPen Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
IAlarmPen.LineColor [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . . . . . . 157
IAlarmPen.LineWidth [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . 158
IAlarmPen.AlarmType [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . . . . . 159
IAlarmPen.GetFillColor [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
IAlarmPen.SetFillColor [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
IAlarmPen.GetHatchColor [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
IAlarmPen.SetHatchColor [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
IAlarmPen.GetHatchStyle [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
IAlarmPen.SetHatchStyle [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
ICursors Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
ICursors.Create [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
ICursors.RemoveAll [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
ICursors.Item [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
ICursors._NewEnum [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
ICursors.Count [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
ICursors.ItemByName [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
ITrendCursor Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
ITrendCursor.GetValue [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
ITrendCursor.Delete [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
ITrendCursor.Color [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
ITrendCursor.Width [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
ITrendCursor.Position [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . . . . . 174
ITrendCursor.Visible [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
ITrendCursor.Collection [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
ITrendCursor.Name [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
ITrendCursor.PenLabelVisible [Property][Get/Set] . . . . . . . . . . . . . . . . . . . 178
ITrendCursor.PenLabelWidth [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . 179
ITrendCursor.PenLabelHeight [Property][Get/Set] . . . . . . . . . . . . . . . . . . . 180
ITrendCursor.PenLabelX [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . 181
ITrendCursor.PenLabelY [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . 182
ITrendCursor.LabelsLocked [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . 183
IPen Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
IPen.AddSample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
IPen.Clear [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
IPen.Delete [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
IPen.GetDefaultSpan [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
IPen.GetHorizontalAxisTimeSpan [Method] . . . . . . . . . . . . . . . . . . . . . . . . 189
IPen.GetInformation [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
IPen.GetStatistic [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
IPen.GetVerticalAxisSpan [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Contents ix
IPen.GoToNow [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
IPen.HorizontalScrollBy [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
IPen.HorizontalZoom [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
IPen.PointsVisible [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
IPen.PutHorizontalAxisTimeSpan [Method] . . . . . . . . . . . . . . . . . . . . . . . . 197
IPen.PutVerticalAxisSpan [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
IPen.RefreshData [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
IPen.ResetToDefaultSpan [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
IPen.Select [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
IPen.SetDefaultSpan [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
IPen.SetQualityCompactionPointType [Method] . . . . . . . . . . . . . . . . . . . . . 202
IPen.SetQualityLineStyle [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
IPen.SetVerticalAxisLabelValue [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . 204
IPen.VerticalScrollBy [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
IPen.VerticalZoom [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
IPen.AxisBackgroundColor [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . 207
IPen.BlockRepaint [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
IPen.Collection [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
IPen.DataPoint [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
IPen.DataServer [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
IPen.Height [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
IPen.HorizontalAxisColor [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . 212
IPen.HorizontalAxisResize [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . 213
IPen.HorizontalAxisScroll [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . 214
IPen.HorizontalAxisWidth [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . 215
IPen.HorizontalGridlinesColor [Property][Get/Set] . . . . . . . . . . . . . . . . . . . 216
IPen.HorizontalGridlinesStyle [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . 217
IPen.HorizontalGridlinesWidth [Property][Get/Set] . . . . . . . . . . . . . . . . . . . 218
IPen.HorizontalMinorGridlinesColor [Property][Get/Set] . . . . . . . . . . . . . . . 219
IPen.HorizontalMinorGridlinesStyle [Property][Get/Set] . . . . . . . . . . . . . . . 220
IPen.IsDeleted [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
IPen.IsSelected [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
IPen.LocalTime [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
IPen.Name [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
IPen.RequestMode [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
IPen.Stacked [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
IPen.TrendCursorLabelFillColor [Property][Get/Set] . . . . . . . . . . . . . . . . . . 225
IPen.TrendCursorLabelLineColor [Property][Get/Set] . . . . . . . . . . . . . . . . . 226
IPen.TrendCursorLabelTextColor [Property][Get/Set]. . . . . . . . . . . . . . . . . 227
IPen.VerticalAxisAutoscale [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . 228
IPen.VerticalAxisColor [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . 229
IPen.VerticalAxisLabelType [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . 230
IPen.VerticalAxisResize [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . 231
IPen.VerticalAxisScroll [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . 232
IPen.VerticalAxisWidth [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . 233
Contents x
IPen.VerticalGridlinesColor [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . 234
IPen.VerticalGridlinesStyle [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . 235
IPen.VerticalGridlinesWidth [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . 236
IPen.VerticalMinorGridlinesColor [Property][Get/Set] . . . . . . . . . . . . . . . . . 237
IPen.VerticalMinorGridlinesStyle [Property][Get/Set] . . . . . . . . . . . . . . . . . 237
IPen.Visible [Property][Get/Set]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
IObjectView Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
IObjectView.Visible [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
IObjectView.Height [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
IObjectView.BackgroundColor [Property][Get/Set] . . . . . . . . . . . . . . . . . . . 241
IObjectView.ForeColor [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . 242
IObjectView.Columns [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
IObjectView.Items [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
IObjectView.SelectedItem [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . 245
IObjectViewItems Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
IObjectViewItems.Count [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
IObjectViewItems.Item [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
IObjectViewItems._NewEnum [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . 247
IObjectViewItem Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
IObjectViewItem.GetField [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
IObjectViewItem.PutField [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
IObjectViewItem.Expanded [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . 249
IObjectViewItem.Tag [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . 250
IObjectViewItem.Items [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
IObjectViewPenItem Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
IObjectViewPenItem.BlockColor [Property][Get] . . . . . . . . . . . . . . . . . . . . . 252
IObjectViewPenItem.Checked [Property][Get/Set] . . . . . . . . . . . . . . . . . . . 253
IObjectViewPenItem.Selected [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . 254
IObjectViewColumns Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
IObjectViewColumns.Add [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
IObjectViewColumns.Hide [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
IObjectViewColumns.Remove [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
IObjectViewColumns.Show [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
IObjectViewColumns.Count [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . 258
IObjectViewColumns.Item [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . . . . 259
IObjectViewColumns.ItemByName [Property][Get] . . . . . . . . . . . . . . . . . . . 260
IObjectViewColumns._NewEnum [Property][Get] . . . . . . . . . . . . . . . . . . . . 261
IObjectViewColumn Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
IObjectViewColumn.Name [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . 261
IObjectViewColumn.Text [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . . . . . 262
IObjectViewColumn.Width [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . 263
ICommandSystem Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
ICommandSystem.Count [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . 264
ICommandSystem.Item [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
ICommandSystem._NewEnum [Property][Get] . . . . . . . . . . . . . . . . . . . . . . 265
Contents xi
ICommandSystem.ItemById [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . 266
ICommandSystem.Create [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
ICommandSystem.Execute [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
ICommandSystem.Remove [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
ICommand Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
ICommand.CommandId [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
ICommand.ButtonType [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
ICommand.Enabled [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
ICommand.Pressed [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
ICommand.Tooltip [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
ICommand.Privilege [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
IToolbars Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
IToolbars.Count [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
IToolbars.Item [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
IToolbars._NewEnum [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
IToolbar Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
IToolbar.Visible [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
IToolbar.Buttons [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
IToolbarButtons Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
IToolbarButtons.Add [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
IToolbarButtons.Remove [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
IToolbarButtons.RemoveAll [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
IToolbarButtons.Count [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
IToolbarButtons.Item [Property][Get]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
IToolbarButtons._NewEnum [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . 282
IToolbarButton Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
IToolbarButton.CommandId [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . 283
IPanes Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
IPanes.Create [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
IPanes.RemoveAll [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
IPanes.Count [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
IPanes.Item [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
IPanes._NewEnum [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
IPanes.ItemByName [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
IPane Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
IPane.Delete [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
IPane.Height [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
IPane.Collection [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
IPane.Name [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
IPane.BackgroundColor [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . 292
IPane.FixedHeight [Property][Get/Set] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
IPane.Pens [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
IPens Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
IPens.Create [Method]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
IPens.RemoveAll [Method] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Contents xii
IPens.Count [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
IPens.Item [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
IPens._NewEnum [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
IPens.ItemByName [Property][Get] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
IPens.Pane[Property][Get]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Chapter 13 Cicode Programming Reference
Automation Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Handling an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Enumerating collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Implementing a custom command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Implementing a custom column. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Index 311
About this Guide
The information presented here is intended for two types of user, Operators and
Users:
Operator - a person who uses the Process Analyst in a runtime environment
to monitor plant operations. An Operator might configure the properties of
various Process Analyst components during runtime to facilitate their work.
An Operator is not expected to possess in-depth technical knowledge about
the Process Analyst components. For details about using the Process Analyst
as an Operator, see Process Analyst for Operators.
User - a person who uses the Process Analyst during design time to engineer
a view for an Operator. A User possesses in-depth technical knowledge
about CitectSCADA and Cicode, and understands how these components
interact. For details about using the Process Analyst as a User, see Process
Analyst for Users.
About this Guide 2
Part I
Process Analyst for Operators
This section contains information for Operators and describes the
following:
The Process Analyst: An Overview
Using the Main Toolbar
Understanding Process Analyst Pens
Interacting with the Process Analyst
Using the Object View
Printing and Exporting
Configuring the Process Analyst
Operator Command Reference
Chapter 1: The Process Analyst: An Overview
The Process Analyst control allows Operators to view trend and/or alarm tag
data (both real-time and historical) for comparison and analysis during run time
through their existing CitectSCADA server architecture. Users can configure
certain properties of the Process Analyst control during design time.
A typical Process Analyst view might look like the one shown here. Your Process
Analyst views will probably look different to this example.
The Process Analyst control interface typically consists of the following
components:
1 Main toolbar: Contains commands for performing general operations in the
Process Analyst, such as opening views, printing reports, and so on. You can
configure this toolbar to contain different items.
2 Pens: A Process Analyst pen represents your trend and/or alarm data. The
Process Analyst supports three types of pen: analog pen, digital pen, and
alarm pen. Each pen has its own graphical representation. You can configure
most pen properties during run time.
1
2
3
5
6
7 8
9
10
Chapter 1: The Process Analyst: An Overview 6
3 Panes: Panes are used to group pens visually in the Process Analyst and are
stacked vertically on the Process Analyst display. Every pen belongs to a
single pane. You can configure chart panes.
4 Chart background (not shown): The panes are drawn over the chart
background. Depending on the layout of the pens, the background may be
partially visible. You can configure the chart background.
5 Date/time axis: Located at the top of a pane, the date/time (horizontal) axis
displays the date or time (or both) of the data for the primary selected pen
within a pane. You can configure the axis.
6 Vertical axis: Analog pens have a vertical axis on the left-hand side of the
pane to indicate data values. You can configure this axis.
7 Cursor: A cursor allows an Operator to determine value at a given point in
time by dragging the cursor line to the point required. You can configure the
cursor.
8 Cursor labels: Display the value where the cursor intersects the trend value
line.
9 Navigation toolbar: Contains commands to allow an Operator to travel
forward or backward through trends, as well as other navigation-related
tasks. You can configure this toolbar to contain different items.
10 Object View: When displayed, the Object View appears under the
navigation toolbar and displays information about your Process Analyst
pens, such as name, color, scale, and so on. You can configure the Object
View.
Chapter 2: Using the Main Toolbar
The Process Analyst main toolbar is located above the top pane. The main
toolbar contains commands that allow you to perform general operations, such
as save and load Process Analyst views, print trend reports, add or remove pens,
display or hide cursors and labels, and so on.
Toolbar commands can be customized; for details, see Configuring Toolbars.
The table below describes the items that are included on the main toolbar by
default.
See Also Using the Navigation Toolbar
Item Description
Load View. Loads a saved view from file. For details, see Loading a view.
Save View. Saves a view to file. For details, see Saving a view.
Print. Displays the standard Windows Print dialog box for printing trend reports. For
details, see Printing and Exporting.
Copy to Clipboard. Copies visible pens to the Windows Clipboard. For details, see
Copying data to the Clipboard.
Export to File. Exports visible pens to an Excel-compatible file. For details, see Copying
data to file.
Add Pen. Displays the Add New Pen(s) dialog box for adding a pen. For details, see
Adding Pens.
Remove Pen. Deletes the currently selected pen from the trend display. For details, see
Deleting Pens.
Lock/Unlock Pens. Toggles the locking of pens. For details, see Locking/Unlocking Pens.
Show/Hide Points. Toggles the display of points representing where sample data was
recorded in the archive. For details, see Pens: An Overview.
Show/Hide Cursors. Toggles the display of cursors. For details, see Using Cursors.
Show/Hide Cursor Labels. Toggles the display of cursor labels. For details, see Using
Cursor Labels.
Toggle Object View. Toggles the display of the Object View. For details, see Using the
Object View.
Properties. Displays the Properties dialog box for configuring the Process Analyst control.
For details, see Configuring the Process Analyst.
Help. Displays the Process Analyst online Help.
Chapter 2: Using the Main Toolbar 8
Operator Command Reference
Chapter 3: Understanding Process Analyst
Pens
The Process Analyst pens allow you to analyze and compare both real-time and
historical data from trend and alarm servers.
See Also Pens: An Overview
Pen Types
Pens: An Overview
Process Analyst pens are drawn against time. Each pen has its own colored line
(and can contain other graphical elements). Sample markers (or points) are
drawn on the line to indicate where data was recorded in the archive. The style
of the line indicates the quality of the data; the style of the sample marker
indicates the compaction of the sample.
Data Compaction
Data compaction is the visual grouping of multiple data points into a single data
point when the data in the archive is too dense to be displayed as individual
data points for the selected time span.
Data is compacted by grouping raw samples together to form a multiple sample.
Sample compaction is indicated on the graph by using different sample markers.
For example, in the illustration below, the two sample markers that appear as
squares actually represent multiple raw samples. However, because the data
points in this view are too dense to display as individual points, the multiple
samples appear as one data point.
The following illustration zooms in on the second multiple sample, and shows
that what appeared to be a single raw sample actually consists of several raw
samples:
Chapter 3: Understanding Process Analyst Pens 10
The Process Analyst uses the following default point styles for single and
multiple samples:
Interpolated samples
Normally samples are only single or multiple. But there is a specific situation in
which an interpolated sample is used to correct a graph that only occurs with
event trends.
The frequency of the data stored in an event trend can vary dramatically; for
example, where several samples are within one display period, followed by no
samples for a long time. A multiple sample will be drawn with a value
calculated from the samples within the period. But the value after that period
will be whatever the last sample in the period was. So an interpolated sample is
added at the start of the next display period to correct the graph.
See Also Interpolation
Request modes
Because the Process Analyst Control makes requests for a range of data using a
display period, CitectSCADA needs to perform calculations on data if it
becomes too dense in order to calculate the value of a multiple sample. The
Process Analyst provides the following options for this calculation:
Average - The value will be an average of all the individual samples within
the multiple sample, as will the timestamp. This is the default calculation
method.
Maximum: The value will be the maximum value out of all the individual
samples within the multiple sample. The timestamp will be that of the
individual sample that was the maximum. The timestamp will be the
average of all the individual samples within the multiple sample.
Minimum: The value will be the minimum value out of all the individual
individual sample that was the minimum. The timestamp will be the
average of all the individual samples within the multiple sample.
Newest: The value will the latest arrived value out of all the individual
individual sample that was the newest. The timestamp will be the average of
all the individual samples within the multiple sample.
Sample compaction Point type
Single Ellipse
Multiple
Rectangle
Interpolated
Triangle (see Interpolated samples).
Data Quality
Process Analyst pens use the same quality system as CitectSCADA trend and
alarm data. There are four data quality states:
Good - Samples were recorded in the trend archive as good.
NA - When Citect is unable to obtain a sample, an N/A sample will be
recorded in the trend archive.
Gated/Disabled - For trends, when the driver determines a sample value is
invalid, a value of Gated is recorded in the trend archive. For alarms, this
data quality state indicates that the alarm has been disabled.
The Process Analyst uses the following default line styles to indicate data
quality:
Consider the following examples:
The line style indicating the data quality is configurable during run time and
design time; for details, see Configuring pen quality.
Date/Time (Horizontal)
Axis
All Process Analyst pens have a date/time axis, located at the top of the pane.
Quality Line style
Good
Solid
NA None
Gated
Dot
Data sample Description
This example shows several single samples. The third sample has a quality of N/A,
indicated by the break in the trend line.
Here the quality of the third sample is gated, indicated by the broken line connecting these
samples.
With multiple samples, the quality of the last sample in the group determines
how the line is drawn. Consider the following examples:
This example shows that the third sample is actually a multiple sample. The quality of the
third (multiple) sample and the next sample is N/A, again indicated by the break in the
trend line.
Here the quality of the third multiple sample is gated, again indicated by the broken line
connecting the samples.
The date/time axis displays time using the current locale format specified in
your computer date/time settings. If the millisecond component is required, it is
appended to the end in the format <xxx>ms. Since the local time zone is
determined from the current computer settings, these settings must be
configured accurately.
The date/time axis can also display data using the universal time coordinate
(UTC) format. You can switch between local or UTC time as you like (see
Configuring pen axes). If the current time is 10.00p.m. UTC, in the Sydney
(GMT+10) time-zone, local time will be 8.00p.m.
The date/time axis is divided into major and minor time intervals, which change
dynamically depending upon the time span. In the illustration above, the major
intervals are 1 minute apart, and the minor are 5 seconds apart.
Note the following:
When the axis time span is 1 minute or less, the format of the axis labels
includes milliseconds and the date is removed.
When the axis time span is 1 week or above, the time is removed and only
the date is displayed.
By default, the date/time axis displays a time span of 10 minutes; the major
intervals represent 5 minutes, and the minor intervals 30 seconds.
Daylight savings (local time)
The date/time axis can also accommodate daylight savings transitions. For
example, when entering daylight savings, the axis will indicate the transition as
11a.m., 12a.m., 1a.m., 3a.m., 4a.m., 5a.m., if this transition occurred at 2a.m.
Likewise, in the out transition, when 1 hour is removed from daylight savings
time, the axis will display 11a.m., 12a.m., 1a.m., 2a.m., 2a.m., 3a.m., 4a.m., 5a.m.
Now indicator
The Now indicator is a small white circle on the date/time axis that indicates the
current computer time based on the computers time settings.
The position of the Now indicator is refreshed according to the value specified in
the Display Refresh Date text box in the Process Analyst Control Properties
dialog box.
Note: If you have used the CitectSCADA trend page feature, note the following:
In CitectSCADA the right-hand side of the screen always represents Now (when
looking at real-time data). In the Process Analyst control, Now is represented
only by the Now indicator, which may be located anywhere on the trend display,
even off screen, since it is possible to scroll into the future, or back into the past.
You can scroll and scale the date/time time axis to interact with your Process
Analyst pens; for details, see Interacting with the Process Analyst. You can also
configure the date/time axis to suit your preferences; for details, see Configuring
pen axes.
Vertical (Value) Axis
The vertical (value) axis is located at the left-hand edge of the pane.
Like the date/time axis, the value axis consists of major and minor intervals, but
they represent value intervals rather than date and time. The intervals are
calculated automatically by the Process Analyst.
The value axis is shown only for analog pens; the axis displayed reflects the
values for the primary selected pen.
By default the vertical axis will use the engineering scale from the tag of the
selected pen. The vertical axis also supports autoscaling. When autoscaling is
enabled, the vertical axis automatically adjusts its limits to accommodate new
samples as they are added to each individual pen.
In this example, there are two panes, each of which has a differently scaled
vertical axis.
You can scroll and scale the vertical axis; for details, see Scrolling the Chart and
Scaling the Chart. You can also configure the appearance of the vertical axis; for
details, see Configuring pen axes.
Gridlines
The Process Analyst pens use gridlines as a visual guide to help an Operator
determine the value of trends. Major gridlines are solid lines; minor gridlines are
broken lines. Analog pens have vertical and horizontal gridlines; alarm and
digital pens only have vertical gridlines. The display of gridlines changes
dynamically according to the selected time span.
You can configure vertical gridlines at run time for all pen types; you can
configure horizontal gridlines for analog pens. For details, see Configuring pen
gridlines.
Pen Layout
You can are display pens in the Process Analyst by stacking or overlaying.
In stacked mode, a user-specified amount of vertical real-estate is allocated
to the pen, and with this, stacked pens are laid out under each other on the
pane, starting from the top of the pane under the date/time axis, like this:
Here, three pens (one analog and two digital) are stacked under each other.
Stacking applies to all types of pens.
In unstacked mode, pens are drawn on top of each other. The order in which
the pens were added to the pane governs the drawing order: the last pen
added is the topmost pen drawn. When a pen is selected, it is brought to the
front of any other pens displayed
Here, two analog pens are overlaid. You can also overlay digital and alarm
pens.
You can have any mix of stacked and unstacked pens on a pane.
Pen Types
The Process Analyst control supports three types of pen: analog pens, digital
pens, and alarm pens. Analog and digital pens are associated with trend tags;
alarm pens are associated with alarm tags.
Analog pens
The Process Analyst control typically uses analog pens to represent nonbinary
data. Only analog pens have a value (vertical) axis, which the data is plotted
against, as shown here:
Interpolation
Analog pens have two types of interpolation that allow you to specify how to
connect data samples on a trend line: straight and stepped:
Straight - a line is drawn directly between the points like this:
Stepped - the lines drawn always maintain the value of the previous sample
until a sample with a different value arrives, in which case a vertical line is
drawn:
The Process Analyst allows analog pens to be configured at run time and design
time. For details, see Configuring Pens.
See Also Interpolated samples
Digital pens
The Process Analyst control typically uses digital pens to represent binary data.
Values on the pen are clamped to a range of 0 to 1. Any value equal to or greater
than 0.5 is clamped to 1; all other values are clamped to 0. A fill color is used to
indicate where the data is 1, as shown here:
By default, the layout of digital pens is stacked. For details, see Pen Layout.
The Process Analyst allows the appearance of digital pens to be configured
during run time and design time. You can configure the trend line color, width,
and fill color. For details, see Configuring pen appearance.
Alarm pens
The Process Analyst uses alarm pens to graphically display the history of a
CitectSCADA alarm over time. The Process Analyst supports seven different
types of alarm pens.
The alarms on/off transition state changes and acknowledgements are all
represented graphically in the alarm pen display. To achieve this, the alarm pen
consists of three elements: the alarm state, on/off, and acknowledgement.
The diagram below illustrates how an alarm pen displays the information of an
alarm tag:
1 The alarm is turned on in its initial state and is unacknowledged.
2 The alarm changes to a different state, but is still unacknowledged.
3 The alarm is acknowledged.
4 The alarm is turned off.
Like other types of pen, alarm pens can represent variations in data quality and
data compaction.
1
2
3
4
on/off
The Process Analyst allows alarm pens to be configured at run time and design
time. For details, see Configuring alarm pens.
On/off
When an alarm is off, the alarm pen will draw the line low. When the alarm
transitions to on, the line is drawn high.
Alarm states
When an alarm transitions to on, it enters a particular state. The states of an
alarm are dictated by the type of CitectSCADA alarm tag. The Process Analyst
supports all CitectSCADA standard alarm types.
Note: For multi-digital alarms, the state descriptions are retrieved from the
CitectSCADA alarm record.
The Process Analyst uses a different color, shading style, and description to
represent each alarm state; these properties are configurable. For details, see
Configuring alarm pens.
Alarm acknowledgment
Process Analyst alarm pens can represent when alarms are acknowledged.
The Process Analyst indicates the period for which the alarm has been left
unacknowledged by drawing a line above the trend line. A new
unacknowledged period begins whenever the alarm transitions to an on
state.
The unacknowledged period ends when an Operator acknowledges an
alarm. The Process Analyst identifies this by placing a sample marker to
indicate the exact time the alarm was acknowledged, and by drawing an
unacknowledged line down to that sample marker, as shown here:
acknowledgements
unacknowledged periods
acknowledgement
marker
Alarm types
The Process Analyst uses the following types of alarm pen:
For multiple samples in an alarm, the alarm state value is the last recorded value
in the group.
Alarm type Alarm pen representation
Digital
Analog
Advanced
Argyle Analog
Multi-digital
Timestamped
Timestamped analog
Timestamped digital
Chapter 4: Interacting with the Process
Analyst
This section discusses how to interact with the Process Analyst.
See Also Pen Selection
Locking/Unlocking Pens
Scrolling the Chart
Scaling the Chart
Using the Navigation Toolbar
Using Cursors
Using Cursor Labels
Using the Right-click Menu
Understanding Mouse Pointers
Adding and Deleting Pens
Viewing Pen Details
Pen Selection
Each pane on the Process Analyst can have one selected pen. The axes that are
displayed on a pane are that of the selected pen. The last pen selected across all
panes is referred to as the primary selected pen.
You can select a Process Analyst pen in several ways:
By clicking on the pens graphical elements (i.e., the pen line).
If the pens are stacked, by clicking the background under the pen line.
By selecting the pen in the Object View.
The selection of a pen is indicated by a subtle halo effect surrounding the pen
line. In the example shown here, the top (green) pen is selected, indicated by the
halo surrounding the pen:
Chapter 4: Interacting with the Process Analyst 20
Note that the halo does not appear if there is only one pen on the pane. Selecting
a pen on a pane also causes the same pen to be highlighted in the Object View.
Selecting a pen causes that pen to be drawn in front of other pens on the pane.
Locking/Unlocking Pens
By default, the Process Analyst locks together the time span and position in time
(horizontal axis) of all pens. However, you can unlock the pens, allowing the
pens to be displayed across different positions in time and/or time spans.
For example, you could unlock pens to compare a previous months data for a
tag with the data for this month. You would do this by adding two pens to a
pane that represent the same tag, then unlocking the pens, and adjusting the
time positions for each pen as required.
To control pen locking and unlocking, you use the Lock/Unlock Pens button on
the main toolbar.
This option is also available on the right-click (context) menu.
Locking and unlocking has the following behavior:
When pens are locked, all time-related operations are applied to all pens.
When pens are unlocked, all time-related operations are applied to the
primary selected pen.
Synchronization applies to all pens regardless of their being locked or
unlocked.
When transitioning from locked to unlocked, the time span and position in time
of all pens are synchronized to match that of the primary selected pen.
Scrolling the Chart
The Process Analyst allows you to scroll through data in both the horizontal and
vertical directions by dragging the mouse or spinning the mouse wheel.
To scroll by dragging:
1 Click and hold down the left mouse button on the pen (or background) that
you want to scroll.
2 Drag the mouse in the direction you want to scroll:
Horizontal axis: drag right to move backward in time, drag left to move
forward.
Vertical axis: drag up to scroll down the axis, drag down to scroll up the
axis.
3 Release the left mouse button to complete the scrolling.
To scroll by using the mouse wheel:
1 Click the pen or background that you want to scroll.
2 Spin the mouse wheel in the direction you want to scroll:
Horizontal axis: spin up to move backward, spin down to move
forward.
Vertical axis: spin up to scroll up the axis, spin down to scroll down.
You can disable scrolling in the horizontal direction, the vertical direction, or
both by using the Property dialog box or the right-click (context) menu; see
Configuring pen axes and Using the Right-click Menu for details.
The Process Analyst indicates whether scrolling is enabled or disabled by
displaying a different-shaped mouse pointer; for details, see Understanding
Mouse Pointers.
Scaling the Chart
The Process Analyst allows you to change the scale of the data in both the
horizontal and vertical direction by dragging the mouse or spinning the mouse
wheel.
To scale the data by dragging:
1 Click and hold down the left mouse button on the axis that you want to
scale.
2 Drag the mouse in the direction you want to scale:
Horizontal axis: drag left to expand the scale, drag right to shrink.
Vertical axis: drag up to expand the scale, drag down to shrink.
3 Release the left mouse button to complete the scaling.
To scale by using the mouse wheel:
1 Click the axis that you want to scale.
2 Spin the mouse wheel in the direction you want to scale:
Horizontal axis: spin up to shrink the axis, spin down to expand.
Vertical axis: spin up to expand the axis, spin down to shrink.
You can disable scrolling in the horizontal direction, the vertical direction, or
both by using the Property dialog box or the right-click (context) menu; see
Configuring pen axes and Using the Right-click Menu for details.
The Process Analyst indicates whether scaling is enabled or disabled by
displaying a different-shaped mouse pointer; for details, see Understanding
Mouse Pointers.
Using the Navigation Toolbar
Using the navigation toolbar you can:
Specify a start time and end time.
Select predefined time spans.
Lock time spans on the display.
Navigate backward or forward through your data.
Synchronize all pens to Now.
Toggle autoscrolling of the display.
Zoom in on or out of data.
Undo the last zoom operation.
Toggle between Zoom mode and normal mode.
Set nonstandard time spans.
Edit the vertical (value) scale.
Specifying a start time
and end time
You can specify a start time and an end time for the trend display by using the
date/time pickers. The start time picker is located on the left-hand side of the
navigation toolbar, the end time picker on the right.
The date/time picker formats the date and time using the settings obtained from
your computer for the currently logged in user. The date/time picker displays
time in 24-hour format (dd/mm/yyyy hh mm:ss nnn) where:
dd represents days
mm represents months
yyyy represents years
hh represents hours
mm represents minutes
ss represents seconds
nnn represents milliseconds (added automatically to the time)
To change the date or time in the date/time picker:
1 Click the element of the date or time you want to change in the start time
picker or the end time picker.
2 Do either of the following:
Type in a time explicitly.
Press the Up arrow key or Down arrow key to increment or decrement
the value respectively.
Note: You can use the Left arrow and Right arrow keys to move between
time elements.
Working with Daylight Savings
To indicate whether the time in the time picker control is Standard time or
Daylight Savings time, the clock to the left of the control has a shaded segment if
the time is in a Daylight Savings period. When in Standard time, the clock does
not have a shaded segment.
For example, this icon appears when the time pickers value is within the local
Daylight Savings period.
This icon appears when the time pickers value is within the local Standard time
period.
If the Daylight Savings transition involves duplicate hours, you can use the spin
controls (or Up and Down arrow keys) to select the hour you want.
Note: In order for the Process Analyst to be able to indicate that Daylight
Savings is in effect, the Automatically adjust clock for daylight saving changes
option on the Date and Time Properties dialog box must be enabled, as indicated
below:
See Also Daylight savings (local time)
Shifting and fitting time units
You can manipulate the start time and end time by using special keyboard
shortcuts. Using these shortcuts, you can do the following:
Shift by unit
Fit to unit
Shift by unit Shifting date or time by unit allows you to change the opposite date/
time element to the one selected by the corresponding date or time component.
For example, if you shift by unit the month time element in the start time, the
month time element in the end time increments by one month exactly, including
days, minutes, and seconds. This also works for months that have different end
days.
To shift by unit:
1 Press and hold down the Shift key.
2 Click a date or time element in the date/time picker. The opposite time
picker changes by the base time amount of the selected time element.
Fit to unit Fitting date or time to unit allows you to synchronize the selected time
element to the zero position of that time element in the start time and end time.
For example, an Operator clicks on the hh time element of the Start picker, which
shows 19:30:05.123. After Ctrl + click, the Start hour time element shows
19:00:00.000, and the End time element shows 20:00:00.000. Now the time span
represents exactly one hour, synchronized on the hour.
To fit to unit:
1 Press and hold the Ctrl key.
2 Click a date or time element in the date/time picker. Both the start time and
end time element are synchronized to zero based on the date/time element
selected.
About time spans
The time span of the trend display is the difference between the start time and the
end time. The start time appears on the left-hand side of the trend display, the
end time on the right. The Span Picker (shown below) indicates the current span
being used; it also contains commonly used predefined time spans. Selecting a
time span adjusts the start time, leaving the end time as-is.
See Also Span Lock
Span Lock
When the time span is locked and the start time and/or end time picker changed,
the current time span is maintained. If the time span is unlocked, the time span
is not maintained when any of the time pickers are changed.
By default, the span is locked. You can toggle span locking on or off by using the
Span Lock button.
See Also About time spans
Navigating time
The navigation controls allow an Operator to navigate backwards or forwards
through time. The amount of time moved depends upon the time currently
selected in the Span Picker. For example, if 10 minutes is selected in the Span
Picker and Back One Span is clicked, the display moves back 10 minutes into
the pens history.
The following navigation controls are available:
Navigation control Description
Back One Span - moves back one time span.
Synchronize to Now
The Synchronize to Now command synchronizes all pens such that the date/
time reflects Now, which is positioned on the right-hand edge of the screen.
Now is calculated using the current system time.
The Synchronize to Command is also available from the right-click (context)
menu.
See Also Now indicator
Toggle Autoscrolling
When Autoscroll is turned on, as time passes the position in time of all pens
moves by the same amount to keep pace; by default, the display is updated
every second. The refresh rate of the display can be controlled by using the
Display Refresh Rate property.
When Autoscroll is turned off, as time passes the position in time of all pens
remain fixed.
By default, Autoscroll is on. You can toggle Autoscrolling on or off by using the
Toggle Autoscrolling button.
Using the navigation controls, including the Time Span picker, causes
Autoscrolling to be turned off
The Autoscroll command is also available from the right-click (context) menu.
Zoom In/Zoom Out
Use the Zoom In 50% and Zoom Out 50% commands like this:
Note: The midpoint of each axis is maintained during these zoom operations.
Back Half a Span - moves back half a time span.
Forward Half a Span - moves forward half a time span.
Forward One Span - moves forward one time span.
Navigation control Description
Command Icon Description
Zoom In 50% Zooms in on the displayed data, halving the span of both axes.
Zoom Out 50% Zooms out of the displayed data, doubling the span of both axes.
Undo Last Zoom
Undo Last Zoom allows you to undo the last zoom operation, returning the
display to the previous state.
Toggle Box Zoom
The Toggle Box Zoom button switches between Box Zoom mode and normal
interaction mode. In Box Zoom mode, you can define an area of the chart to
zoom in on for more detail.
To use Box Zoom:
1 Select the pen to zoom in on.
2 Click Toggle Box Zoom on the navigation toolbar.
The cursor changes to a cross.
3 Click and drag the bounding box to enclose the part of the data you want to
zoom in on, as shown below.
4 Release the mouse button. The display changes to a close-up of the selected
data.
5 To exit Zoom mode, click the Toggle Box Zoom button.
Depending on whether the pens are locked or unlocked, the Toggle Box Zoom
commands works differently:
For locked pens, the zoom is applied to all pens in the horizontal date/time
axes. If an analog pen is being zoomed, the zoom is applied to the vertical
(value) axis of all non-autoscaled analog pens in the pane in which the zoom
box was initiated.
For unlocked pens, the zoom is applied only to the selected pen in both the
date/time and vertical (value) axes. The value axis is only affected if
autoscale is off.
Note: Vertical zoom is only applied to analog pens, since it has no effect with
alarm or digital pens.
Edit Span
Click the Edit Span button to display the Edit Span dialog box, which allows
you to set non-standard time spans.
To edit a time span:
1 Click Edit Span on the navigation toolbar. The Edit Span dialog box
appears.
The fields provided are: w = weeks, d = days, hr = hours, min = minutes, sec
= seconds, and ms = milliseconds.
2 Enter a New span. Click the element of the time span that you want to
change, then either type in a new value, or use the Up arrow or Down arrow
to specify a new value. You can use the Right arrow and the Left arrow key
to move between the time elements.
3 Click OK. The new time span is applied.
Edit Vertical Scale
The Process Analyst allows Operators to edit the vertical scale of a selected
analog pen to display more appropriate values, if required. The vertical scale for
digital or alarm pens cannot be edited.
To edit the vertical scale:
1 Click Edit Vertical Scale on the navigation toolbar. The Edit Vertical Scale
dialog box appears.
2 Click the Limits or Engineering Scale option. The Limits values displayed
are the current values used by the vertical scale. The Engineering Scale
values are obtained from the trend tag.
3 Enter a new Minimum value and Maximum value, and then click OK.
Reset to Default Span
Use the Reset to Default Span button to reset the time span to the default time
span of the primary selected pen. The default span can be configured by using
the Property dialog box. For details, see Configuring pen axes.
See Also Configuring Defaults
Pen Selection
Using Cursors
A cursor enables an Operator to determine the value of a pen at a given point in
time by dragging the cursor to the specific point on the pen line. A cursor label is
used to display the value.
An Operator can define many of the properties of cursors and cursor labels. For
details, see Configuring Cursors.
In this example the cursor intersects three pens; the cursor labels (the yellow
rectangles) display the corresponding pen values.
To move a cursor, drag the cursor line left or right. As the cursor moves, the
cursor labels move with the cursor and are updated continuously, reflecting the
position of the cursor.
Note: The cursor extends across all configured panes.
A line connects the cursor label to the associated pen line. The line has three
main states:
State Style Example
Intersection within pen data Line
Intersection before or after pen
data
Line with indicator
No intersection and no data Invisible line
To show/hide a cursor:
Click Show/Hide Cursor on the main toolbar. You can display additional
cursors by using the Properties dialog box.
You can display as many cursors as you want. To add a cursor, right-click the
root item (Process Analyst View) in the property tree in the Properties dialog
box, and choose Add Cursor.
Using Cursor Labels
Each cursor has one cursor label for each pen displayed. The cursor label
displays the value of the pen at the point where the cursor intersects with the
pen data.
To display cursor labels:
Click Show/Hide Cursor Labels on the main toolbar.
This table summarizes how to use cursor labels:
The cursor label displays the following information:
The fields are displayed in the cursor label using the order defined above using
the format specified for the vertical axis. For example, if your vertical axis format
is km/h, the label reads <value> km/h.
Task Description
Move a cursor label Click the cursor label and drag the label to a new location.
Change the size of cursor labels Click the cursor label you want to resize. Place the mouse cursor on one
of the sizing boxes, and drag the label to the new size. If you drag the
corner of the label, the label text resizes to an optimal size for the label.
Lock or unlock the cursor labels Click the Lock/Unlock Cursor Labels. When on, this command causes
cursor labels to be frozen in the position.
Cursor field Applies to Description
Pen Name All Pen types Displays the non-unique Process Analyst pen name
Value/Quality All Pen types Displays the value of the pen at the point the cursor intersects with the
pen data
Date-Time Stamp All Pen types Displays the date/time stamp at the point the cursor intersects with the
date/time axis.
Alarm Sample
Comment
Alarms Comment bound to an alarm sample.
The label displays the following values when the quality of the data is not good:
The label value can also contain a directional indicator that functions as follows:
Alarm label value
The alarm label value has the following format:
state [acknowledgement]
where state refers to the alarm state at the point of intersection (see Alarm pens)
and acknowledgement refers to the acknowledged state of the alarm at the point of
intersection; i.e., Acknowledged or Unacknowledged.
Using the Right-click Menu
Use the right-click (context) menu to quickly access frequently used commands.
This menu is context-sensitive, providing relevant commands for different
regions of the display. The right-click menu appears when you click any of the
following regions:
Horizontal axis
Vertical axis
Background
Pen
The Properties command is always available on the right-click menu; this
command displays the Properties dialog box. For details, see Using the Process
Analyst Properties Dialog Box.
Cursor value Description
NA At the point of intersection the pen has no available data for display.
Gated At the point of intersection the pens data has been gated.
Disabled At the point of intersection the alarm tag of the pen was disabled.
Cursor value Description
<value> -> The cursor is to the left of the first available sample for this pen.
<- <value> The cursor is to the right of the last available sample for this pen.
Understanding Mouse Pointers
When using the Process Analyst, the mouse pointer changes shape to indicate
the operations you can perform at that time.
Adding and Deleting Pens
Pens can be added to (or removed from) any pane. The Process Analyst allows
Operators to search the trend tags and alarm tags that are defined on their trend
and alarm servers and add pens that represent these tags to the current trend
display.
Mouse pointer Region Description
Pen line The mouse pointer looks like this when the pointer is on a pen. Clicking the
mouse at this point selects the pen.
Pen line/pen
background
The mouse pointer looks like this when the mouse is over a pens
background and both horizontal and vertical scrolling are enabled. Clicking
and dragging at this point results in the free movement of the pen. Scrolling
the mouse wheel results in horizontal-only movement.
Horizontal
axis
The mouse pointer looks like this when the pointer is on the horizontal axis
and horizontal scaling is enabled. Clicking and dragging (or scrolling the
mouse wheel) will result in the axis being scaled.
Pen line/pen
background
The mouse pointer looks like this when the pointer is on the horizontal axis
and only horizontal scrolling is enabled. Clicking and dragging (or scrolling
the mouse wheel) will result in the axis being scrolled.
Vertical axis The mouse pointer looks like this when the pointer is on the vertical axis
and vertical scaling is enabled. Clicking and dragging (or scrolling the
mouse wheel) will result in the axis being scaled.
Vertical axis The mouse pointer looks like this when the pointer is on the vertical axis
and only vertical scrolling is enabled. Clicking and dragging (or scrolling the
mouse wheel) will result in the axis being scrolled.
Box Zoom
mode
The mouse pointer looks like this when Box Zoom mode is enabled. See
Toggle Box Zoom.
Adding Pens
You use the Add New Pens dialog box to add a new pen to your trend display.
To display the Add Pens dialog box, click Add Pens on the main toolbar.
To add a new pen:
1 Select the Type of server you want to search: Trends or Alarms.
2 Type in a Filter to apply to the search (optional).
If you leave the Filter text box blank, all tags of the selected server type will
be retrieved. If you leave the Filter text box blank, all tags of the selected
server type will be retrieved. The filter has basic wildcard and Boolean
search functionality. You can use the keywords AND, OR and NOT with
wildcard strings, as well as group Boolean terms using parentheses. For
example, entering 'L*' returns all tags beginning with the letter L. Entering
L* OR H* will find all tags beginning with L or H. More complex
examples include L* OR (H* AND NOT *G). This would return all tags that
start with L or any that start with H, but do not end in G.
3 Click Search. The search results are returned in the Search Results list. The
results are not sorted: the tags appear in the order they were configured in
CitectSCADA.
The Search Results list displays a maximum of 100 entries at a time. If your
search returns more than 100 results, use the First, Prev, Next, and Last
buttons to navigate your search results.
4 Select one or more tags from the Search Results list. You can use the Ctrl
and/or Shift keys to select multiple tags.
5 Select the destination pens to Add Add pens to. Pens can be added to any
existing pane, or to a new pane.
6 Select a Pen Type. A trend tag can be represented by an analog or digital
pen. An alarm tag can be represented by an alarm pen only.
7 Select how to resolve the pen name:
Comment - applies the tag comment as the pen name. Note that if the
tag does not have a comment specified, a name is automatically
generated.
Tag - applies the tag name as the pen name.
Auto -applies an automatically generated name to the pen using the
format Pen<X> where X is an incremented number, starting with the
first available number.
8 Click Add. This moves all the selected items in the Search Results list into
the Selected Items list. The Selected Items list contains all the tags that will
be added as pens to the Process Analyst. You can perform multiple searches
to add tags into the Selected Items list.
Note: To remove a tag from the Selected Items list, highlight the item you
want to move, and then click Remove.
9 To view details about a selected tag, click Show Detail. The Pen Detail box
appears, showing defined information for the selected tag.
10 Click OK. Your selected tags appear on the trend display as pens.
See Also Deleting Pens
Deleting Pens
Operators can delete pens from the trend display at any time.
Note: Deleting a pen is different than hiding the pen from display by using the
Visibility check box in the Object View. For details, see Using Object View.
To remove a pen:
1 Select the pen you want to delete.
2 Click Remove Pen in the main toolbar. The pen is deleted from the display.
See Also Adding Pens
Viewing Pen Details
You can use the Pen Details box to view tag properties information for a selected
pen. You access this box from the Add Pens dialog box.
To view pen details:
1 Click Add Pens. The Add Pens dialog box appears.
2 Navigate to the tag you want to view details for. For details on searching
tags, see Adding Pens.
3 Select the tag in the Selected Items list, and then click Show Detail. The Pen
Details dialog box appears, showing the system information for the selected
tag.
Chapter 5: Using the Object View
The Object View provides a structured view of the pens displayed in the Process
Analyst. You use the Object View to view information about the pens on the
chart, along with information about associated tags.
See Also Object View Basics
Using Object View
Configuring the Object View
Object View Basics
The Object View displays a hierarchically arranged view of the panes and pens
on the chart, in the Object Tree column. The Object View lists information about
each pen. When displayed, the Object View is located under the navigation
toolbar.
The Object View (as it appears in a default configuration) is shown below; your
Object View might look different depending on how it has been customized in
your system.
By default, all items in the Object View are expanded (that is, all pens for all
panes are shown). Clicking a pen in the Object View selects that pen. There is
always one pen selected in each pane; in the example above, the primary
selected pen is highlighted in blue; all other selected pens are highlighted in
gray.
See Also Pen Selection
The Object View displays the following items:
Icon Object
Analog pen
Chapter 5: Using the Object View 38
The check box controls whether the pen is visible on the chart. The gradient-
filled color box to the left of the pen name indicates the pens line color as it
appears on the chart.
The Object View always mirrors the items that are displayed on a chart. For
example, if you add a pane to the chart, a new pane is added simultaneously to
the Object View. Similarly, if a new pen is added to or deleted from a pane, or if a
pens properties are changed, these changes are reflected in the Object View.
The table below shows the predefined default columns, which are displayed in
addition to the object tree. These columns are arranged by default from left to
right in the Object View.
You can configure the Object View to display other predefined columns that
show different information about your pens; for details, see Configuring the
Object View.
Using Object View
The table describes how to perform basic functions with Object View.
Digital pen
Alarm pen
Pane
Column Description
Zero Scale Vertical axis start position of the pen.
Full Scale Vertical axis end position of the pen.
Engineering Units Engineering units associated with the pen.
Task Description
Toggle the display of Object View on or off Click Toggle Object View on the main toolbar.
Change the size of Object View Drag the splitter bar that is located between the chart area and
the Object View up or down.
Expand or collapse a tree node in the
Object Tree column
Either click the (+) box to expand the node or the (-) box to
collapse the node; or double-click the item to toggle between
expanded and collapsed states. This does not affect the display
of panes in the chart.
Select a pen Click the pen in the Object View table. Selecting a pen in the
Object View gives the focus in the chart to the selected pen, and
vice versa. You can only select one pen per pane at a time (you
cannot select a pane).
Icon Object
See Also Configuring the Object View
Display or hide a pen Click to clear the check box to hide the pen; click the check box
again to display the pen.
Dynamically change the width of a column
during display
Drag the column divider left or right.
Note: You can quickly resize a column to fit the size of the
widest item in a column by double-clicking a column separator.
To resize the column back to its original size, double-click the
separator again. You can also configure the width of a column
via the Process Analyst Properties dialog; for details, see
Configuring the Object View.
Task Description
Chapter 6: Printing and Exporting
You can print detailed reports of your Process Analyst trends for management
reports and other purposes. You can configure Process Analyst reports to
include other print options designed to maximize the business value of your
reports. You can also export pen data to the Windows Clipboard or to Microsoft
Excel.
Note: For details about general print options in Windows, refer to your
Windows documentation.
See Also About Process Analyst Reports
Configuring Process Analyst Report Options
Exporting Pen Data
About Process Analyst Reports
Process Analyst reports are formatted automatically by the system to make
optimal use of the paper size and orientation. For example, if the page is small
and the report contains a lot of information, the reports will use a smaller font to
try to fit the information to the page. For larger pages, a larger font will be used.
Reports use an Arial font between 8-14 points.
Chapter 6: Printing and Exporting 42
A typical Process Analysis report looks like this:
This example shows a report of a chart titled Citect Process Analyst; the chart has
only one pane, which contains three analog pens. The topmost pen in the report
legend is highlighted, indicating that this pen is selected; consequently, the axes
shown in the report are associated with this pen. You can see that this pen is
selected in the chart by the halo effect surrounding the pen. The color boxes on
the left-hand side of the legend help you to distinguish between the pens.
To print a report:
Click Print. The Print dialog box appears. Click the Print button, or choose
Print from the right-click (context) menu.
Configuring Process Analyst Report Options
You can configure Process Analyst reports to contain such things as specific
items on a report legend (pen names, durations, engineering units, for example).
You can also include header information and page numbers.
You use the Print dialog box to configure Process Analyst reports. To display the
Print dialog box, click Print on the main toolbar. After configuring your reports,
click Print on the General panel of the Print dialog box to print your report.
See Also Setting up report legends
Setting up report options
Setting up report
legends
You can configure your reports to include report legends. The information in the
report legend is derived from the information properties of the underlying tag
that is associated with a pen. If there are no information properties defined for a
tag, this information isnt available for a legend.
You set up your report legends by using the Legend panel of the Print dialog
box.
To set up a report legend:
1 In the Print dialog box, click the Legend tab. The Legend panel appears.
2 The panel shows, by default, the Pen Options, Statistical Analysis Options,
and Cursors lists (if there is a cursor currently displayed on the chart). The
options available to you might differ from the ones shown here.
3 Select the check box of the Pen Options you want to include in your report.
For details about these options, see Configuring the Object View.
4 Select the Statistical Analysis Options you want to include. Note that this
section is available only if the chart contains at least one analog or digital
pen.
Minimum - causes the minimum value from cache to be returned. Note
that this value might not be a real logged sample if the sample found is a
multiple calculated sample.
Maximum - causes the maximum value from cache to be returned. Note
that this value might not be a real logged sample if the sample found is a
multiple calculated sample.
Average - uses time-weighted averaging to determine the average for
both stepped and interpolated lines. This means that if a trend stays at a
value of 10 for 1 hour and then spikes quickly at a value of 50 for a
minute, the average will not be significantly affected.
5 Select the Cursors you want to include.
6 If you want to include a report legend, make sure the Include Legend check
box is selected.
7 Click Apply.
Setting up report
options
You can configure your reports to include a report header, which can include a
report title and comment. For multiple-page reports, you can include page
numbers, which appear at the bottom of each report page.
You set up your report options by using the Report panel of the Print dialog box.
To set up report options:
1 In the Print dialog box, click the Report tab. The Report panel appears.
2 In the Header Information area, type a Title for the report. If necessary,
include a Comment. Comments are printed under the report title on each
report page.
3 To include a header, make sure the Include Header check box is selected.
4 To include page numbering, make sure the Include Page Numbers check
box is selected.
5 Click Apply.
Exporting Pen Data
You can export Process Analyst data for pens that are visible to either the
Windows Clipboard (by using the Copy to Clipboard command) or to an
Microsoft Excel-compatible file (Copy to File).
When you export data, it is exported using a standard format of columns that
represent time, milliseconds, and then a column per pen, as shown here:
Export functionality doesnt simply return the sample markers displayed on the
graph. Instead, it exports an interpolated value per display period from the start
time to the end time of the pen. The display period can be calculated by dividing
the time span of the pen by the IProcessAnalyst.Number of
Samples[Property][Get/Set] property.
Before exporting the data, the Process Analyst sorts all the timestamps for all
pens from the earliest to the latest sample. When the pens are unlocked and have
different time spans, the data for each pen might have different timestamps. As
each entry is added to a row in the table, the value of the pen at that particular
timestamp is exported. If a pen does not have a sample for that timestamp, the
column for that pen is left blank.
An export will also write values of NA, GATED and all alarm states as localized
text when required.
Pen columns use the format <pane>-<pen> where pane is the name of the pane
that contains the pen, and pen is the name of the pen.
See Also Copying data to the Clipboard
Copying data to file
Time Milliseconds Pane1-Pen1 Pane1-Pen2 Pane1-Pen3
15/06/2004 01:17:25 100 NA 10 Off
15/06/2004 01:17:26 100 1 20 Low [Unacknowledged]
15/06/2004 01:17:27 100 Low [Acknowledged]
15/06/2004 01:17:28 100 3 25 Low [Acknowledged]
Copying data to the
Clipboard
Copying pen data to the Clipboard allows you to paste the data into another
application, such as an Excel spreadsheet.
To copy data to the Clipboard:
1 Select the pen(s) you want to copy data for.
2 Click Copy to Clipboard, or select Copy from the right-click (context) menu.
Copying data to file
Copying pen data to Microsoft Excel allows you to manipulate the data using
spreadsheet application capabilities.
Note: The Time column is an encoded (OLEDATE) double value, which holds
the date and time in seconds in local time. When exporting pen data to Excel,
you should change the format of the Time column to dd/mm/yyyy hh:mm:ss so
that the time is displayed correctly. Because the OLEDATE data type excludes
milliseconds, a separate column is provided, which exports the millisecond
component for each timestamp.
To copy data to file:
1 Select the pen(s) you want to copy data for.
2 Click Copy to File. The Save As dialog box appears.
3 Enter a filename and click Save. The data is exported in a delimited format.
4 Open the file you just created, and complete the Text Import Wizard.
Chapter 7: Configuring the Process Analyst
Many of the Process Analyst controls properties can be configured at run time
to allow an Operator to customize the control to suit their working preferences.
To configure the Process Analyst, you use the Properties dialog box.
See Also Using the Process Analyst Properties Dialog Box
Configuring Chart-wide Properties
Configuring Chart Panes
Configuring Pens
Configuring Cursors
Configuring Defaults
Configuring Toolbars
Working with Views
Using the Process Analyst Properties Dialog Box
You use the Process Analyst Properties dialog box to configure Process Analyst
views. You can also configure chart-wide properties.
The Properties dialog box has three tabs, Main page, Toolbars, and Object View.
Chapter 7: Configuring the Process Analyst 50
Main page
You use the Main page of the Properties dialog box to configure general
properties and access the server path properties. The Main page looks like this:
The list on the left-hand side contains the property tree, a hierarchical list of
Process Analyst interface components. Selecting an item displays the property
controls for that component on the right. The pens in the property tree indicate
the information that the pen is trending.
Using the property tree right-click menu
Right-clicking an item in the property tree displays the shortcut menu for that
item, as shown below.
The tasks you can perform vary depending on your privilege level: if you dont
have the required privilege at run time to perform an action, that control is
disabled/removed. For example, the right-click menu removes the Add Pen
option at run time if you dont have the privilege to add a pen. Commands that
are unavailable appear grayed-out. The right-click menu contains the
following options:
Use the Main page for the following:
Configuring Pens
Configuring Cursors
Toolbars
You use the Toolbars page to configure the main toolbar and navigation toolbar.
Operators and Users can configure the toolbars at run time and design time. Use
the Toolbars page to configure the toolbars; for details, see Configuring Toolbars.
Object View
You use the Object View page to configure the Object View. Operators and Users
can select (at run time and design time) the columns they want to display, as well
as change the column width and display order. Users can define new columns
and edit existing columns at design time.
Use the Object View page for the following:
Creating or Editing Object View Columns
You use the Main page of the Process Analyst Properties dialog box to configure
chart-wide properties. Select Process Analyst at the top of the property tree to
display the Process Analyst properties page. This page contains two tabs,
General and Server Paths, used to modify the following configurations:
Configuring general properties
Right-click this item... Actions
Chart Add Pane - add a new pane.
Add Cursor - add a new cursor.
Pane Add Digital - adds a new digital pen.
Add Analog - adds a new analog pen.
Add Alarm - adds a new alarm pen.
Note: After adding a pen from this menu, configure the data connection by
clicking the Connection tab and typing the name of the tag into the Tag text box.
Delete - deletes the pane.
Pen Delete - deletes the pen.
Cursor Delete - deletes the cursor.
Configuring server paths
Configuring general
properties
You can configure general properties such as the background color of the chart,
the refresh rate, data request rate, number of samples for pens, and specify
whether chart pens should be locked. The Administration area indicates the
privilege setting for the current Operator.
To configure general properties:
1 Click the General tab on the Main page.
2 Click the color swatch and select a Background color.
3 Specify a Display refresh rate.
This value determines the rate at which the display data is refreshed on the
display; it also controls how often the position of the Now indicator is
refreshed. This control is disabled if you do not have appropriate privilege.
The default value is 1000 milliseconds. The permitted range is between 10
milliseconds to 60,000 milliseconds. Note that specifying a rate below 500 is
not recommended if your chart contains many pens, since this may
negatively affect performance.
4 Specify a Data request rate.
This value determines the maximum frequency of data requests. The Process
Analyst internally determines when a request is required, but you can use
this property to cap the Process Analysts performance.
This control is disabled if you do not have appropriate privilege. The default
value is 1000 milliseconds. The permitted range is between 10 to 60,000
milliseconds. Note that this property affects trend server performance.
5 Specify a Number of Samples.
This specifies the date/time axis span of each pen in number of samples. This
control is disabled if you do not have the appropriate privilege. The default
value is 300. The permitted range is between 10-5000. Also see Exporting Pen
Data.
Note: The chart has a minimum resolution of one millisecond per sample. If
the time span is reduced enough so that the number of samples exceeds the
number of milliseconds in the time span, the number of milliseconds in the
time span is used instead of the number of samples.
6 Select the Lock pens check box to lock your pens, or clear the check box to
turn off pen-locking. For details on pen locking, see Locking/Unlocking
Pens.
7 Click Apply.
Configuring server
paths
You can configure the file server locations that the Process Analyst uses to load
and save Process Analyst views, and displays the current Citect run path if the
Process Analyst is embedded in a running CitectSCADA system. This command
is disabled at run time if you do not have the appropriate privilege. For details
about saving and loading views, see Working with Views and Process Analyst
View Synchronization.
The Process Analyst uses four possible storage locations:
User - maps to the client machines logged-in users My Documents folder.
This option is available for any possible privilege and CitectSCADA mode.
Primary - User-definable.
Secondary - User-definable.
Local - displays the current CitectSCADA run path (read-only). This text
box only gets populated when the Process Analyst is running in
CitectSCADA V6.0 or higher. This path is an Analyst Views subdirectory
under the CitectSCADA current Run directory.
To configure server paths:
1 Click the Server Paths tab on the Main page.
2 Enter the location of the Primary file server.
3 Enter the location of the Standby file server (optional). This specifies the file
server to use if the primary file server is unavailable.
4 Click Apply.
You use the Properties dialog box to configure chart panes. After adding a pane,
you can configure its size relative to other panes, as well as select a different
color. All pane properties can be configured during run time.
To add a pane:
In the property tree of the Properties dialog box, right-click the Process
Analyst view item at the top of the tree, and then select Add Pane. (To
remove a pane, right-click a pane in the tree and choose Delete.)
To configure the chart pane:
1 In the property tree of the Properties dialog box, select the pane you want to
configure. The properties for that pane appear.
Note: To configure defaults for your panes, select the Pane item in the
Default Settings node of the property tree, not a specific pane.
2 Click the color swatch and select a new Background color.
3 Select a Height option:
Variable - Automatically calculates the pane height based on the value
in the Size control. For example, if the chart contains two panes,
selecting this option and using a Size value of 110 will set this pane to
110% of the size of the other pane in the chart. Note that fixed height
panes have precedence of variable-size panes.
Fixed - Sets the pane height to the value specified in the Size control.
4 Specify a Size for the pane.
5 Click Apply.
Configuring Pens
The Process Analyst allows you to configure your pens to suit your preferences.
Pen configuration tasks are performed by using the Properties dialog box, which
is used for:
Configuring pen appearance
Configuring pen gridlines
Configuring pen axes
Configuring pen quality
Configuring the pen data connection
Configuring cursor labels
Configuring pen
appearance
You use the Process Analyst Properties dialog box to configure the appearance
of pens. Pen appearance can be configured at run time by Operators and Users
(and at design time by Users).
For details about pen appearance, see Pen Types.
Note: To configure default settings for pen appearance, select Analog, Digital,
or Alarm in the property tree under Default Settings, and then complete the
procedure below for the type of pen you want to configure.
Configuring analog and digital pens
Configuring the appearance of analog or digital pens involves selecting the line
color, stack property, line width, and either the method of interpolation (analog
pens) or fill color (digital pens).
To configure pen appearance:
1 Select the pen you want to configure.
2 Click the Appearance tab to display the appearance property controls.
3 Select a Line color using the color swatch.
4 Specify a Line width.
5 To stack a pen, select the Stacked option and then specify a Height in pixels
for the stack.
6 Do one of the following:
For analog pens, choose an Interpolation method. Straight causes a line
to be drawn directly between two data points. Stepped causes a line to
be drawn between points maintaining the value of the previous sample
until a sample with a different value arrives, in which case a vertical line
is drawn.
For digital pens, select the Filled check box, and then select a fill color
from the color swatch.
7 Click Apply.
Configuring alarm pens
Configuring the appearance of alarm pens involves selecting the line color, stack
property, line width, alarm type, and the properties for that alarm type.
To configure alarm pen appearance:
2 Click the Appearance tab to display the appearance property controls for
the selected alarm pen.
3 Select a Line color using the color swatch.
4 Specify a Line width.
5 To stack a pen, select the Stacked option and then specify a Height in pixels
for the stack.
6 Select an Alarm type. For details about the different types of alarm pen
available, see Alarm pens. For information about alarm states, see Alarm
states.
7 For each Label for the alarm type you selected, select a Style, a Fill color,
and/or a Hatch color by using the swatches.
8 Click Apply.
Configuring pen
gridlines
You use the Process Analyst Properties dialog box to configure the gridlines for
a selected pen. Pen gridlines can be configured at run time by Operators, and at
design time by Users.
For more information about pen gridlines, see Gridlines.
Note: To configure defaults for pen gridlines, select the All pens item in the
property tree under Default Settings, and then complete the procedure below.
To configure pen gridlines:
1 Click the Main Page tab.
2 From the property tree list, select the pen you want to configure gridlines
for.
3 Click the Gridlines tab to display the gridlines property controls.
4 In the Vertical: Major area, select a Style, specify a Width, and then select a
Color.
5 In the Vertical: Minor area, select a Style, specify a Width, and then select a
Color.
6 In the Horizontal area (analog pens only), select a Style for the minor
gridline, specify a Width, and then select a Color for the major gridline.
7 Do the same if necessary for the minor gridline.
8 Click Apply.
Configuring pen axes
You use the Process Analyst Properties dialog box to configure the axis of the
selected pen. A pen axis can be configured at run time by Operators, and at
You can configure the color, line width, label type, scroll and scale properties for
the date/time and value axes. You can also choose whether to display time on the
date/time axis using local or UTC format.
For more information about pen axes, see Date/Time (Horizontal) Axis and
Vertical (Value) Axis.
Note: To configure defaults for pen axes, select the All pens item in the property
tree under Default Settings, and then complete the procedure below.
To configure a pen axis:
2 From the property tree list, select the pen you want to configure axes for.
3 Click the Axis tab to display the axis property controls.
4 In the Vertical area, select a Color by using the color swatch.
5 Enter a new Line width.
6 Select a Label type. This specifies the format to use for axis values.
7 Do one of the following (analog pens only):
Select the Autoscale option to autoscale the vertical axis.
Select the Interactive option, and then select Scale to be able to
interactively scale the vertical axis; and/or select Scroll to be able to
scroll the axis.
Note: These options are also available on the right-click (context) menu.
8 In the Horizontal area, select a Color by using the color swatch.
9 Select a Background color by using the color swatch.
10 Enter a new Line width.
11 Enter a Default Span to define the span you want to use for a new pen.
The default span is used by the Process Analyst when the Operator or User
clicks the Reset to Default Span button, or if the pen is added in pen
unlocked mode, or if the pen is the first one added to a display.
If youre setting the span value as a default setting for all new pens, the new
span value is inherited by all news pens created.
12 Select the Local Time option to display the date/time axis in local time using
your machine settings. If this option is not selected, the time is displayed in
UTC format. For details about time display on the date/time axis, see Date/
Time (Horizontal) Axis.
13 Select Scale to be able to interactively scale the vertical axis.
14 Select Scroll to be able to scroll the axis.
Note: The Scale and Scroll options are also available on the right-click
(context) menu.
15 Click Apply.
Configuring pen quality
You use the Process Analyst Properties dialog box to configure the quality of the
selected pen. Pen quality can be configured at run time by Operators, and at
Configuring the pen quality allows you to define the appearance of sample
markers on a selected pen, as well as the line styles of the pen, based upon the
quality of the data being trended by the Process Analyst.
For details about how the Process Analyst represents data quality, see Data
Quality.
To configure pen quality:
3 Click the Quality tab to display the quality property controls.
4 To enable points for the pen to be visible, select the Points Visible option.
5 In the Point Styles area, select a Single point style to represent a single data
sample.
6 Select a Multiple point style to represent multiple data samples.
7 Selected an Interpolated point style for interpolated data samples.
8 In the Line Styles area, select a line style to represent a Good sample.
9 Select a line style to represent a Gated/Disabled sample.
10 Select a line style to represent an NA sample.
11 Click Apply.
Configuring the pen
data connection
You use the Process Analyst Properties dialog box to configure the pen data
connection. Configuring the pen data connection allows you to define the server,
trend tag, and request mode for the selected pen.
Pen connection can be configured at run time by Operators and Users that have
the appropriate privileges.
To configure pen data connection:
2 Click the Connection tab to display the connection property controls.
3 For the Server data connection, a <localhost> connection is specified by
default, indicating that the Process Analyst will connect to the CitectSCADA
run time client running on the same computer, and pass its requests through
to the client, which will pass them onto the server.
4 Enter the Trend tag for the pen.
5 Select a Request mode. The default is Average.
The request mode defines how multiple samples are treated by the Process
Analyst. Regardless of the request mode used, the timestamp for a sample is
always averaged.
6 Click Apply.
See Also Data Compaction
Configuring cursor
labels
You use the Process Analyst Properties dialog box to configure the pen cursor
labels. Configuring the pen cursor labels allows you to specify the color used for
the lines, background, and text on the cursor label. Note that the information
shown on a cursor label is predefined and cannot be changed.
For details about cursor labels, see Using Cursor Labels.
Pen cursor labels can be configured at run time by both Operators and Users that
have the appropriate privileges.
To configure pen data connection:
2 Click the Cursor Label tab to display the connection property controls.
3 Select a Line color from the color swatch.
4 Select a Background color from the color swatch.
5 Select a Text color from the color swatch.
6 Click Apply.
Configuring Cursors
You can configure the line width and line color of a selected cursor. Changes to
the cursor line color apply only to the currently selected cursor. For details on
cursors, see Using Cursors.
To configure the cursor:
1 In the property tree of the Citect Process Analyst Properties dialog box, click
the cursor you want to configure. The Appearance property controls appear.
2 Type in a new Width value, and/or select a new Color.
3 Click Apply.
The defaults are a collection of properties that are inherited by each item (pane,
pen, cursor, and so on) when that item is created. These default properties are
maintained for the lifetime of the item until its properties are modified.
You configure these defaults in the same way as you configure the individual
components. The Default Settings node on the property tree contains the
following items:
All pens - configure the gridlines, axis, quality, connection, and cursor label
properties for all pen types. See Configuring pen gridlines, Configuring pen
axes, Configuring pen quality, Configuring the pen data connection, and
Configuring cursor labels.
Cursor - configure cursor defaults. See Configuring Cursors.
Analog - configure the appearance of analog pens. See Configuring pen
appearance.
Digital - configure the appearance of digital pens. See Configuring pen
appearance.
Alarm - configure the appearance of alarm pens. See Configuring pen
appearance.
Pane - configure the pane height and appearance defaults. See Configuring
Chart Panes.
Configuring Toolbars
The Process Analyst has two toolbars, the main toolbar and the navigation
toolbar. You use the Properties dialog box to configure the toolbars.
Operators can configure the Process Analyst toolbars by:
Adding or removing toolbar commands
Changing the order of toolbar commands
Users can perform additional tasks such as:
Adding New Commands
Editing Existing Custom Commands
Adding or removing
toolbar commands
Operators can add or remove toolbar commands during run time.
To add or remove commands from a toolbar:
1 From the Toolbar menu, choose the toolbar you want to customize (Main
Toolbar or Navigation Toolbar).
2 To add a command to the toolbar: In the Available toolbar buttons list,
select the command you want to add to the toolbar, and then click Add. The
selected command moves to the Current toolbar buttons list.
The Available toolbar buttons list contains all the command buttons
available in your system, including predefined as well as user-defined
commands.
3 To remove a command from the toolbar: In the Current toolbar buttons list,
select the command you want to remove from the toolbar, and then click
Remove. The selected command moves to the Available toolbar buttons
list.
Changing the order of
toolbar commands
Operators can change the order of toolbar commands during run time.
To change the order of commands:
Select a command in the Current toolbar buttons list and click Move Up or
Move down to move the selected command up or down the list as required.
Operators can configure the Object View to display additional pen information
to the columns that are displayed by default. You configure the Object View by
using the Properties dialog box.
Operators can select which columns to display, as well as change the size of
existing columns and the column display order. Users can define new columns,
or edit or delete existing columns; for details, see Creating or Editing Object
View Columns.
You can configure the Object View to display these predefined columns:
Column Description
Scale Vertical axis start and end position of the pen.
Engineering Units Engineering units associated with the pen.
Comment The trend/alarm comment defined for the pen.
Start Time Date/time axis start position of the pen.
End Time Date/time axis end position of the pen.
Duration Difference between the start time and the end time.
Tag Pens associated trend or alarm tag.
Trend Type Trend type of associated tag.
Sample Period Sampling period of the associated trend tag.
Engineering Scale Engineering scale for associated trend tag.
Raw Scale Raw scale for associated trend tag.
Alarm Category Category of associated alarm tag.
Alarm Description Description of associated alarm tag.
Alarm Area Area of associated alarm tag.
Alarm Name Name of associated alarm tag.
Alarm Type Alarm type of associated alarm tag.
For information on columns that are displayed by default, see Object View
Basics.
Object View properties
page
The Object View properties page allows you to show or hide existing columns,
create custom columns, edit existing columns, and re-order columns.
The Properties page displays all the available columns for the Object View and
their properties:
NameID - Internal identifier, which must be unique.
Width - Default width of the column in pixels.
Display Text - Title displayed in the column header.
The check boxes in the NameID column are bound to a columns visibility: a
column is visible only if the associated checkbox is selected.
The Move Up and Move Down buttons to the right of the Available Columns
list box allow you to reorder columns. The order of the columns from top to
Error Displays the error of the last data request. Blank if last data request succeeded.
Minimum Lowest displayed value (trend tags only).
Maximum Highest displayed value (trend tags only).
Average Average of all displayed values (trend tags only).
Column Description
bottom in the list dictates their display order from left to right in the Object
View. Clicking Move Up or Move Down shifts the currently selected item up or
down respectively.
See Also Creating or Editing Object View Columns
Working with Views
An Operator can save the visual setup of a Process Analyst control by saving a
view, which is saved as a Process Analyst View (.pav) file. They can also load
views that have been created previously. A view saves the state of all commands,
as well as properties for all the Process Analyst components (panes, pens, axes,
backgrounds, and so on).
To save a view or to load a view, you use the Save View and Load View
commands, respectively, on the main toolbar.
Saving a view
A Process Analyst view stores the trends and alarms that are being displayed,
the columns being viewed in the Object View, the toolbar buttons that are
available, as well as the look and feel of the view.
To save a view:
1 On the main toolbar, click Save View. The Save Process Analyst View dialog
box appears, showing the location where you can save views.
2 Choose a location to save your view to.
Note: It is your administrators responsibility to set up the correct directories
for saving views.
3 Enter a File name for your view, and then click OK.
To support redundancy, if the Local option is available and selected,
CitectSCADA attempts to save the view to the primary, standby and local
locations.
Loading a view
When loading a view, the start time and end time of a view is restored only
autoscroll is off. If autoscroll is on, pens are synchronized to Now.
When loading a view, the only locations that are available (My Documents,
Primary, and Standby) are those that have been configured by your
administrator.
To load a view:
1 On the main toolbar, click Load View. The Load dialog box appears.
2 Select a view to load, and then click OK. The view is loaded.
Chapter 8: Operator Command Reference
You use the toolbar commands on the main toolbar and navigation toolbar to
perform commonly used functions for viewing and interacting with Process
Analyst data, such as adding or removing pens, displaying cursors, and so on.
Process Analyst has predefined commands, grouped into the following
categories:
View Commands
Zoom Commands
Navigation Commands
Export Commands
Interface Commands
General Commands
The toolbars in your run time environment might have been customized during
implementation, so not all these commands might appear on your toolbars.
Additionally your toolbars might have custom commands not described here.
The tables describe the default set of commands delivered with the Process
Analyst.
View Commands
The Process Analyst has the following view commands by default:
See Also Zoom Commands
Navigation Commands
Export Commands
Interface Commands
General Commands
Icon Tooltip Description
Save View Displays the Save File dialog box allowing an Operator to save a Process
Analyst view to a specified location. For details, see Saving a view.
Load View Displays the Load View dialog box allowing the operator to specify a view
to load. For details, see Loading a view.
Chapter 8: Operator Command Reference 72
Zoom Commands
The Process Analyst has the following zoom commands by default:
See Also View Commands
Navigation Commands
Export Commands
Interface Commands
General Commands
Navigation Commands
The Process Analyst has the following navigation commands by default. For
details about these commands, see Navigating time.
Toggle Box Zoom Toggles the Process Analyst into box zoom mode. The mouse cursor
changes to a crosshair used to define an area to zoom in on. Zoom may
be cancelled by right-clicking or toggling the Zoom command off. For
details, see Toggle Box Zoom.
Zoom in 50% Executes a horizontal and vertical zoom in of 50% of the current span(s)
of the pen(s). For details, see Zoom In/Zoom Out.
Zoom out 50% Executes a horizontal and vertical zoom out of 50% of the current
span(s) of the pen(s). For details, see Zoom In/Zoom Out.
Undo Last Zoom Undoes the last zoom operation. For details, see Undo Last Zoom.
Reset to Default Span Restores the pen(s) spans to their original default settings. For details,
see Reset to Default Span.
Edit Span Displays the Edit Span dialog box allowing an operator to explicitly enter
a time span to apply to the display. For details, see Edit Span.
Edit Vertical Scale Enabled when an analog pen is selected. For details, see Edit Vertical
Scale.
Toggle Span Lock Toggles the locking of the time span. A time span is the distance in time
between the start time and end time of the chart. For details, see Span
Lock.
Back One Span Moves the pen(s) back in time exactly one time span. For details, see
Navigating time.
Back Half a Span Moves the pen(s) back half a span. For details, see Navigating time.
Forward One Span Moves the pen(s) forward in time exactly one span. For details, see
Navigating time.
Forward Half a Span Moves the pen(s) forward half a span. For details, see Navigating time.
Zoom Commands
Export Commands
Interface Commands
General Commands
Export Commands
The Process Analyst has the following export commands by default:
Zoom Commands
Navigation Commands
Interface Commands
General Commands
Interface Commands
The Process Analyst has the following interface commands by default:
Synchronize to Now Synchronizes pen(s) such that the end date time reflects now which is
positioned on the right-hand edge of the screen. Now is calculated
using the current system time. For details, see Synchronize to Now.
Toggle Auto-Scrolling Toggles the automatic scrolling off and on for all pens. For details, see
Toggle Autoscrolling.
Export to File Copies visible pens to an Excel compatible file. For details, see Copying
data to file.
Copy to Clipboard Copies visible pens to the clipboard.Interface Commands. For details, see
Copying data to the Clipboard.
Show/Hide Cursor Toggles the display of cursors. For details, see Using Cursors.
Show/Hide Cursor Labels Toggles the display of cursor labels. Enabled only when a cursor is
visible and when a pen exists. For details, see Using Cursor Labels.
Show/Hide Points Toggles the display of points representing where sample data was
recorded in the archive. For details, see Pens: An Overview.
Lock/Unlock Cursor Labels Toggles the locking/unlocking of cursor labels. Enabled only when a
cursor is visible and when a pen exists. For details, see Using
Cursor Labels.
Lock/Unlock Pens Toggles the locking/unlocking of pens. For details, see Locking/
Unlocking Pens.
Zoom Commands
Navigation Commands
Export Commands
General Commands
General Commands
The Process Analyst has the following general commands by default:
Zoom Commands
Navigation Commands
Export Commands
Interface Commands
Add Pane Adds a new pane to the view. For details, see Configuring Chart
Panes.
Remove Pane Removes the pane of the primary selected pen. A dialog confirms
the delete. For details, see Configuring Chart Panes.
Autoscale Vertical Axis for
Analog Pens
Toggles autoscaling for the selected pen on a per-pen basis. For
details, see Scaling the Chart.
Lock/Unlock Vertical Axis
Scrolling
Toggles interactive scrolling of the vertical axis and disables
autoscaling. For details, see Scrolling the Chart.
Add Pen Displays the add pen dialog. For details, see Adding Pens.
Remove Pen Removes the selected pen from the display. For details, see Deleting Pens.
Toggle Object View Toggles the display of the Object View. For details, see Using the Object
View.
Print Displays the print dialog, allowing the user to print the current state of the
Process Analyst. For details, see Printing and Exporting.
Refresh Data Refreshes the data for the selected pen, or all pens (if locked).
Show Properties Displays the Process Analyst Properties dialog box. For details, see Using
the Process Analyst Properties Dialog Box.
Help Displays the Process Analyst Help.
Part II
Process Analyst for Users
This section contains information for Users and describes the following:
Integration with CitectSCADA
Configuring Process Analyst Design Time Properties
Using the Process Analyst Command System
Automation Model
Chapter 10: Integration with CitectSCADA
The Process Analyst integrates seamlessly into the CitectSCADA system and is
designed to work primarily with the CitectSCADA Graphics Builder and the run
time environment. But the Process Analyst can also be embedded in custom
Visual Basic and .NET applications. In these situations CitectSCADA is still
required.
See Also Configuring the Process Analyst Control from Graphics Builder
Security and Permissions
Multi-language Support
Persistence
Backing up Projects
Configuring the Process Analyst Control from Graphics Builder
Being an ActiveX control, you can insert the Process Analyst onto a
CitectSCADA graphics page. To do this, do one of the following:
In Graphics Builder, choose Edit | Insert ActiveX Control. The Insert
ActiveX dialog box appears. Double-click the Citect Process Analyst
Control item in the ActiveX Controls list box. The control is inserted onto
the graphics page and the Properties dialog box appears.
Click the Process Analyst button in the Graphics Builder toolbox.
After inserting the Process Analyst into a page, you can resize it into position. To
view the configuration pages for the Process Analyst, double-click the Process
Analyst control. For details on configuring the design time properties for the
Process Analyst, see Configuring Process Analyst Design Time Properties.
See Also Persistence
Tag association
CitectSCADA can bind a CitectSCADA tag to an ActiveX property and update
either the tag or the property, based on a specified ActiveX event. You should
note that the Process Analyst control does not support this feature.
Security and Permissions
The Process Analyst integrates seamlessly into the CitectSCADA security model
by allowing access to certain Process Analyst features based on the privilege
level of the currently logged in Operator.
Chapter 10: Integration with CitectSCADA 78
The Process Analyst has nine privilege levels. Privilege level zero (0) indicates
there is no security and any user can perform the function. Levels 1-8 map
directly to the eight (8) privilege levels of security provided by Citect. The
Process Analyst, by default, assumes the area of the page that it is situated on;
this can be changed in the Graphics Builder. So if an operator has area access for
the page and has privilege level 1, and the function they want to use is level 2,
the function will be unavailable. If the operator had level 2, the function would
then become available. The Process Analyst also supports the CitectSCADA
Hierarchical Privilege security option.
Security can be applied to the following features:
Administration; for details, see Administration privilege.
Commands; for details, see Command privilege.
Saving Process Analyst views (write privilege); for details, see Write
privilege.
Administration privilege
The Process Analyst also uses an Administration privilege level to disable
engineer-oriented features at run time. For example, the ability to add new
custom commands and so on are all disabled if the Operator does not meet the
required privilege level. The Administration privilege level should never be zero
on a running system as this would expose properties to an Operator, which
could adversely affect the performance of the client and/or server (e.g., Number
Of Samples property).
The features that are disabled when an operator does not meet the
Administration privilege level include:
Add Pen context menu in Property dialog box.
New/Edit/Delete command (includes changing the privilege of commands).
New/Delete Column.
Data Refresh Rate property.
Display Refresh Rate property.
Number Of Samples property.
Server Paths tab.
Server field on Connection tab.
Tag field on Connection tab.
To modify the Administration privilege level, see Configuring Chart-wide
Properties.
Command privilege
The Process Analyst allows a privilege level to be assigned to each command
(standard or custom command). If an Operator does not have the required
privilege level to use that command, the associated toolbar button is disabled
and cannot be executed.
See Also Editing Existing Custom Commands
Write privilege
The Process Analyst uses a concept of write privilege level to control whether
an operator can save Process Analyst views to a location other than "My
documents". These views can then be loaded into the Process Analyst later by
any Operator. The write privilege is set at design time on the Server Paths
property page located on the root Process Analyst node in the Property pages
dialog box. If the write privilege level is set to zero (0), any operator can save to
any location. If the write privilege is any other level, the Operator must have that
privilege level to be able to save an Analyst view to a location other than "My
Documents".
See Also Configuring server paths
Working with Views
Process Analyst View Synchronization
Multi-language Support
The Process Analyst supports the CitectSCADA multilanguage ability of
changing the user interface language dynamically at run time. If the language is
changed in CitectSCADA, the Process Analyst will change its language to
match.
The process of configuring the Process Analyst for multiple languages is
different from that of CitectSCADA. This section describes how to localize the
Process Analyst user interface and get it to work with CitectSCADA.
Understanding the
Process Analyst
resources
The Process Analyst uses a special file, called Resources.dll, to store all of its
display strings and dialog boxes. This file holds the native translations for your
version of the Process Analyst; these native translations are considered the
default language. For example, the Japanese version of the Process Analyst will
contain Japanese resources inside the Resources.dll file.
A separate Resources.dll file must be created for each individual language that
you want to support in your system. The file should be renamed using a special
format to indicate the language. The Process Analyst expects the file to be
named Resources_<LanguageCode>.dll, where <LanguageCode> is the unique
identifier of your dll.
For example, if you are creating French resources, your dll should be named
Resources_fr.dll. CitectSCADA uses the RFC 1766 standard for specifying
culture names.
See Also Creating your own Process Analyst resource.dll
All language Resources*.dll files must be placed in the same directory as the
Analyst.dll file.
The example below shows a system that contains English as the default, and has
alternative languages of French, German and Chinese.
Resources.dll (default - any language, eg English)
Resources_fr.dll (French standard)
Resources_zh-CN.dll (Chinese PRC)
Resources_de.dll (German)
Using CitectSCADA to
switch the Process
Analyst language
Citect uses the Cicode function SetLanguage to switch languages at run time.
To allow the Process Analyst to determine the language it should display, you
must map your Citect language databases to the Process Analyst resource files.
To do this, add a new .ini section called [ProcessAnalyst] to the Citect.ini file
on all your CitectSCADA clients and servers, and create a mapping for each
language. (Note that this section might already exist in your Citect.ini file.) The
mapping must use this format:
LanguagePath.<dbf>=<ProcessAnalystLanguage>
where <dbf> is the name of a specific CitectSCADA language translation
database, and <ProcessAnalystLanguage> is the language code of the
resources.dll file that has the equivalent translations.
For example,
[ProcessAnalyst]
LanguagePath.French=fr
LanguagePath.Chinese=zh-CN
LanguagePath.German=de
The last step is to ensure each of your machines contains the necessary language
fonts. Windows XP and Windows 2000 both provide facilities to add the
necessary languages to your machine via the Regional and Language Options
dialog box, accessible from the Control Panel. This step is essential if you want to
use Asian languages on an English operating system. See Creating your own
Process Analyst resource.dll for details on adding languages to your system.
With the .ini file now configured, languages installed, and the Resource.dll files
in place when the SetLanguage Cicode function is called, CitectSCADA and the
Process Analyst will automatically change into the selected language.
Manually switching
languages
The Process Analyst can also switch languages by itself using the
IProcessAnalyst.Language property. You can call this property directly from
Cicode, for example.
Note: Using this method will only switch the Process Analyst language and not
the one used by CitectSCADA. See IProcessAnalyst.Language [Property] [Get/
Set].
Specifying languages
for the Web Client
A Process Analyst running inside a CitectSCADA Web Client also supports run
time language switching, but you must configure the languages that the Web
Client will download to the client machine.
To configure the languages to download:
1 Create a zip file in the CitectSCADA \bin folder called bin.zip.
2 Add to the zip file all the language resource DLL files that you want the
client to download and use. (You can find these files in your \Program
Files\Common Files\Citect folder.)
Note: The bin.zip file and its contents are not version-checked. This means
you must manually remove the bin.zip from the Web Client machines if
your server contains a more recent bin.zip file. To do this:
1 Find the installation directory of the Analyst.dll file on your Web Client
machines and look for a file called bin.zip in this directory.
2 Delete this file.
3 Reconnect to the Web server to download the latest bin.zip file.
Creating your own
Process Analyst
resource.dll
To create your own resources dll, you need to do the following:
1 Install the specific languages you are localizing on your Windows system.
2 Set your system to use that specific language.
Note: To create your own resources.dll file, youll need to use Microsoft
Developer Studio 6 or an equivalent tool.
Setup for localization on Windows XP
You must have Administrator privileges to perform the following setup.
1 Open Control Panel and double-click Regional and Language Options.
2 Click the Languages tab.
3 If localizing for East Asian languages, select the Install files for East Asian
languages check box, then click OK.
4 Once the languages are installed, click the Languages tab in the Regional
and Language Options dialog box.
5 Click Details in the Text services and input languages section to display the
Text Services and Input Languages dialog box.
6 In the Installed services section, ensure that the language you want to
localize with is listed. If not, add it.
1 To add a language, click Add to display the Add Input Language dialog
box.
2 Select the language you want from the Input language menu and click
OK.
Note: You might need your original Windows Installer CD
3 You might need to restart your system before the language is available.
If not, click Apply and then OK to close the Text Services and Input
Languages dialog box and return to the main window under the
Languages tab. If you need to restart your system, return to the Regional
and Language Options dialog box after logging back into Windows. Be
sure to login as an Administrator.
7 Click the Advanced tab in the Regional and Language Options dialog box.
8 Select the language you want from the menu in the Language for Non-
Unicode Programs section.
9 Click Apply and then OK (you may need to restart your system).
Setup for localization on Windows 2000
You must have Administrator privileges to perform the following setup.
1 Open Control Panel and double-click Regional Options.
2 On the General tab under Language Settings for the System, make sure the
language you want to localize with is in the list and "Checked". If it is not,
you must add it.
1 To add a language, click the Input Locales tab.
2 Click Add to display the Add Input Locale dialog box.
3 Select the language you want from the list.
4 Click OK and follow the on-screen prompts.
Note: You will need your original Windows Installer CD.Once the
language has been installed, repeat steps 1 and 2, and continue on to 3.
3 Click the Input Locales tab.
4 Ensure that your language is listed in the Installed input locals list.
5 Click back to the General tab.
6 Click Set default to display the Select System Locale dialog box.
7 From this list, select the language that you want to localize to and click OK.
This step is essential if you are using Asian characters on an English system.
(This may require a system restart.)
Note: When you are finished localizing, you should switch this option back to its
original setting.
Changing the input language
When your system has been configured to use multiple languages, you will find
a new icon in the system tray displayed as "EN" or similiar.
To change input language:
1 Click EN to display the input language option menu.
2 Select the language you want to use (to work correctly with Visual Studio,
this should match the language you selected in Step 8 of the Windows XP
setup and Step 7 of the Windows 2000 setup). This might display a
language-specific IME editor, which allows you to select characters to use in
your translations.
Localizing the Process Analyst resource dll
Once you have set up your system to cope with multiple languages, you can
begin localizing. Do the following:
1 Open Microsoft Visual Studio 6.
2 Choose File | Open.
3 Browse to the location of the Process Analyst's Resources.dll file. By default
it is located at C:\Program Files\Common Files\Citect\.
4 Ensure that the Files of type menu has Executable Files (.exe;.dll;*.ocx)
selected.
5 Ensure that the Open as menu has Resources selected.
6 Select Resources.dll and click Open.
7 Save the file under a new name. For example, if you are localizing for
Japanese, use Resources_ja-JP.dll. See Understanding the Process Analyst
resources for naming conventions.
8 Before changing any string, you must change the language code for each
dialog box and the string table by doing the following:
1 Expand the String Table folder in the tree.
2 Right-click the String Table entry.
3 Select Properties from the right-click (context) menu (see below).
4 From the Language menu, select the language that you are localizing
for.
5 Click the Close button in the top-right corner of the dialog.
6 Repeat these steps for each of the dialogs inside the Dialog folder.
Once the language code has been set for all dialogs and the string table, you are
ready to begin changing the text.
Localizing dialog boxes To localize a dialog box, do the following:
1 Expand the Dialogs folder in the tree.
2 Double-click a dialog to edit.
3 Select an item of text and right-click to display the properties for that item.
4 Enter your replacement text into the Caption field.
5 Click the Close button in the top-right corner of the dialog box.
You should note the following:
Controls can be repositioned or resized if necessary to fit your replacement
text.
Never resize a dialog box. The size of a dialog box is set to an optimum size
so that it integrates into Graphics Builder correctly.
Dialogs 3028 and 3050 do not require translation.
Localizing the String Table To localize the string table, do the following:
1 Expand the String Table folder in the tree.
2 Double-click the String Table entry. This will display a table showing you all
the strings of the Process Analyst.
3 Double-click an entry to display the Properties dialog box.
4 Type in the replacement text in the Caption box.
5 Click the Close button in the top-right corner of the dialog box.
Note: When translating strings, if a string contains %s, %x, %d and so on,
do not remove or replace those symbols as they are important to the Process
Analyst.
Persistence
Persistence refers to saving the state (properties, pens, and so on) of the Process
Analyst to disk. CitectSCADA and the Process Analyst provide the following
methods of persistence:
Saving as part of a Citect Graphics Builder page (design time)
Save View toolbar button on the Process Analyst (run time)
SaveToFile automation method on the Process Analyst (run time)
Saving between Citect page transitions (run time)
Saving while using the
Citect Graphics Builder
This feature allows you to configure the default look and/or what pens will be
displayed on the Process Analyst at design time while you are designing your
graphics pages. Design time is the appropriate time to configure the appearance
properties, toolbar buttons and, most importantly, the security of the Process
Analyst since these will become the default settings of the Process Analyst when
your page is displayed at run time.
When a page containing the Process Analyst is saved in the Graphics Builder all
the properties you configured on the Process Analyst will be stored within the
Graphics Builder page.
Note: When defining new custom toolbar buttons, any icon you assign will be
copied and also stored within the Graphics Builder page. This allows your
custom toolbar buttons to work on any machine.
Using the Save View
toolbar button
This feature is valid only at run time and allows operators to save the current
state of the Process Analyst (called a view) to a standalone file. These files can be
loaded during run time, and are an efficient way to store commonly used pen
configurations.
Using the SaveToFile
automation method
This feature is valid only at run time and allows a user to write Cicode to save
the current state of the Process Analyst to a standalone file, referred to as an
Analyst view. These files can be loaded during run time using the LoadFromFile
automation method (or the Load View toolbar button). Views and are an
efficient way to store commonly used pen configurations.
Saving between Citect
page transitions (Run-
time)
Using CitectSCADA run time, if you modify the Process Analyst (for example,
changing the timespan of a pen) and move off the page, your changes will be
lost. This behavior is not always what you want, so the Citect Graphcis Builder
provides an option Persist ActiveX data between page transitions to save the
state of an ActiveX control when you switch between pages.
Enabling this option causes CitectSCADA to write a temporary file to the Citect
Data directory in the format of <Event class>.stg whenever you leave a page
that contains an ActiveX object (e.g., the Process Analyst). When you reenter the
page, CitectSCADA looks for that same file and, if found, will load the settings
from it. These files only exist while CitectSCADA run time is running. When you
shut down CitectSCADA, the temporary *.stg files are deleted.
To save between page transitions:
1 Double-click the Process Analyst ActiveX control you want to change. The
Properties dialog box appears.
2 Click the Access tab.
3 Click the Identification tab. The Identification panel appears.
4 In the Persistence area, select the Persist ActiveX data between page
transitions check box, and then click Apply.
Resetting back to the
default state
You can reset the original configuration of the Process Analyst control by calling
the Cicode function ObjectResetState. This function takes the object handle of
the Process Analyst control, which you retrieve by using the Cicode function
ObjectByName.
Backing up Projects
When you save views to the Local storage location, the Process Analyst will
create a *.pav file in an Analyst Views subfolder under your project directory. If
your project contains Analyst views, you should ensure that the Save sub-
directories option is selected in Citect Explorer before backing up your project.
Chapter 11: Configuring Process Analyst
Design Time Properties
Most Process Analyst properties can be defined or modified during run time
and design time. This section describes properties that can be configured only
during design time, usually by a User.
For information about configuring run time properties, see Using the Process
Analyst Properties Dialog Box.
See Also Adding New Commands
Adding New Commands
Users can define new toolbar commands during design time if they have the
appropriate privilege level.
To add a new command:
1 On the Toolbars page of the Properties dialog box, click New. The New
Command dialog box appears.
Chapter 11: Configuring Process Analyst Design Time Properties 90
1 The dialog shows the unique, system-generated ID for the new command. If
necessary, enter a new ID for the command. This ID can be used in Cicode to
determine which command has been triggered or to find a specific com-
mand in the CitectSCADA system.
2 Enter the Tooltip text for the new command. You are limited to 64
characters. Tooltip text appears when the mouse pointer is over the toolbar
command.
3 Click Browse and navigate to the icon to represent the new command. The
icon image appears on the toolbar command button.
4 To define how the command behaves, choose a button style from the Button
style menu:
Push Button - click the Enabled check box to set the default appearance
of the button when the button is enabled or disabled.
Toggle Button - click Enabled or Pressed to specify the on
appearance.
See Also Editing Existing Custom Commands
Users can edit existing toolbar commands if they have the appropriate privilege
level. Commands can only be edited during design time, and only fields for
custom commands can be edited.
To edit an existing custom command
1 Open the Properties dialog box and click the Toolbars tab.
2 Select the command you want to edit in the Available toolbar buttons list
box, and then click Edit. The Edit Command dialog box appears.
3 If required. click Browse to navigate to a new icon to use for the command.
4 If required, edit the Tooltip text. The maximum length for Tooltip text is 64
characters.
5 If required, choose a new button style from the Button style menu.
See Also Adding New Commands
Users can create or delete Object View columns (during design time), as well as
edit existing columns (run time or design time). Object View columns display
information about your pens. All these configuration tasks are performed by
using the Citect Process Analyst Properties dialog box.
To create an Object View column:
1 Click the Object View tab. The Object View panel appears.
2 Click New. The New Column dialog box appears.
3 Enter a Name ID for the column. The value is used to reference the column
in code.
4 Specify a Width.
5 Enter the Text to use for the column in the Object View display.
To delete an Object View column:
Select the column you want to delete and click Delete.
To edit an Object View column:
1 Select the column you want to edit, and then click Edit. The Edit Column
dialog box appears.
2 Modify the information as required, and then click OK.
See Also Configuring the Object View
The Process Analyst implements a basic level of file synchronization for Process
Analyst views (.pav files). This feature causes the Process Analyst to try and
obtain the latest version of a .pav file before displaying it to the operator.
To achieve this, an engineer must first configure the Process Analyst to support
Primary and Standby server locations for Analyst Views; for details, see
Configuring server paths.
With these file servers in place, the Process Analyst now has a central location
from which to obtain Process Analyst views. If one of the locations is
unavailable, the operator can try the alternate location. When a client saves or
loads a Process Analyst view, only that view on the Primary and Standby server
locations will be synchronized to ensure they are all the same.
The table below outlines the rules of synchronization and privilege for the
storage locations and client modes when loading and saving Process Analyst
views.
* Refers to the Look in menu on SaveView and Load View dialog boxes.
** Means both privileged and un-privileged.
When setting up file-servers to store Process Analyst views, ensure that each
client machine has privileges enabling it the desired read/write access to those
locations.
See Also Configuring server paths
Working with Views
Write privilege
Action CitectSCADA mode Privilege Available Storage Locations*
Load Normal client Both** The Primary and Standby options appear as configured
as well as My Documents. If either are invalid or
unavailable paths, they do not appear. If both are invalid
or unavailable, the Local option appears. Default order is
Primary, Standby, My Documents, and Local, My
Documents respectively. Synchronization occurs when
loading from a Primary or Standby location.
Load Web client Both** The Local and My Documents options are the only ones
available. Local maps to the project directory\Analyst
Views. The default order is Local, My Documents.
Save Normal client Privileged The Local and My Documents options are the only ones
available. Local however will attempt to save to all server
locations as well as the project directory. The .pav file will
be saved to all available locations from primary, standby
and project directories. Default order: Local, My
Documents.
Save Normal client Unprivileged The My Documents option is the only one available.
Save Normal client Both** The My Documents option is the only one available.
Chapter 12: Using the Process Analyst
Command System
This section describes how to use the Process Analyst command system.
See Also Command System Overview
Custom Commands
Icons
Command System Overview
The Process Analyst provides an extensive command system allowing
manipulation of common Process Analyst features, as well as providing the
framework for creating custom user-defined commands.
The command system is configurable via the Toolbar property page and the
automation model.
To access the command system via the automation model, call the property
GetCommandSystem() from the IProcessAnalyst interface. For details, see
IProcessAnalyst Interface.
Custom Commands
Custom commands are defined in the Process Analyst, but must be
implemented in Cicode. You define commands by using the ICommandSystem-
> Create method, or by using the New button on the Toolbar property page.
To implement the command, you must respond to the event CommandExecuted
(and optionally UpdateCommand). Both of these events notify you of the ID of the
command which needs to be handled.
CommandExecuted
When an operator presses the toolbar button representing your command, it will
trigger this event. This is your opportunity to execute the desired functionality
of the command. This will not be triggered if the logged-in user fails to meet the
required privilege level. Be aware that this is an asynchronous operation.
UpdateCommand
When the Process Analyst requires the Enable state or pressed states of its
toolbar buttons to be refreshed, this event will be triggered. This will not be
triggered if the logged-in user fails to meet the required privilege level. Note that
this is asynchronous operation.
Chapter 12: Using the Process Analyst Command System 96
The state of all commands (custom and pre-defined) will be saved to disk
whenever the Process Analyst configuration is saved.
See Also Persistence
Icons
For custom commands, the user can specify their own custom icons by pointing
to a file on their hard drive. As these files may be deleted or moved over time,
the Process Analyst makes an instant copy of the icon into memory when the
command is added. This removes any dependence on the original icon file.
When the Process Analyst configuration is saved, the icon data is also saved.
Chapter 13: Automation Model
The automation model allows applications or solutions to programmatically
configure the Process Analyst controls appearance, performance, and behavior.
It also allows code, via automation events, to be attached to events fired from the
Process Analyst Control and perform custom behavior.
The automation model allows almost every visual aspect of the control to be
configured, as well as performance. It is simple and follows a traditional object-
oriented approach (see below).
To view information for an interface, click the name of the interface in the
illustration below. For example, to view information for the IPens interface, click
IPens.
Execution Results
Each property and method listed in the automation model will return one of the
following results upon execution. The exact meaning is described in the
Execution Result section for each property or method.
Execution Result Cicode VBA C++
InvalidArgument 274 5 E_INVALIARG
GeneralFailure 356 2147500037 E_FAIL
PathNotFound 356 76 STG_E_PATHNOTFOUND
Success 0 - S_OK
Chapter 13: Automation Model 98
Errors are captured differently in Cicode and VBA. The following code
examples show how to trap and handle errors in VBA and Cicode.
[VBA]
Sub VBATest(myObject As Object)
On Error Goto errHandler
myObject.<function>
Exit Sub
errHandler:
Print Err.Number, Err.Description
Resume Next
End Sub
[Cicode]
FUNCTION Test1(OBJECT hObject)
ErrSet(1); // Enable User error checking (disabled HW alarm)
IF ObjectIsValid(hObject) THEN
_ObjectCallMethod(hObject, "<function>");
error = IsError();
errorMessage = IntToStr(error)
IF (error <> 0) THEN
Message("An error occured", errorMessage, 0);
END
END
ErrSet(0); // Enable hardware alarm reporting of errors
END
Interfaces
IProcessAnalyst Interface
IAnalogPen Interface
IDigitalPen Interface
IAlarmPen Interface
ICursors Interface
ITrendCursor Interface
IPen Interface
IObjectView Interface
IObjectViewItems Interface
IObjectViewItem Interface
IObjectViewPenItem Interface
IObjectViewColumns Interface
IObjectViewColumn Interface
ICommandSystem Interface
ICommand Interface
IToolbars Interface
IToolbar Interface
IToolbarButtons Interface
IToolbarButton Interface
IPanes Interface
IPane Interface
IPens Interface
Events
CommandExecuted [Event]
CursorMoved [Event]
Error [Event]
HorizontalAxisChanged [Event]
MouseClick [Event]
MouseDoubleClick [Event]
OVColumnAdded [Event]
OVColumnRemoved [Event]
OVItemAdded [Event]
OVItemChecked [Event]
OVItemSelected [Event]
PenCreated [Event]
PenDeleted [Event]
PenRenamed [Event]
PenSelectionChanged [Event]
PropertyChanged [Event]
UpdateCommand [Event]
VerticalAxisChanged [Event]
Enumerations
AlarmType [Enumeration]
AxisLabelType [Enumeration]
ErrorNotifyCode [Enumeration]
FileLocation [Enumeration]
HatchStyle [Enumeration]
LineStyle [Enumeration]
LineType [Enumeration]
PenNameMode [Enumeration]
PenType [Enumeration]
PointType [Enumeration]
QualityCompactionType [Enumeration]
QualityType [Enumeration]
RequestMode [Enumeration]
ToolbarButtonType [Enumeration]
IProcessAnalyst Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IProcessAnalyst
Methods
IProcessAnalyst.BlockUpdates [Method]
IProcessAnalyst.UnBlockUpdates [Method]
IProcessAnalyst.CopyToClipboard [Method]
IProcessAnalyst.CopyToFile [Method]
IProcessAnalyst.FreezeEvent [Method]
IProcessAnalyst.LoadFromFile [Method]
IProcessAnalyst.PrintAll [Method]
IProcessAnalyst.SaveToFile [Method]
IProcessAnalyst.ShowProperties [Method]
IProcessAnalyst.SubscribeForPropertyChange [Method]
IProcessAnalyst.SynchroniseToNow [Method]
IProcessAnalyst.UnsubscribePropertyChange [Method]
Properties
IProcessAnalyst.AdminPrivilegeLevel [Property] [Get]
IProcessAnalyst.AutoScroll [Property][Get/Set]
IProcessAnalyst.BackgroundColor [Property][Get/Set]
IProcessAnalyst.CommandSystem [Property][Get]
IProcessAnalyst.ContextMenu [Property][Get/Set]
IProcessAnalyst.Cursors [Property][Get]
IProcessAnalyst.DataRequestRate [Property][Get/Set]
IProcessAnalyst.DisplayRefreshRate [Property][Get/Set]
IProcessAnalyst.Language [Property] [Get/Set]
IProcessAnalyst.LastSelectedPen [Property][Get]
IProcessAnalyst.LockedPens [Property][Get/Set]
IProcessAnalyst.ObjectView [Property][Get]
IProcessAnalyst.Number of Samples[Property][Get/Set]
IProcessAnalyst.Panes [Property][Get]
IProcessAnalyst.PrimaryPath [Property][Get/Set]
IProcessAnalyst.SecondaryPath [Property][Get/Set]
IProcessAnalyst.Toolbars [Property][Get]
IProcessAnalyst.WritePrivilegeLevel [Property][Get]
IProcessAnalyst.ZoomMode [Property][Get/Set]
IProcessAnalyst.BlockU
pdates [Method]
Blocks certain aspects of the Process Analysts redrawing and data updating.
Defined As
[VBA] BlockUpdates()
[Cicode] BlockUpdates()
[C++] HRESULT BlockUpdates()
Remarks
This method blocks three redraw systems: redraw for the chart, the Object
View, and the toolbars.
Data updates are also blocked.
The current data requests are all cancelled.
The Process Analyst has a built-in counter to store how many times the
block and unblock have been called, so that only the final UnBlockUpdates
call actually unblocks the above mentioned data updates and redraw
systems.
See Also IProcessAnalyst.UnBlockUpdates [Method]
Execution Result
If the function suceeds, the return value will be Success. If the function fails, the
return value will be general failure.
Calling Syntax
This example assumes there is a valid Process Analyst object to be passed into
the example methods.
[VBA]
Sub Example(ProcessAnalyst As Object)
ProcessAnalyst.BlockUpdates()
End Sub
[Cicode]
FUNCTION Example(OBJECT hProcessAnalyst)
_ObjectCallMethod(hProcessAnalyst, BlockUpdates);
END
IProcessAnalyst.UnBlo
ckUpdates [Method]
Unblocks certain aspects of the Process Analysts redrawing and data updating.
Defined As
[VBA] UnblockUpdates()
[Cicode] UnblockUpdates()
[C++] HRESULT UnblockUpdates()
Remarks
This method unblocks three redraw systems: redraw for the chart, the Object
View, and the toolbars.
Data updates are also unblocked.
The Process Analyst has a built-in counter to store how many times the
block and unblock have been called, so that only the final UnBlockUpdates
call actually unblocks the above mentioned data updates and redraw
systems.
See Also IProcessAnalyst.BlockUpdates [Method]
Execution Result
If the function suceeds, the return value will be Success. If the function fails, the
return value will be general failure. If other BlockUpdates are in effect, a Success
will be returned also (for those C++ users, S_FALSE will be returned in this case).
Calling Syntax
[VBA]
Sub Example(ProcessAnalyst As Object)
ProcessAnalyst.UnblockUpdates()
End Sub
[Cicode]
FUNCTION Example(OBJECT hProcessAnalyst)
_ObjectCallMethod(hProcessAnalyst, UnblockUpdates);
END
IProcessAnalyst.CopyT
oClipboard [Method]
Copies the data in the current viewable range for all visible pens to the
clipboard.
Defined As
[VBA] CopyToClipboard()
[Cicode] CopyToClipboard()
[C++] HRESULT CopyToClipboard()
Remarks
The timestamp of each sample will be in local time defined by your computer.
The start and end sample maybe generated for each pen to indicate the exported
range of the data.
Execution Result
If the function succeeds the return value will be Success. If the function fails the
return value will be GeneralFailure.
See Also IProcessAnalyst.CopyToFile [Method]
Calling Syntax
Assumes you have a page called myPage and the Process Analyst has been
named AN35.
[VBA]
Sub Example()
myPage_AN35.CopyToClipboard
End Sub
[Cicode]
Sub Example()
OBJECT hProcessAnalyst = ObjectByName(AN35);
_ObjectCallMethod(hProcessAnalyst, CopyToClipboard);
End Sub
IProcessAnalyst.CopyT
oFile [Method]
Saves the data in the current viewable range for all visible pens to the specified
file.
Defined As
[VBA] CopyToFile(filename As String)
[Cicode] CopyToFile(STRING filename)
[C++] HRESULT CopyToClipBoard(BSTR filename)
Parameters
filename
[in] Indicates the name and path of the file that the data will be exported to.
Execution Result
If the function succeeds the return value will be Success. If the function fails the
Remarks
The timestamp of each sample will be in local time defined by your computer.
The start and end sample maybe generated for each pen to indicate the exported
range of the data.
See Also IProcessAnalyst.CopyToClipboard [Method]
Calling Syntax
named AN35.
[VBA]
Sub Example()
myPage_AN35.CopyToFile test.xls
End Sub
[Cicode]
Sub Example()
_ObjectCallMethod(hProcessAnalyst, CopyToFile, test.xls);
End Sub
IProcessAnalyst.Freeze
Event [Method]
Enables or disables a specified event from triggering.
Defined As
[VBA] FreezeEvent(eventName As String, freeze As Boolean)
[Cicode] FreezeEvent(STRING eventName, INT freeze)
[C++] HRESULT FreezeEvent(BSTR columnName, VARIANT_BOOL freeze)
Parameters
eventName
[in] Specifies the event that you want to cease receiving notifications for.
freeze
[in] Indicates whether to enable or disable the event. True(-1) enable the
event. False(0) disable the event.
Execution Result
If the method succeeds, the return value will be Success. If the method fails, the
return value will be GeneralFailure. If eventName is bad or does not exist, the
return value will be InvalidArgument.
Remarks
All events exposed by the Process Analyst can be enabled or disabled. This
method is particularly useful to prevent recursive behavior of functions that
generate the same event that you are trying to handle.
Calling Syntax
[VBA]
Sub Example(analyst As Object)
analyst.FreezeEvent "HorizontalAxisChanged" True
End Sub
[Cicode]
FUNCTION Example(OBJECT hAnalyst)
_ObjectCallMethod(hAnalyst, "FreezeEvent",
"HorizontalAxisChanged", -1);
END
IProcessAnalyst.LoadFr
omFile [Method]
Loads a specified view into the Process Analyst.
Defined As
[VBA] LoadFromFile(filename As String, fileLocation As Integer)
[Cicode] LoadFromFile(STRING filename, INT fileLocation)
[C++] HRESULT LoadFromFile(BSTR filename, FileLocation fileLocation)
Parameters
filename
[in] Indicates a relative path and filename of the view to load into the
Process Analyst. See Remarks, below.
fileLocation
[in] Indicates which known location to load the file from.
Execution Result
If the function succeeds the return value will be Success. If the filename is invalid
the return value will be InvalidArgument. If the path indicated by fileLocation is
invalid or offline then the return value will be PathNotFound. If any other
problem occurs then the return value will be GeneralFailure.
Remarks
This method will replace the current view with the one in the specified file.
Absolute paths are not required for the filename as the method has been
designed to load the specified file from your project
directory(FileLocation_Local), my documents folder (FileLocation_User) or
from the primary/secondary paths (FileLocation_Server).
When a file is loaded it will be synchronized with the other locations to ensure
each location has the file which is the latest. If the file you are loading is older
then one which exists in another location it will be replaced. Synchronization
will not occur when loaded from a Web-client.
See Also FileLocation [Enumeration], IProcessAnalyst.PrimaryPath
[Property][Get/Set], IProcessAnalyst.SecondaryPath [Property][Get/
Set]
Calling Syntax
named AN35.
[VBA]
Sub Example()
Load the view from the server
myPage_AN35.LoadFromFile Analyst Views\Test1.pav, 1
End Sub
[Cicode]
FUNCTION Example()
_ObjectCallMethod(hProcessAnalyst, LoadFromFile, Analyst
Views\Test1.pav, 1);
END
IProcessAnalyst.PrintAl
l [Method]
Displays the Print configuration dialog.
Defined As
[VBA] PrintAll
[Cicode] PrintAll()
[C++] HRESULT PrintAll()
Execution Result
If the function succeeds the return value will be Success. If an unexpected error
occurs then return value will be GeneralFailure.
Calling Syntax
named AN35.
[VBA]
Sub Example()
myPage_AN35.PrintAll
End Sub
[Cicode]
FUNCTION Example()
_ObjectCallMethod(hProcessAnalyst, PrintAll);
END
IProcessAnalyst.SaveT
oFile [Method]
Saves the current view using the specified name to the specified location.
Defined As
[VBA] SaveToFile(filename As String, fileLocation As Integer)
[Cicode] SaveToFile(STRING filename, INT fileLocation)
[C++] HRESULT SaveToFile(BSTR filename, FileLocation fileLocation)
Parameters
filename
[in] Indicates a relative path and filename which will be used during the
saving of the view. See Remarks.
fileLocation
[in] Indicates which known location to save the file to.
Execution Result
If the function succeeds the return value will be Success. If the filename is invalid
the return value will be InvalidArgument. If the path indicated by fileLocation is
invalid or offline then the return value will be PathNotFound. If any other
problem occurs, the return value will be GeneralFailure.
Remarks
On a client where the current user matches the WritePrivilegeLevel only the
FileLocation_Server and FileLocation_User options will succeed. Saving using
the FileLocation_Server option will save to the locations indicated by
PrimaryPath and SecondaryPath properties and into the Project directory.
On a client where the current user does not match the WritePrivilegeLevel only
the FileLocation_User will succeed.
On a webclient the FileLocation_User is the only option which will succeed.
See Also FileLocation [Enumeration], IProcessAnalyst.PrimaryPath
[Property][Get/Set], IProcessAnalyst.SecondaryPath
[Property][Get/Set], IProcessAnalyst.WritePrivilegeLevel
[Property][Get]
Calling Syntax
named AN35.
[VBA]
Sub Example()
Save the view to the server and project
myPage_AN35.SaveToFile Analyst Views\Test1.pav, 1
End Sub
[Cicode]
FUNCTION Example()
Save the view to the server and project
_ObjectCallMethod(hProcessAnalyst, SaveToFile, Analyst
Views\Test1.pav, 1);
END
IProcessAnalyst.ShowP
roperties [Method]
Displays the Process Analysts property configuration dialog.
Define As
[VBA] ShowProperties
[Cicode] ShowProperties()
[C++] HRESULT ShowProperties ()
Execution Result
occurs then the return value will be GeneralFailure.
Calling Syntax
named AN35.
[VBA]
Sub Example()
myPage_AN35.ShowProperties
End Sub
[Cicode]
FUNCTION Example()
_ObjectCallMethod(hProcessAnalyst, ShowProperties);
END
IProcessAnalyst.Subscr
ibeForPropertyChange
[Method]
Use this method to receive notifications of when a particular property changes.
Notifications will be sent via the PropertyChanged event.
Defined As
[VBA] SubscribeForPropertyChange(interfaceName As String,
propertyName As String)
[Cicode] SubscribeForPropertyChange(STRING interfaceName, STRING
propertyName)
[C++] HRESULT SubscribeForPropertyChange(BSTR interfaceName, BSTR
propertyName)
Parameters
interfaceName
[in] Specify the name of the interface that the property you want
notifications for is defined on.
propertyName
[in] This is the name of the property you want to receive notifications for.
Execution Result
If the function succeeds, the return value will be Success. If the interfaceName or
propertyName is a bad string, the return value will be InvalidArgument. If any
other problem occurs, the return value will be GeneralFailure.
Remarks
The following set of properties are supported:
See Also IProcessAnalyst.UnsubscribePropertyChange [Method],
Calling Syntax
named AN35.
[VBA]
Sub Example()
myPage_AN35.SubscribeForPropertyChange IProcessAnalyst,
ZoomMode
End Sub
Interface name Property Name
IProcessAnalyst AutoScroll
IProcessAnalyst BackgroundColor
IProcessAnalyst ContextMenu
IProcessAnalyst LockedPens
IProcessAnalyst DisplayRefreshRate
IProcessAnalyst DataRequestRate
IProcessAnalyst ZoomMode
[Cicode]
Sub Example()
_ObjectCallMethod(hProcessAnalyst,
SubscribeForPropertyChange, IProcessAnalyst, ZoomMode);
End Sub
IProcessAnalyst.Synchr
oniseToNow [Method]
Synchronizes all pens such that the date/time reflects Now.
Defined As
[VBA] SynchroniseToNow
[Cicode] SynchroniseToNow()
[C++] HRESULT SynchroniseToNow()
Execution Result
If the function succeeds, the return value will be Success. If any other problem
occurs, the return value will be GeneralFailure.
Remarks
The current span for each pen will be maintained. Now is defined as the
current time on the client machine.
Calling Syntax
named AN35.
[VBA]
Sub Example()
myPage_AN35.SynchroniseToNow
End Sub
[Cicode]
Sub Example()
_ObjectCallMethod(hProcessAnalyst, SynchroniseToNow);
End Sub
IProcessAnalyst.Unsub
scribePropertyChange
[Method]
Use this method to cancel notifications of when the specified property changes.
Notifications will cease to be sent via the PropertyChanged event.
Defined As
[VBA] UnsubscribePropertyChange(interfaceName As String,
[Cicode] UnsubscribePropertyChange(STRING interfaceName, STRING
propertyName)
[C++] HRESULT UnsubscribePropertyChange(BSTR interfaceName, BSTR
propertyName)
Parameters
interfaceName
[in] Name of the interface that the property you want to remove
notifications for is defined on.
propertyName
[in] Name of the property you want to remove notifications for.
Execution Result
If the function succeeds, the return value will be Success. If the interfaceName or
propertyName is a bad string, the return value will be InvalidArgument. If any
other problem occurs, the return value will be GeneralFailure.
See Also IProcessAnalyst.SubscribeForPropertyChange [Method],
Calling Syntax
named AN35.
[VBA]
Sub Example()
myPage_AN35.UnsubscribePropertyChange IProcessAnalyst,
ZoomMode
End Sub
[Cicode]
Sub Example()
_ObjectCallMethod(hProcessAnalyst, UnsubscribePropertyChange,
IProcessAnalyst, ZoomMode);
End Sub
IProcessAnalyst.Admin
PrivilegeLevel
[Property] [Get]
Retrieves the privilege level currently set for controlling administration features
of the Process Analyst at Run-time.
Defined As
[VBA] Integer AdminPrivilegeLevel
[Cicode] INT AdminPrivilegeLevel
[C++] short AdminPrivilegeLevel
Execution Result
If the property get succeeds the return value will be Success. If the return
variable is bad then the return value will be InvalidArgument.
Remarks
By default the level is 0 (Zero), which allows access to all features at run time.
Setting this to any other level will require the operator viewing the Process
Analyst to have a privilege equal to that level.
This property can only be set at design time (in the Graphics Builder property
pages) and is recommended to prevent Operators from changing performance
properties such as DataRequestRate and DisplayRefreshRate.
Limits
Privilege level defined in CitectSCADA 1 - 8. 0 = no security.
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim privilege As Boolean
Getting Property value
privilege = myPage_AN35.AdminPrivilegeLevel
End Sub
[Cicode]
FUNCTION Example()
INT privilege;
// Getting current property value
privilege = _ObjectGetProperty(hProcessAnalyst,
AdminPrivilegeLevel);
END
IProcessAnalyst.AutoS
croll [Property][Get/Set]
Gets or Sets the automatic scrolling of all pens as time passes.
Defined As
[VBA] Boolean AutoScroll
[Cicode] INT AutoScroll
[C++] VARIANT_BOOL AutoScroll
Execution Result
If the property get/set succeeds, the return value will be Success. If the return
variable is bad, the return value will be InvalidArgument.
Remarks
This function does not synchronize the pens to now. The display will be updated
according to the value of the DisplayRefreshRate property.
Limits
True (-1): Autoscroll is On
False (0): Autoscroll is Off
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim autoScroll As Boolean
autoScroll = myPage_AN35.AutoScroll
Setting Property value
myPage_AN35.AutoScroll = True
End Sub
[Cicode]
FUNCTION Example()
INT autoScroll;
autoScroll = _ObjectGetProperty(hProcessAnalyst, AutoScroll);
// Setting Property to true
_ObjectSetProperty(hProcessAnalyst, AutoScroll, -1);
END
IProcessAnalyst.Backgr
oundColor
[Property][Get/Set]
Gets or sets the background color for the Process Analyst.
Defined As
[VBA] Long BackgroundColor
[Cicode] INT BackgroundColor
[C++] OLECOLOR BackgroundColor
Execution Result
Remarks
The background is the area under the panes. To calculate the integer value
required for a color, apply the following formula:
(65536 * Blue) + (256 * Green) + (Red)
where Red, Green, and Blue are 0-255.
Limits
True (-1): Context menu is enabled
False (0): Context menu is disabled
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim backgroundColor As Long
backgroundColor = myPage_AN35.BackgroundColor
Setting Property value to Red
myPage_AN35.BackgroundColor = 255
End Sub
[Cicode]
FUNCTION Example()
INT backgroundColor;
backgroundColor = _ObjectGetProperty(hProcessAnalyst,
BackgroundColor);
// Setting Property to Red
_ObjectSetProperty(hProcessAnalyst, BackgroundColor, 255);
END
IProcessAnalyst.Comm
andSystem
[Property][Get]
Gets a reference to the Process Analysts Command System object. With this
object you can execute commands, query command information, and create
your own custom commands.
Defined As
[VBA] Object CommandSystem
[Cicode] OBJECT CommandSystem
[C++] ICommandSystem* CommandSystem
Execution Result
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim commandSystem As Object
Retrieve command system
Set commandSystem = myPage_AN35.CommandSystem
End Sub
[Cicode]
FUNCTION Example()
OBJECT hCommandSystem;
// Retrieve command system
hCommandSystem = _ObjectGetProperty(hProcessAnalyst,
CommandSystem);
END
IProcessAnalyst.Contex
tMenu [Property][Get/
Set]
Enables or disables the context menu which is displayed at Run-time when an
operator clicks the right mouse button on the graphical display.
Defines As
[VBA] Boolean ContextMenu
[Cicode] INT ContextMenu
[C++] VARIANT_BOOL ContextMenu
Execution Result
If the property get/set succeeds the return value will be Success. If the return
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim contextMenu As Boolean
contextMenu = myPage_AN35.ContextMenu
Disable the context menu
myPage_AN35.ContextMenu = False
End Sub
[Cicode]
FUNCTION Example()
INT contextMenu;
contextMenu =_ObjectGetProperty(hProcessAnalyst,ContextMenu);
// Disable the context menu
_ObjectSetProperty(hProcessAnalyst, ContextMenu, 0);
END
IProcessAnalyst.Cursor
s [Property][Get]
Gets a reference to the Process Analysts cursors collection. With this object you
can create new, and browse existing cursors.
Defined As
[VBA] Object Cursors
[Cicode] OBJECT Cursors
[C++] ICursors* Cursors
Execution Result
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim cursors As Object
Retrieve cursors collection
Set cursors = myPage_AN35.Cursors
End Sub
[Cicode]
FUNCTION Example()
OBJECT hCursors;
// Retrieve cursor collection
hCursors = _ObjectGetProperty(hProcessAnalyst, Cursors);
END
IProcessAnalyst.DataRe
questRate
[Property][Get/Set]
Indicates how often (in milliseconds) the Process Analyst Control will request
data from the trend server(s). Internally the Process Analyst will choose the most
optimum request rate for data, but this property can be used to slow the request
down further.
Defined As
[VBA] Integer DataRequestRate
[Cicode] INT DataReqestRate
[C++] short DataRequestRate
Execution Result
Remarks
This property is useful for controlling the load on a trend server. The higher the
figure the less load will be put on the trend server(s).
Limits
Minimum = 10 milliseconds
Maximum = 60000 milliseconds (1 minute)
Default = 1000 milliseconds (1 second)
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim requestRate As Integer
Retrieve request rate
requestRate = myPage_AN35.DataRequestRate
Set request rate
myPage_AN35.DataRequestRate = 2000
End Sub
[Cicode]
FUNCTION Example()
INT requestRate;
// Retrieve property value
requestRate = _ObjectGetProperty(hProcessAnalyst,
DataRequestRate);
// Set property value to 2 seconds
_ObjectSetProperty(hProcessAnalyst, DataRequestRate, 2000);
END
IProcessAnalyst.Displa
yRefreshRate
[Property][Get/Set]
Indicates how fast the Process Analyst Control display is updated in
milliseconds. The default is an update of 1 second, which provides optimum
client performance and visual feedback.
Defined As
[VBA] Integer DisplayRefreshRate
[Cicode] INT DisplayRefreshRate
[C++] short DisplayRefreshRate
Execution Result
Remarks
This property is useful for controlling the performance of a client (CPU usage).
Limits
Minimum = 10 milliseconds (most machines will not be fast enough to keep
up).
Maximum = 60000 milliseconds (1 minute).
Default = 1000 milliseconds (1 second).
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim requestRate As Integer
Retrieve request rate
requestRate = myPage_AN35.DisplayRefreshRate
Set request rate
myPage_AN35.DisplayRefreshRate = 2000
End Sub
[Cicode]
FUNCTION Example()
INT requestRate;
// Retrieve request rate
requestRate = _ObjectGetProperty(hProcessAnalyst,
DisplayRefreshRate);
// Set request rate
_ObjectSetProperty(hProcessAnalyst, DisplayRefreshRate,
2000);
END
IProcessAnalyst.Langu
age [Property] [Get/Set]
This function allows dynamic changing of the user interface to the language
specified.
Defined As
[VBA] String Language
[Cicode] STRING Language
[C++] BSTR Language
Execution Result
Remarks
To change languages you must have additional localized resource .dll files
alongside the main resources.dll file. Additional language .dll files are named
(and should be named) using the format Resources_<languagecode>.dll. The
Process Analyst expects this format or the language will not be loaded.
For example, if you have a Chinese resource dll named Resources_zh-CN.dll,
set the Language property to zh-CN. The .dll files are named according to the
RFC 1766 standard for specifying culture names.
Specifying . resets the language back to the default.
Note: This method is not required to be called if you are using CitectSCADAs
multilanguage feature to make the Process Analyst switch languages. For
details, see Multi-language Support.
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim language As String
Retrieve current language
language = myPage_AN35.Language
Set language to Japanese
myPage_AN35.Language = ja-JP
End Sub
[Cicode]
FUNCTION Example()
STRING language;
// Retrieve current language
language = _ObjectGetProperty(hProcessAnalyst, Language);
// Set language to Japanese
_ObjectSetProperty(hProcessAnalyst, Language, ja-JP);
END
IProcessAnalyst.LastSe
lectedPen
[Property][Get]
Retrieves the last selected pen on the Process Analyst.
Defined As
[VBA] Object LastSelectedPen
[Cicode] OBJECT LastSelectedPen
[C++] IPen* LastSelectedPen
Execution Result
Remarks
The last selected pen is also referred to as the primary selection. If there are no
pens in the view, an invalid object will be returned.
Limits
A reference to the primary selected pen.
Invalid object when there are no pens on the display.
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim selectedPen As Object
Retrieve primary selection
Set selectedPen = myPage_AN35.LastSelectedPen
End Sub
[Cicode]
FUNCTION Example()
OBJECT selectedPen;
// Retrieve primary selection
selectedPen = _ObjectGetProperty(hProcessAnalyst,
LastSelectedPen);
END
IProcessAnalyst.Locke
dPens [Property][Get/
Set]
Determines whether all the pens across all panes in the Process Analyst control
are locked together.
Defined As
[VBA] Boolean LockedPens
[Cicode] INT LockedPens
[C++] VARIANT_BOOL LockedPens
Execution Result
Remarks
While this property is enabled, any operation applied to the selected pen is
applied to all pens. When the property is disabled, the pens will lose the lock
logic, and any interaction technique will apply to the individual pen with
selection focus.
If this property is disabled and then enabled, all pens assume the same scale,
timespan, and end time position as the selected pen.
Limits
True (-1): Pens are locked.
False (0): Pens are unlocked.
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim locked As Boolean
Get current locked status
locked = myPage_AN35.LockedPens
Turn off locked Pens
myPage_AN35.LockedPens = False
End Sub
[Cicode]
FUNCTION Example()
OBJECT lockedPens;
// Get current locked status
lockedPens = _ObjectGetProperty(hProcessAnalyst, LockedPens);
// Turn off locked Pens
_ObjectSetProperty(hProcessAnalyst, LockedPens, 0);
END
IProcessAnalyst.Object
View [Property][Get]
Gets a reference to the ObjectView object. With this object you can manipulate
the look of the ObjectView.
Defined As
[VBA] Object ObjectView
[Cicode] OBJECT ObjectView
[C++] IObjectView* ObjectView
Execution Result
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim objectView As Object
Retrieve the objectview
Set objectView = myPage_AN35.ObjectView
End Sub
[Cicode]
FUNCTION Example()
OBJECT objectView;
// Retrieve the objectview
objectView = _ObjectGetProperty(hProcessAnalyst, ObjectView);
END
IProcessAnalyst.Numbe
r of
Samples[Property][Get/
Set]
Specifies the date/time axis span of each pen in number of samples. More or less
detail for each pen can be displayed by increasing or decreasing the value of this
property respectively.
Defined As
[VBA] Integer NumberofSamples
[Cicode] INT NumberofSamples
[C++] short NumberofSamples
Execution Result
Remarks
This property is useful for controlling the performance of a client. (CPU usage).
By dividing a pens time span by the value of this property, you can calculate the
current display period of the pen. The Process Analyst will only display a
maximum of one sample per display period. See Data Compaction for details.
Limits
Minimum = 10
Maximum = 5000
Default = 300
See Also Exporting Pen Data
Calling Syntax
Assumes you have a page called "myPage" and the Process Analyst has been
named "AN35".
[VBA]
Sub Example()
Dim numOfSamples As Integer
`Retrieve number of samples
numOfSamples = myPage_AN35.NumberOfSamples
`Set request rate
myPage_AN35.NumberOfSamples = numOfSamples
End Sub
[Cicode]
FUNCTION Example()
OBJECT hProcessAnalyst = ObjectByName("AN35");
INT numOfSamples;
// Retrieve number of samples
numOfSamples = _ObjectGetProperty(hProcessAnalyst,
"NumberOfSamples");
// Set request rate
_ObjectSetProperty(hProcessAnalyst, "NumberOfSamples", 500);
END
IProcessAnalyst.Panes
[Property][Get]
Gets a reference to the Panes collection. With this object you can create new, and
browse existing panes.
Defined As
[VBA] Object Panes
[Cicode] OBJECT Panes
[C++] IPanes* Panes
Execution Result
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim panes As Object
Retrieve the panes collection
Set panes = myPage_AN35.Panes
End Sub
[Cicode]
FUNCTION Example()
OBJECT panes;
// Retrieve the panes collection
panes = _ObjectGetProperty(hProcessAnalyst, Panes);
END
IProcessAnalyst.Primar
yPath [Property][Get/
Set]
Specifies the primary location for saving and loading Process Analyst views.
Defined As
[VBA] String PrimaryPath
[Cicode] STRING PrimaryPath
[C++] BSTR PrimaryPath
Execution Result
Remarks
The primary and secondary path properties together provide a file redundancy
option for large systems that need to store Process Analyst Views in a shared
location. Whenever a load operation occurs from either of these locations, the
loaded file will be synchronized with each location, such that the latest version
of the file appears in both locations.
See Also IProcessAnalyst.SecondaryPath [Property][Get/Set],
IProcessAnalyst.LoadFromFile [Method], IProcessAnalyst.SaveToFile
[Method]
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim path As String
Retrieve the path
path = myPage_AN35.PrimaryPath
Set the path
myPage_AN35.PrimaryPath = \\computer1\PA Views
End Sub
[Cicode]
FUNCTION Example()
STRING path;
// Retrieve the path
path = _ObjectGetProperty(hProcessAnalyst, PrimaryPath);
// Set the path
_ObjectSetProperty(hProcessAnalyst, PrimaryPath,
\\computer1\PA Views);
END
IProcessAnalyst.Secon
daryPath
[Property][Get/Set]
Specifies the secondary location for saving and loading Process Analyst views.
Defined As
[VBA] String SecondaryPath
[Cicode] STRING SecondaryPath
[C++] BSTR SecondaryPath
Execution Result
Remarks
The secondary and primary path properties together provide a file redundancy
option for large systems that need to store Process Analyst Views in a shared
location. Whenever a load operation occurs from either of these locations, the
loaded file will be synchronized with each location, such that the latest version
of the file appears in both locations.
See Also IProcessAnalyst.LoadFromFile [Method],
IProcessAnalyst.PrimaryPath [Property][Get/Set],
IProcessAnalyst.SaveToFile [Method]
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim path As String
Retrieve the path
path = myPage_AN35.PrimaryPath
Set the path
myPage_AN35.SecondaryPath = \\computer1\PA Views
End Sub
[Cicode]
FUNCTION Example()
STRING path;
// Retrieve the path
path = _ObjectGetProperty(hProcessAnalyst, SecondaryPath);
// Set the path
_ObjectSetProperty(hProcessAnalyst, SecondaryPath,
\\computer1\PA Views);
END
IProcessAnalyst.Toolba
rs [Property][Get]
Gets a reference to the Toolbars collection. With this object you can browse and
modify existing toolbars.
Defined As
[VBA] Object Toolbars
[Cicode] OBJECT Toolbars
[C++] IToolbars* Toolbars
Execution Result
If the property get succeeds, the return value will be Success. If the return
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim toolbars As Object
Retrieve the toolbars collection
Set toolbars = myPage_AN35.Toolbars
End Sub
[Cicode]
FUNCTION Example()
OBJECT toolbars;
// Retrieve the toolbars collection
toolbars = _ObjectGetProperty(hProcessAnalyst, Toolbars);
END
IProcessAnalyst.WriteP
rivilegeLevel
[Property][Get]
Returns the privilege level required to save Process Analyst views to the
Primary and Secondary paths.
Defined As
[VBA] Integer WritePrivilegeLevel
[Cicode] INT WritePrivilegeLevel
[C++] short WritePrivilegeLevel
Execution Result
Remarks
The privilege cannot be set via automation. It must be set in the property pages
at design time (for example, in Graphics Builder).
See Also IProcessAnalyst.SaveToFile [Method], IProcessAnalyst.PrimaryPath
[Property][Get/Set], IProcessAnalyst.SecondaryPath
[Property][Get/Set]
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim privilege As Integer
Retrieve the privilege
privilege = myPage_AN35.WritePrivilegeLevel
End Sub
[Cicode]
FUNCTION Example()
INTEGER privilege;
// Retrieve the privilege
privilege = _ObjectGetProperty(hProcessAnalyst,
WritePrivilegeLevel);
END
IProcessAnalyst.Zoom
Mode [Property][Get/
Set]
Enables or disables the box zooming mode for the Process Analyst.
Defined As
[VBA] Boolean ZoomMode
[Cicode] INT ZoomMode
[C++] VARIANT_BOOL ZoomMode
Execution Result
Remarks
Setting this mode will ensure only box zooming operations can occur; all other
operations such as interactive scrolling and scaling will cease.
Limits
True (-1): Enable zoom mode.
False (0): Disable zoom mode.
Calling Syntax
named AN35.
[VBA]
Sub Example()
Dim zoomMode As Boolean
Retrieve the mode
zoomMode = myPage_AN35.ZoomMode
Set the path
myPage_AN35.ZoomMode = True
End Sub
[Cicode]
FUNCTION Example()
INT zoomMode;
// Retrieve the zoomMode
zoomMode = _ObjectGetProperty(hProcessAnalyst, ZoomMode);
// Set the zoomMode
_ObjectSetProperty(hProcessAnalyst, ZoomMode, -1);
END
MouseDoubleClick
[Event]
This event is raised whenever a mouse double-click occurs on the graphical
chart area of the Process Analyst.
Defined As
[VBA] MouseDoubleClick(pen As Object, button As Integer)
[Cicode] MouseDoubleClick(OBJECT processAnalyst, OBJECT pen, INT
button)
[C++] MouseDoubleClick(IPen pen, int button)
Parameters
pen
[in] Indicates which pen the double-click occurred on. This object will be
invalid if no pen was double-clicked.
button
[in] Indicates which button was double-clicked: 0 = Left, 1 = Right.
processAnalyst
[in] Indicates the Process Analyst object that raised the event (Cicode only).
Calling Syntax
Assumes you have a Process Analyst on a page with an event class defined as
myPage_AN35.
[VBA]
Sub myPage_AN35_MouseDoubleClick(pen As Object, button As Integer)
End Sub
[Cicode]
FUNCTION myPage_AN35_MouseDoubleClick(OBJECT processAnalyst,
OBJECT pen, INT button)
END
MouseClick [Event]
This event is raised whenever a single mouse click occurs on the graphical chart
area of the Process Analyst.
Defined As
[VBA] MouseClick(pen As Object, button As Integer)
[Cicode] MouseClick(OBJECT processAnalyst, OBJECT pen, INT button)
[C++] MouseClick(IPen* pen, int button)
Parameters
pen
[in] Indicates which pen the click occurred on. This object will be invalid if
no pen was clicked.
button
[in] Indicates which button was clicked: 0 = Left, 1 = Right.
processAnalyst
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_MouseClick(pen As Object, button As Integer)
End Sub
[Cicode]
FUNCTION myPage_AN35_MouseClick(OBJECT processAnalyst, OBJECT pen,
INT button)
END
PenCreated [Event]
This event is raised whenever a pen is either created via the automation model,
or added through the Add Pen dialog at run time.
Defined As
[VBA] PenCreated(pen As Object)
[Cicode] PenCreated(OBJECT processAnalyst, OBJECT pen)
[C++] PenCreated(IPen* pen)
Parameters
pen
[in] Refers to the pen that was created.
processAnalyst
[in] Indicates the Process Analyst object which raised the event. (Cicode
only).
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_PenCreated(pen As Object)
End Sub
[Cicode]
FUNCTION myPage_AN35_PenCreated(OBJECT processAnalyst, OBJECT pen)
END
PenDeleted [Event]
This event is raised whenever a pen is deleted either by automation or via the
interface.
Defined As
[VBA] PenDeleted(penName As String)
[Cicode] PenDeleted(OBJECT processAnalyst, STRING penName)
[C++] PenDeleted(BSTR penName)
Parameters
penName
[in] Contains the name of the pen that was deleted.
processAnalyst
only)
Calling Syntax
myPage_AN35
[VBA]
Sub myPage_AN35_PenDeleted(penName As String)
End Sub
[Cicode]
FUNCTION myPage_AN35_PenDeleted(OBJECT processAnalyst, STRING
penName)
END
PenRenamed [Event]
This event is raised whenever a pen is renamed via automation or through the
user interface.
Defined As
[VBA] PenRenamed(pen As Object)
[Cicode] PenRenamed(OBJECT processAnalyst, OBJECT pen)
[C++] PenRenamed(IPen* pen)
Parameters
pen
[in] Refers to the pen that was renamed.
processAnalyst
only).
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_PenRenamed(pen As Object)
End Sub
[Cicode]
FUNCTION myPage_AN35_PenRenamed(OBJECT processAnalyst, OBJECT pen)
END
PenSelectionChanged
[Event]
This event is raised whenever the selection changes in the Process Analyst.
Defined As
[VBA] PenSelectionChanged (pen As Object)
[Cicode] PenSelectionChanged (OBJECT processAnalyst, OBJECT pen)
[C++] PenSelectionChanged (IPen* pen)
Parameters
pen
[in] Refers to the pen that now has primary selection. This maybe invalid if
the last pen was deleted from the view.
processAnalyst
only)
Remarks
Selection can change via user interaction (such as clicking on pens, deleting/
adding pens) and automation.
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_PenSelectionChanged(pen As Object)
End Sub
[Cicode]
FUNCTION myPage_AN35_PenSelectionChanged(OBJECT processAnalyst,
OBJECT pen)
END
HorizontalAxisChanged
[Event]
This event is raised when the date/time axis position or scale of a pen is changed.
Defined As
[VBA] HorizontalAxisChanged(pen As Object)
[Cicode] HorizontalAxisChanged(OBJECT processAnalyst, OBJECT pen)
[C++] HorizontalAxisChanged(IPen* pen)
Parameters
pen
[in] Refers to the pen that has changed. This will be invalid if pens are
locked.
processAnalyst
Remarks
When the LockedPens property is True, this event is fired only once with the pen
parameter marked as invalid.
See Also IProcessAnalyst.LockedPens [Property][Get/Set],
VerticalAxisChanged [Event]
Calling Syntax
AN35_E.
[VBA]
Sub AN35_E_HorizontalAxisChanged (pen As Object)
End Sub
[Cicode]
FUNCTION AN35_E_HorizontalAxisChanged (OBJECT processAnalyst,
OBJECT pen)
END
VerticalAxisChanged
[Event]
This event is raised whenever the vertical axis position or scale of a pen is
changed.
Defined As
[VBA] VerticalAxisChanged(pen As Object)
[Cicode] VerticalAxisChanged(OBJECT processAnalyst, OBJECT pen)
[C++] VerticalAxisChanged(IPen* pen)
Parameters
pen
[in] Refers to the pen that has changed.
processAnalyst
only)
See Also HorizontalAxisChanged [Event]
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_VerticalAxisChanged (pen As Object)
End Sub
[Cicode]
FUNCTION myPage_AN35_VerticalAxisChanged (OBJECT processAnalyst,
OBJECT pen)
END
CursorMoved [Event]
This event is raised whenever the cursor position changes.
Defined As
[VBA] CursorMoved(cursor As Object, position As Integer)
[Cicode] CursorMoved (OBJECT processAnalyst, OBJECT cursor, INT
position)
[C++] CursorMoved (IPen* pen, int position)
Parameters
cursor
[in] Refers to the cursor that has moved.
position
[in] Indicates the new position of the cursor.
processAnalyst
only).
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_CursorMoved(pen As Object, position As Integer)
End Sub
[Cicode]
FUNCTION myPage_AN35_CursorMoved(OBJECT processAnalyst, OBJECT
cursor, INT position)
END
Error [Event]
This event is raised whenever an error is generated from the Process Analyst.
Defined As
[VBA] Error(errorCode As Integer, errorMessage As String)
[Cicode] Error(OBJECT processAnalyst, INT errorCode, STRING
errorMessage)
[C++] Error(ErrorNotifyCode errorCode, BSTR errorMessage)
Parameters
errorCode
[in] Indicates the error that occurred. See the ErrorNotifyCode
enumeration.
errorMessage
[in] Contains the message associated with the error code.
processAnalyst
only)
See Also ErrorNotifyCode [Enumeration]
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_Error(errorCode As Integer, errorMessage As
String)
End Sub
[Cicode]
FUNCTION myPage_AN35_Error(OBJECT processAnalyst, INT errorCode,
STRING errorMessage)
END
PropertyChanged
[Event]
This event is raised whenever a property that has been subscribed to has
changed.
Defined As
[VBA] PropertyChanged(interfaceName As String, propertyName As
String)
[Cicode] PropertyChanged (OBJECT processAnalyst, STRING
interfaceName, STRING propertyName)
[C++] PropertyChanged (BSTR interfaceName, BSTR propertyName)
Parameters
interfaceName
[in] Indicates which interface the property which has changed belongs to.
propertyName
[in] Indicates which property has changed.
processAnalyst
only)
Remarks
For this event to be raised you must subscribe to one or more properties.
See Also IProcessAnalyst.SubscribeForPropertyChange [Method],
IProcessAnalyst.UnsubscribePropertyChange [Method]
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_PropertyChanged(interfaceName As String,
End Sub
[Cicode]
FUNCTION myPage_AN35_PropertyChanged(OBJECT processAnalyst, STRING
interfaceName, STRING propertyName)
END
OVItemAdded [Event]
This event is raised whenever an item is added to the ObjectView.
Defined As
[VBA] OVItemAdded(item As Object)
[Cicode] OVItemAdded (OBJECT processAnalyst, OBJECT item)
[C++] OVItemAdded (IObjectViewItem* item)
Parameters
item
[in] A reference to the item that was added to the ObjectView.
processAnalyst
only)
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_OVItemAdded(item As Object)
End Sub
[Cicode]
FUNCTION myPage_AN35_OVItemAdded(OBJECT processAnalyst, OBJECT
item)
END
OVItemRemoved
[Event]
This event is raised whenever an item is added to the ObjectView.
Defined As
[VBA] OVItemRemoved(item As Object)
[Cicode] OVItemRemoved(OBJECT processAnalyst, OBJECT item)
[C++] OVItemRemoved(IObjectViewItem* item)
Parameters
item
[in] A reference to the item that was removed from the ObjectView.
processAnalyst
only)
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_OVItemRemoved(item As Object)
End Sub
[Cicode]
FUNCTION myPage_AN35_OVItemRemoved(OBJECT processAnalyst, OBJECT
item)
END
OVItemSelected [Event]
This event is raised whenever an item is selected in the ObjectView.
Defined As
[VBA] OVItemSelected(item As Object)
[Cicode] OVItemSelected(OBJECT processAnalyst, OBJECT item)
[C++] OVItemSelected(IObjectViewItem* item)
Parameters
item
[in] A reference to the item that was selected in the ObjectView.
processAnalyst
only)
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_OVItemSelected(item As Object)
End Sub
[Cicode]
FUNCTION myPage_AN35_OVItemSelected(OBJECT processAnalyst, OBJECT
item)
END
OVItemChecked [Event]
This event is raised whenever an item is checked in the ObjectView.
Defined As
[VBA] OVItemChecked(item As Object)
[Cicode] OVItemChecked(OBJECT processAnalyst, OBJECT item)
[C++] OVItemChecked(IObjectViewItem* item)
Parameters
item
[in] A reference to the item that was checked in the ObjectView.
processAnalyst
only)
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_OVItemChecked(item As Object)
End Sub
[Cicode]
FUNCTION myPage_AN35_OVItemChecked(OBJECT processAnalyst, OBJECT
item)
END
OVColumnAdded
[Event]
This event is raised whenever a column is added to the ObjectView.
Defined As
[VBA] OVColumnAdded(name As String)
[Cicode] OVColumnAdded(OBJECT processAnalyst, STRING name)
[C++] OVColumnAdded(BSTR name)
Parameters
item
[in] The name of the column that has been added
processAnalyst
only)
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_OVColumnAdded(name As String)
End Sub
[Cicode]
FUNCTION myPage_AN35_OVColumnAdded(OBJECT processAnalyst, STRING
name)
END
OVColumnRemoved
[Event]
This event is raised whenever a column is removed to the ObjectView.
Defined As
[VBA] OVColumnRemoved(name As String)
[Cicode] OVColumnRemoved(OBJECT processAnalyst, STRING name)
[C++] OVColumnRemoved(BSTR name)
Parameters
item
[in] The name of the column that has been removed.
processAnalyst
only)
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_OVColumnRemoved(name As String)
End Sub
[Cicode]
FUNCTION myPage_AN35_OVColumnRemoved(OBJECT processAnalyst, STRING
name)
END
CommandExecuted
[Event]
This event is raised when a command is executed.
Defined As
[VBA] CommandExecuted(commandId As String)
[Cicode] CommandExecuted (OBJECT processAnalyst, STRING
commandId)
[C++] CommandExecuted (BSTR commandId)
Parameters
commandId
[in] Contains the unique identifier of the command that was executed.
processAnalyst
only)
Remarks
Each toolbar button is associated with a command so when they are pressed this
event will be raised with the unique identifier of that command. You can then
use that identifier to determine which command was executed.
By using this event you can implement your own custom commands.
See Also UpdateCommand [Event], ICommandSystem.Execute [Method]
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_CommandExecuted(commandId As String)
End Sub
[Cicode]
FUNCTION myPage_AN35_CommandExecuted(OBJECT processAnalyst, STRING
commandId)
END
UpdateCommand
[Event]
This event is raised whenever the Process Analyst needs to refresh the state of its
toolbars.
Defined As
[VBA] UpdateCommand(commandId As String)
[Cicode] UpdateCommand(OBJECT processAnalyst, STRING commandId)
[C++] UpdateCommand(BSTR commandId)
Parameters
commandId
[in] Contains the unique identifier of the command that needs to be
refreshed.
processAnalyst
only)
Remarks
This event is only raised for custom commands. You should use this event as an
opportunity to update the enable and/or the pressed state of the toolbar button
associated with the command.
This event will be raised frequently so you should limit the amount of code
executed in response to this event.
An Update will be triggered in at least the following scenarios:
Selection changes
Command execution
Calling Syntax
myPage_AN35.
[VBA]
Sub myPage_AN35_UpdateCommand(commandId As Integer)
End Sub
[Cicode]
FUNCTION myPage_AN35_UpdateCommand(OBJECT processAnalyst, INT
commandId)
END
AlarmType
[Enumeration]
Specifies the visual representation for an alarm pen.
Defined As
[VBA] Integer
[Cicode] INT
[C++] AlarmType
Members
See Also IAlarmPen.AlarmType [Property][Get/Set]
AxisLabelType
[Enumeration]
Specifies how the labels are drawn on the vertical axis.
Member Name Description Value
AlarmType_Digital The tag is digital alarm 0
AlarmType_Analog The tag is an analog alarm 1
AlarmType_Advanced The tag is an advanced alarm 2
AlarmType_TimeStamped The tag is a time-stamped alarm 3
AlarmType_MultiDigital The tag is a multi-digital alarm 4
AlarmType_ArgyleAnalog The tag is a legacy Argyle analog alarm 5
AlarmType_TimeStampedDigital The tag is a digital time-stamped alarm 6
AlarmType_TimeStampedAnalog The tag is a analog time-stamped alarm 7
Defined As
[VBA] Integer
[Cicode] INT
[C++] AxisLabelType
Members
AxisLabelType_NONE No labels will be visible on axis 0
AxisLabelType_DOUBLE Displays in decimal format 1
AxisLabelType_INTEGER Displays in integer format 2
AxisLabelType_PERCENT Displays as % 3
AxisLabelType_AMPS Displays as A 4
AxisLabelType_DEGREES Displays as deg 5
AxisLabelType_FEET Displays as ft 6
AxisLabelType_FEETPERMIN Displays as ft/min 7
AxisLabelType_FEETPERSEC Displays as ft/s 8
AxisLabelType_GALLONS Displays as gal 9
AxisLabelType_GALLONSPERHR Displays as gal/h 10
AxisLabelType_GALLONSPERMIN Displays as gal/min 11
AxisLabelType_GALLONSPERSEC Displays as gal/s 12
AxisLabelType_HERTZ Displays as Hz 13
AxisLabelType_KILOGRAMS Displays as kg 14
AxisLabelType_KILOGRAMSPERHR Displays as kg/h 15
AxisLabelType_KILOGRAMSPERMIN Displays as kg/min 16
AxisLabelType_KILOGRAMSPERSEC Displays as kg/s 17
AxisLabelType_KILOMETRESPERHR Displays as kg/h 18
AxisLabelType_KILOPASCALS Displays as kPa 19
AxisLabelType_KILOWATTS Displays as kW 20
AxisLabelType_LITRES Displays as l 21
AxisLabelType_LITRESPERHR Displays as l/h 22
AxisLabelType_LITRESPERMIN Displays as l/min 23
AxisLabelType_LITRESPERSEC Displays as l/s 24
AxisLabelType_METRES Displays as m 25
AxisLabelType_METRESPERMIN Displays as m/min 26
AxisLabelType_METRESPERSEC Displays as m/s 27
AxisLabelType_REVS Displays as Rev 28
AxisLabelType_REVSPERHR Displays as Rev/h 29
AxisLabelType_REVSPERMIN Displays as RPM 30
AxisLabelType_TONNES Displays as t 31
AxisLabelType_TONNESPERHR Displays as t/h 32
LineStyle [Enumeration]
Defines the drawing style for a line.
Defined As
[VBA] Integer
[Cicode] INT
[C++] LineStyle
Values
HatchStyle
[Enumeration]
Defines the filling style for Alarm pens.
Defined As
[VBA] Integer
[Cicode] INT
[C++] HatchStyle
Members
See Also IAlarmPen.SetHatchStyle [Method], IAlarmPen.GetHatchStyle [Method]
AxisLabelType_VOLTS Displays as V 33
AxisLabelType_WATTS Displays as W 34
AxisLabelType_LOOKUP Displays user-defined text for label 35
LineStyle_SOLID Draws a solid line (all line widths) 0
LineStyle_DASH Draws a dashed line (line width 1 only) 1
LineStyle_DOT Draws a dot line (line width 1 only) 2
LineStyle_DASHDOT Draws a dash dot (line width 1 only) 3
LineStyle_DASHDOTDOT Draws a dash dot dot (line width 1 only) 4
LineStyle_NONE Draws no line 5
HatchStyle_None No pattern 0
HatchStyle_Horizontal Horizontal line pattern 1
HatchStyle_Vertical Vertical line pattern 2
HatchStyle_ForwardDiagonal Forward diagonal line pattern 3
HatchStyle_BackwardDiagonal Backward diagonal line pattern 4
HatchStyle_Cross Cross pattern 5
HatchStyle_DiagonalCross Diagonal cross pattern 6
PenNameMode
[Enumeration]
Defines how the pen name will be generated. It is used in conjunction with the
IPens.Create method.
Defined As
[VBA] Integer
[Cicode] INT
[C++] PenNameMode
Members
See Also IPens.Create [Method], IPen.DataPoint [Property][Get/Set],
IPen.Name [Property][Get/Set]
PenType [Enumeration]
Defines the plotting style of a Process Analyst pen.
Defined As
[VBA] Integer
[Cicode] INT
[C++] PenType
Members
See Also IPens.Create [Method]
PointType
[Enumeration]
Defines the visual cue applied to samples of a pen.
Defined As
[VBA] Integer
[Cicode] INT
[C++] PointType
PenNameMode_Comment The comment field obtained from the CitectSCADA trend/alarm
tag will be used as the pen name.
1
PenNameMode_Tag The value of the IPen.DataPoint property will be used as the pen
name.
2
PenNameMode_Custom Indicates that you will be setting the name using the IPen.Name
property.
3
PenType_ANALOG A pen with an analog range 4097
PenType_DIGITAL A pen with a range of 0 and 1 4098
PenType_ALARM A pen represented as states 4099
Members
See Also IPen.SetQualityCompactionPointType [Method]
RequestMode
[Enumeration]
Defines the data acquisition method for a pen.
Defined As
[VBA] Integer
[Cicode] INT
[C++] RequestMode
Members
See Also IPen.RequestMode [Property][Get/Set]
ToolbarButtonType
[Enumeration]
Defines the type of a toolbar button.
Defined As
[VBA] Integer
[Cicode] INT
[C++] ToolbarButtonType
PointType_NONE No marker 0
PointType_RECT A rectangular marker 1
PointType_CIRCLE A circular marker 2
PointType_PLUS A plus marker 3
PointType_CROSS A cross marker 4
PointType_TRIANGLE A triangular marker 5
PointType_ELLIPSE A elliptical marker 6
RequestMode_Average The value will be an average of all the individual samples within the
multiple sample, as will the timestamp
0
RequestMode_Minimum The value will be the minimum value out of all the individual samples
within the multiple sample. The timestamp will be the average of all the
individual samples.
1
RequestMode_Maximum The value will be the maximum value out of all the individual samples
individual samples.
2
RequestMode_Newest The value will the latest arrived value out of all the individual samples
individual samples.
3
Members
See Also ICommandSystem.Create [Method], ICommand.ButtonType [Property][Get]
LineType [Enumeration]
Defines the visual representation of the lines between samples of an analog pen.
Defined As
[VBA] Integer
[Cicode] INT
[C++] LineType
Members
See Also IAnalogPen.LineInterpolation [Property][Get/Set]
ErrorNotifyCode
[Enumeration]
Defines known errors that can occur during operation.
Defined As
[VBA] Integer
[Cicode] INT
[C++] ErrorNotifyCode
Members
ToolbarButtonType_Push Standard push button behavior. 0
ToolbarButtonType_Toggle The button has two states: On and Off. 1
ToolbarButtonType_Separator A visual marker used to group buttons. 2
LineType_STRAIGHT A single line is drawn from point A to point B. 0
LineType_STEPPED The line drawn will maintain the value of the previous sample. When the
samples differ, a vertical line will be drawn to the new sample value.
1
ErrorNotifyCode_None No error. 0
ErrorNotifyCode_InvalidTag Occurs when the tag specified for the pen does not
exist.
1
ErrorNotifyCode_CtapiConnectionOffline Occurs when connections cannot be made to the trend
and/or alarm servers.
2
ErrorNotifyCode_Unknown Occurs when an unknown CitectSCADA or Windows
error occurs.
3
ErrorNotifyCode_NoServer Occurs when CitectSCADA cannot find a server to get
the data from.
4
ErrorNotifyCode_InvalidArgument Occurs when an invalid argument is specified. 5
See Also Error [Event]
QualityType
[Enumeration]
Defines the known quality states of data.
Defined As
[VBA] Integer
[Cicode] INT
[C++] QualityType
Members
Remarks
An alarm pens disabled state is treated as QualityType_Gated.
See Also IPen.SetQualityLineStyle [Method]
QualityCompactionType
[Enumeration]
Specifies the different types of presentation used for a sample.
Defined As
[VBA] Integer
[Cicode] INT
[C++] QualityCompactionType
Members
ErrorNotifyCode_OutOfMemory Occurs when a memory error is detected. 6
ErrorNotifyCode_BadVersion Occurs when the trend and/or alarm servers do not
match the client version.
7
ErrorNotifyCode_NoPrivilege Occurs when the current user does not have the
required privileges to view the data.
8
QualityType_Good The sample is good 0
QualityType_NA Indicates a loss of connection 1
QualityType_Gated Indicates the data was marked as unwanted 2
QualityCompactionType_Single Representation when the marker represents a single
sample
0
QualityCompactionType_Multiple Representation when the marker represents a
calculation of two or more samples
1
QualityCompactionType_Interpolated Representation when the marker represents
interpolated samples
2
FileLocation
[Enumeration]
Specifies the location to save and write Process Analyst views to.
Defined As
[VBA] Integer
[Cicode] INT
[C++] FileLocation
Members
See Also IProcessAnalyst.LoadFromFile [Method], IProcessAnalyst.SaveToFile
[Method]
IAnalogPen Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IAnalogPen
Methods (0)
Properties (3)
See Also IAnalogPen.LineColor [Property][Get/Set]
IAnalogPen.LineInterpolation [Property][Get/Set]
IAnalogPen.LineWidth [Property][Get/Set]
IAnalogPen.LineColor
[Property][Get/Set]
Gets or Sets the color that will be used to draw the pen line.
Defined As
[VBA] Long LineColor
[Cicode] INT LineColor
[C++] OLE_COLOR LineColor
Execution Result
FileLocation_Local Refers to the project folder 0
FileLocation_Server Refers to the both the primary/standby server paths 1
FileLocation_User Refers to the My Documents folder 2
variable is bad, the return value will be InvalidArgument. If the pen is deleted,
the return value will be GeneralFailure.
Remarks
The color value can be calculated using the following formula:
color = (65536 * blue) + (256 * green) + (red)
where red, green, and blue are 0-255.
Calling Syntax
This example assumes there is a valid AnalogPen object to be passed into the
example methods.
[VBA]
Sub Example(analogPen As Object)
Dim lineColor As Long
lineColor = analogPen.LineColor
Setting Property to red
analogPen.LineColor = 255
End Sub
[Cicode]
FUNCTION Example(OBJECT hAnalogPen)
// Getting property value
INT nLineColor = _ObjectGetProperty(hAnalogPen, "LineColor");
// Setting property to red
_ObjectSetProperty(hAnalogPen, "LineColor", 255);
END
IAnalogPen.LineInterpol
ation [Property][Get/
Set]
Gets or sets the drawing style used for drawing the connecting lines between
points for this analog pen.
Defined As
[VBA] Long LineInterpolation
[Cicode] INT LineInterpolation
[C++] LineType LineInterpolation
Execution Result
variable is bad then the return value will be InvalidArgument. If the pen is
deleted the return value will be GeneralFailure.
Remarks
The LineInterpolation mode dictates how the two points of a line are joined
when drawn. If Stepped, there will be two lines joining each point, one
horizontal and one vertical. If Straight, only one line is used to directly connect
the two points.
See Also LineType [Enumeration]
Calling Syntax
This example assumes there is a valid Analog Pen object to be passed into the
example methods.
[VBA]
Dim lineInterpolation As Long
lineInterpolation = analogPen.LineInterpolation
analogPen.LineInterpolation = 1
End Sub
[Cicode]
INT nInterpolation = _ObjectGetProperty(hAnalogPen,
"LineInterpolation");
// Setting property value
_ObjectSetProperty(hAnalogPen, "LineInterpolation", 1);
END
IAnalogPen.LineWidth
[Property][Get/Set]
Gets or sets the width in pixels of the pen line when it is drawn.
Defined As
[VBA] Long LineWidth
[Cicode] INT LineWidth
[C++] int LineWidth
Execution Result
Limits
Minimum = 0
Maximum = 8
Calling Syntax
This example assumes there is a valid Analog Pen object to be passed into the
example methods.
[VBA]
Dim lineWidth As Long
lineWidth = analogPen.LineWidth
analogPen.LineWidth = 5
End Sub
[Cicode]
INT nLineWidth = _ObjectGetProperty(hAnalogPen, "LineWidth");
_ObjectSetProperty(hAnalogPen, "LineWidth", 5);
END
IDigitalPen Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IDigitalPen
Methods (0)
Properties (4)
IDigitalPen.FillColor [Property][Get/Set]
IDigitalPen.LineColor [Property][Get/Set]
IDigitalPen.LineWidth [Property][Get/Set]
IDigitalPen.Fill [Property][Get/Set]
IDigitalPen.FillColor
[Property][Get/Set]
Gets or Sets the color that will be used to fill the area under the line when the
value is 1.
Defined As
[VBA] Long FillColor
[Cicode] INT FillColor
[C++] OLE_COLOR FillColor
Execution Result
Remarks
color = (65536 * blue) + (256 * green) + (red)
where red, green, and blue are 0-255. The area under the line is filled with this
color if the value of the Fill property is True (-1).
See Also IDigitalPen.Fill [Property][Get/Set]
Calling Syntax
This example assumes there is a valid DigitalPen object to be passed into the
example methods.
[VBA]
Sub Example(digitalPen As Object)
Dim fillColor As Long
fillColor = digitalPen.FillColor
digitalPen.FillColor = 255
End Sub
[Cicode]
FUNCTION Example(OBJECT hDigitalPen)
INT nFillColor = _ObjectGetProperty(hDigitalPen, "FillColor");
_ObjectSetProperty(hDigitalPen, "FillColor", 255);
END
IDigitalPen.LineColor
[Property][Get/Set]
Defined As
Execution Result
Remarks
The color value can be calculated using the following formula: color = (65536 *
Blue) + (256 * Green) + (Red). Where red, green and blue are 0-255.
Calling Syntax
This example assumes there is a valid DigitalPen object to be passed into the
example methods.
[VBA]
lineColor = DigitalPen.LineColor
digitalPen.LineColor = 255
End Sub
[Cicode]
INT nLineColor = _ObjectGetProperty(hDigitalPen, "LineColor");
_ObjectSetProperty(hDigitalPen, "LineColor", 255);
END
IDigitalPen.LineWidth
[Property][Get/Set]
Defined As
[C++] int LineWidth
Execution Result
Limits
Minimum = 0
Maximum = 8
Calling Syntax
This example assumes there is a valid Digital Pen object to be passed into the
example methods.
[VBA]
lineWidth = digitalPen.LineWidth
digitalPen.LineWidth = 5
End Sub
[Cicode]
INT nLineWidth = _ObjectGetProperty(hDigitalPen, "LineWidth");
_ObjectSetProperty(hDigitalPen, "LineWidth", 5);
END
IDigitalPen.Fill
[Property][Get/Set]
Gets or sets whether the pen fill is displayed.
Defined As
[VBA] Boolean Fill
[Cicode] INT Fill
[C++] VARIANT_BOOL Fill
Execution Result
Remarks
If the pen is filled, the area under the pen line will be filled with the color
specified by the FillColor property.
See Also IDigitalPen.FillColor [Property][Get/Set]
Limits
True (-1): = Fill is displayed
False (0): = Fill is hidden
Calling Syntax
This example assumes there is a valid digital pen object to be passed into the
example methods.
[VBA]
Dim fill As Boolean
fill = digitalPen.Fill
digitalPen.Fill = True
End Sub
[Cicode]
INT nFill = _ObjectGetProperty(hDigitalPen, "Fill");
_ObjectSetProperty(hDigitalPen, "Fill", -1);
END
IAlarmPen Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IAlarmPen
Methods (6)
IAlarmPen.GetFillColor [Method]
IAlarmPen.SetFillColor [Method]
IAlarmPen.GetHatchColor [Method]
IAlarmPen.SetHatchColor [Method]
IAlarmPen.GetHatchStyle [Method]
IAlarmPen.SetHatchStyle [Method]
Properties (3)
IAlarmPen.LineColor [Property][Get/Set]
IAlarmPen.LineWidth [Property][Get/Set]
IAlarmPen.AlarmType [Property][Get/Set]
IAlarmPen.LineColor
[Property][Get/Set]
Defined As
Execution Result
Remarks
color = (65536 * Blue) + (256 * Green) + (Red)
Calling Syntax
This example assumes there is a valid alarm pen object to be passed into the
example methods.
[VBA]
Sub Example(alarmPen As Object)
lineColor = alarmPen.LineColor
alarmPen.LineColor = 255
End Sub
[Cicode]
FUNCTION Example(OBJECT hAlarmPen)
INT nLineColor = _ObjectGetProperty(hAlarmPen, "LineColor");
_ObjectSetProperty(hAlarmPen, "LineColor", 255);
END
IAlarmPen.LineWidth
[Property][Get/Set]
Defined As
[C++] int LineWidth
Execution Result
Limits
Minimum = 0
Maximum = 8
Calling Syntax
example methods.
[VBA]
lineWidth = alarmPen.LineWidth
alarmPen.LineWidth = 5
End Sub
[Cicode]
INT nLineWidth = _ObjectGetProperty(hAlarmPen, "LineWidth");
_ObjectSetProperty(hAlarmPen, "LineWidth", 5);
END
IAlarmPen.AlarmType
[Property][Get/Set]
Gets or Sets the display type of this alarm pen.
Defined As
[VBA] Long AlarmType
[Cicode] INT AlarmType
[C++] AlarmType AlarmType
Execution Result
Remarks
This AlarmType also dictates the number of alarm states, and their descriptions.
See Also IAlarmPen.AlarmType [Property][Get/Set]
Calling Syntax
example methods.
[VBA]
Dim alarmType As Long
alarmType = alarmPen.AlarmType
Setting Property value to Analog
alarmPen.AlarmType = 1
End Sub
[Cicode]
INT eAlarmType = _ObjectGetProperty(hAlarmPen, "AlarmType");
// Setting property to Analog
_ObjectSetProperty(hAlarmPen, "AlarmType", 1);
END
IAlarmPen.GetFillColor
[Method]
Gets the color used to fill the pen for the specified state.
Defined As
[VBA] GetFillColor(state as Long) as Long
[Cicode] INT GetFillColor(INT state)
[C++] HRESULT GetFillColor(int state, OLE_COLOR* color)
Execution Result
Parameters
state
[in] The state for which fill color to retrieve (0 to 8).
Remarks
Calling Syntax
This example assumes there is a valid AlarmPen object to be passed into the
example methods.
[VBA]
fillColor = alarmPen.GetFillColor(0)
End Sub
[Cicode]
INT nFillColor = _ObjectCallMethod(hAlarmPen, GetFillColor ,
0);
END
IAlarmPen.SetFillColor
[Method]
Sets the color used to fill the pen for the specified state.
Defined As
[VBA] SetFillColor(state as Long, color as Long)
[Cicode] INT SetFillColor(INT state, INT color)
[C++] HRESULT SetFillColor(int state, OLE_COLOR color)
Parameters
state
[in] The state for which you would like to assign a fill color (0 to 8).
color
[in] The fill color that you would like used to for this specific state.
Execution Result
If the function succeeds, the return value will be Success. If the state is out of
range, the return value will be InvalidArgument. If the pen is deleted, the return
value will be GeneralFailure.
Remarks
Calling Syntax
example methods.
[VBA]
Setting FillColor to Red
alarmPen.SetFillColor(0, 255)
End Sub
[Cicode]
// Setting FillColor to Red
_ObjectCallMethod(hAlarmPen, SetFillColor ,0, 255);
END
IAlarmPen.GetHatchCol
or [Method]
Gets the color used to draw the outline and hatching for the specified state.
Defined As
[VBA] GetHatchColor(state as Long) as Long
[Cicode] INT GetHatchColor(INT state)
[C++] HRESULT GetHatchColor(int state, OLE_COLOR* color)
Execution Result
If the function succeeds, the return value will be Success. If the state is out of
Parameters
state
[in] The state for which hatch color to retrieve (0 to 8).
Remarks
Calling Syntax
example methods.
[VBA]
Dim hatchColor As Long
hatchColor = alarmPen.GetHatchColor(0)
End Sub
[Cicode]
INT nHatchColor = _ObjectCallMethod(hAlarmPen, GetHatchColor
, 0);
END
IAlarmPen.SetHatchCol
or [Method]
Sets the color used to draw the outline and hatching for the specified state.
Defined As
[VBA] SetHatchColor(state as Long, color as Long)
[Cicode] INT SetHatchColor (INT state, INT color)
[C++] HRESULT SetHatchColor (int state, OLE_COLOR color)
Parameters
state
[in] The state for which you would like to assign a hatch color (0 to 8).
color
[in] The color that you would like to be used for a specified states hatch.
Execution Result
If the function succeeds the return value will be Success. If the state is out of
range then the return value will be InvalidArgument. If the pen is deleted the
Remarks
Calling Syntax
example methods.
[VBA]
Dim hatchColor As Long
Setting HatchColor to Red
alarmPen.SetHatchColor(0, 255)
End Sub
[Cicode]
// Setting HatchColor to Red
_ObjectCallMethod(hAlarmPen, SetHatchColor,0, 255);
END
IAlarmPen.GetHatchStyl
e [Method]
Gets the hatch style used when drawing the boxes for the specified state.
Defined As
[VBA] GetHatchStyle(state as Long) as Long
[Cicode] INT GetHatchStyle(INT state)
[C++] HRESULT GetHatchStyle(int state, HatchStyle* color)
Parameters
state
[in] The state for which you would like to retrieve a hatch style (0 to 8).
Execution Result
Remarks
See Also IAlarmPen.GetHatchStyle [Method]
Calling Syntax
example methods.
[VBA]
Dim hatchStyle As Long
hatchStyle = alarmPen.GetHatchStyle(0)
End Sub
[Cicode]
INT nHatchStyle = _ObjectCallMethod(hAlarmPen, GetHatchStyle,
0);
END
IAlarmPen.SetHatchStyl
e [Method]
Sets the hatch style used for drawing the specified state.
Defined As
[VBA] SetHatchStyle(state as Long, HatchStyle as Long)
[Cicode] INT SetHatchStyle (INT state, INT hatchStyle)
[C++] HRESULT SetHatchStyle (int state, HatchStyle hatchStyle)
Parameters
state
[in] The state for which you would like to assign a hatch style.
hatchStyle
[in] The hatch style that will be used for the specified state.
Execution Result
Remarks
See Also IAlarmPen.GetHatchStyle [Method]
Calling Syntax
example methods.
[VBA]
Setting HatchStyle
alarmPen.SetHatchStyle(0, 1)
End Sub
[Cicode]
// Setting HatchStyle
_ObjectCallMethod(hAlarmPen, SetHatchStyle ,0, 1);
END
ICursors Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] ICursors
Methods
ICursors.Create [Method]
ICursors.RemoveAll [Method]
Properties
ICursors.Item [Property][Get]
ICursors._NewEnum [Property][Get]
ICursors.Count [Property][Get]
ICursors.ItemByName [Property][Get]
ICursors.Create
[Method]
Creates a new TrendCursor at the given location.
Defined As
[VBA] Object Create(name As String, position As Integer)
[Cicode] OBJECT Create(STRING name, INT position)
[C++] HRESULT Create(BSTR name, int position, ITrendCursor**
ppTrendCursor)
Parameters
name
[in] The desired unique name of the new cursor. This must be between 1
and 250 characters.
position
[in] The initial position of the new cursor. This value is given as the number
of pixels from the left of the Process Analyst graph view.
Execution Result
If the function succeeds, the return value will be Success. If the name is out of
range, the return value will be InvalidArgument. If the name is not unique, the
return value will be InvalidArgument.
If an unexpected error occurs, the return value will be GeneralFailure.
Remarks
The cursor name must be unique. Attempting to create a cursor with a name that
is already in use will result in error and the new cursor will not be created.
Calling Syntax
[VBA]
Sub Example(cursors As Object)
Dim newCursor As Object
newCursor = cursors.Create(Cursor1, 100)
End Sub
[Cicode]
FUNCTION Example(OBJECT hCursors)
OBJECT hNewCursor = _ObjectCallMethod(hCursors, Create,
Cursor1, 100);
END
ICursors.RemoveAll
[Method]
Removes all cursors from the collection.
Defined As
[VBA] RemoveAll()
[Cicode] RemoveAll()
[C++] HRESULT RemoveAll()
Execution Result
occurs, the return value will be GeneralFailure.
Calling Syntax
This example assumes there is a valid Cursors object to be passed into the
example methods.
[VBA]
cursors.RemoveAll
End Sub
[Cicode]
_ObjectCallMethod(hCursors, "RemoveAll");
End Sub
ICursors.Item
[Property][Get]
Retrieves the Cursor from the collection at the specified index.
Defined As
[VBA] Object Item(index As Integer)
[Cicode] OBJECT get_Item(INT index)
[C++] HRESULT get_Item (long index, ITrendCursor **cursor)
Parameters
index
[in] The index of the required cursor.
Execution Result
If the index is out of range, the return value will be InvalidArgument. If the
collection is deleted, the return value will be GeneralFailure.
Remarks
The index for the collection is 1 based. The valid range for this parameter is
between 1 and the total number of cursors.
Calling Syntax
This example assumes you have a valid reference to the cursors collection and
that there are two items in the collection.
[VBA]
Sub Example(hCursors As Object)
Dim hSecondCursor As Object
Set hSecondCursor = hCursors.Item(2)
End Sub
[Cicode]
Sub Example(OBJECT hCursors)
OBJECT hSecondCursor = _ObjectCallMethod(hCursors, "get_Item",
2);
END
ICursors._NewEnum
[Property][Get]
Retrieves an enumerator for the cursors collection.
Defined As
[VBA] Object _NewEnum()
[C++] HRESULT get__NewEnum(LPUNKNOWN *pVal)
Execution Result
variable is bad, the return value will be InvalidArgument. If the collection is
deleted, the return value will be GeneralFailure.
Remarks
Provided for the implementation of For Each...Next loops in Citect VBA (See
Calling Syntax, below). This property cannot be used in Cicode.
Calling Syntax
This example assumes you have a valid reference to the cursors collection and
that there are cursors in the collection.
[VBA]
Dim cursor As Object
Dim count As Integer = 0
For Each cursor In cursors
Set count = count + 1
Next
End Sub
ICursors.Count
[Property][Get]
Returns the number of cursors in the collection.
Defined As
[VBA] Integer Count()
[Cicode] INT Count()
[C++] HRESULT get_Count (long *pCount)
Execution Result
variable is bad then the return value will be InvalidArgument. If the collection is
Remarks
This property may be used in conjunction with the Item property to iterate
through the collection in Cicode.
Calling Syntax
This example assumes you have a valid reference to the cursors collection.
[VBA]
Dim cursorCount As Integer
cursorCount = cursors.Count
End Sub
[Cicode]
INT cursorCount;
cursorCount = _ObjectGetProperty(hCursors, "Count");
END
ICursors.ItemByName
[Property][Get]
Retrieves the Cursor at the specified index.
Defined As
[VBA] Object ItemByName(name As String)
[Cicode] OBJECT get_ItemByName(STRING name)
[C++] HRESULT get_ItemByName (BSTR name, ITrendCursor **cursor)
Parameters
name
[in] The name of the required cursor.
Execution Result
variable is bad, the return value will be InvalidArgument. If the cursor is not
found, the return value will be InvalidArgument.
If the collection is deleted, the return value will be GeneralFailure.
Calling Syntax
This example assumes you have a valid reference to the cursors collection, and
that there is a cursor in the collection named MyCursor.
[VBA]
Dim cursor As Object
Set cursor = cursors.ItemByName("MyCursor")
End Sub
[Cicode]
OBJECT hCursor = _ObjectCallMethod(hCursors, "get_ItemByName",
"MyCursor");
END
ITrendCursor Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] ITrendCursor
Methods
ITrendCursor.GetValue [Method]
ITrendCursor.Delete [Method]
Properties
ITrendCursor.Color [Property][Get/Set]
ITrendCursor.Width [Property][Get/Set]
ITrendCursor.Position [Property][Get/Set]
ITrendCursor.Visible [Property][Get/Set]
ITrendCursor.Collection [Property][Get]
ITrendCursor.Name [Property][Get/Set]
ITrendCursor.PenLabelVisible [Property][Get/Set]
ITrendCursor.PenLabelWidth [Property][Get/Set]
ITrendCursor.PenLabelHeight [Property][Get/Set]
ITrendCursor.PenLabelX [Property][Get/Set]
ITrendCursor.PenLabelY [Property][Get/Set]
ITrendCursor.LabelsLocked [Property][Get/Set]
ITrendCursor.GetValue
[Method]
Gets the value at the cursor for the given pen.
Defined As
[VBA] GetValue(pen As Object, asLocal As Boolean, time As Date, milli As
Integer, value As String)
[Cicode] GetValue(OBJECT pen, INT asLocal, REAL time, INT milli,
STRING value)
[C++] HRESULT Create GetValue(IPen* pen, VARIANT_BOOL asLocal,
DATE *time, short *milli, BSTR *value)
Parameters
pen
[in] The pen for which the value is required.
asLocal
[in] Set to True (-1) if returned time is required in Local form (False (0) for
UTC).
time
[out] The time represented by the cursor position. This is accurate to one
second and must be combined with milli to give millisecond accuracy.
milli
[out] Added to time (see above) to give cursor time in millisecond accuracy.
value
[out] The value of the trend for the given pen at the returned time.
Execution Result
If the function succeeds, the return value will be Success. If one of the return
variables are bad, then the return value will be InvalidArgument. If the cursor is
Calling Syntax
This example assumes you have a valid reference to a cursor and a pen.
[VBA]
Sub Example(cursor As Object, pen As Object)
Dim asLocal As Boolean
Dim cursorTime As Date
Dim milli As Integer
Dim cursorValue As String
asLocal = 0
cursor.GetValue pen, asLocal, cursorTime, milli, cursorValue
End Sub
[Cicode]
FUNCTION Example(OBJECT hCursor, OBJECT hPen)
INT asLocal = 0;
REAL time;
INT milli;
STRING value;
_ObjectCallMethod(hCursor , "GetValue", hPen, asLocal, time,
milli, value);
END
ITrendCursor.Delete
[Method]
Deletes the cursor.
Defined As
[VBA] Delete()
[Cicode] Delete()
[C++] HRESULT Delete()
Execution Result
If the function succeeds, the return value will be Success. If the cursor is deleted,
Remarks
This method will remove the cursor from the Process Analyst. Any current
references to the cursor will continue to be valid; however, operations on them
will result in failure.
Calling Syntax
This example assumes you have a valid reference to a cursor.
[VBA]
Sub Example(cursor As Object)
cursor.Delete
End Sub
[Cicode]
FUNCTION Example(OBJECT hCursor)
_ObjectCallMethod(hCursor, "Delete");
END
ITrendCursor.Color
[Property][Get/Set]
Gets or Sets the line color of the cursor.
Defined As
[VBA] Long Color
[Cicode] INT Color
[C++] OLE_COLOR Color
Execution Result
variable is bad then the return value will be InvalidArgument. If the cursor is
Remarks
The Cicode function PackedRGB can be used to convert an RGB color
specification to the OLE_COLOR type used by the Process Analyst.
Calling Syntax
[VBA]
Dim trendCursorColor As Long
trendCursorColor = cursor.Color
Setting Property value (to red)
cursor.Color = 255
End Sub
[Cicode]
INT trendCursorColor;
trendCursorColor = _ObjectGetProperty(hCursor, Color);
// Setting Property to blue
_ObjectSetProperty(hCursor, Color, PackedRGB(0, 0, 255));
END
ITrendCursor.Width
[Property][Get/Set]
Gets or Sets the line width of the cursor.
Defined As
[VBA] Long Width
[Cicode] INT Width
[C++] int Width
Execution Result
Limits
Minimum (0)
Maximum (8)
Calling Syntax
[VBA]
lineWidth = cursor.Width
cursor.Width = 5
End Sub
[Cicode]
INT lineWidth;
lineWidth = _ObjectGetProperty(hCursor, Width);
// Setting Property to 5
_ObjectSetProperty(hCursor, Width, 5);
END
ITrendCursor.Position
[Property][Get/Set]
Get or Set the cursors physical position in the Process Analyst.
Defined As
[VBA] Long Position
[Cicode] INT Position
[C++] int Position
Execution Result
variable is bad, the return value will be InvalidArgument. If the cursor is
Remarks
The cursor position is measured as the number of pixels from the left of the
Process Analyst graph.
Calling Syntax
[VBA]
Dim position As Integer
position = cursor.Position
cursor.Position = 300
End Sub
[Cicode]
INT position;
position = _ObjectGetProperty(hCursor, Position);
// Setting Property to (300)
_ObjectSetProperty(hCursor, Position, 300);
END
ITrendCursor.Visible
[Property][Get/Set]
Get or Set whether the cursor is visible.
Defined As
[VBA] Boolean Visible
[Cicode] INT Visible
[C++] VARIANT_BOOL Visible
Execution Result
Remarks
This property controls the visibility of the cursor. The visibility is also applied to
all labels associated with the cursor.
See Also ITrendCursor.PenLabelVisible [Property][Get/Set]
Calling Syntax
[VBA]
Dim visibility As Boolean
visibility = cursor.Visible
Setting Property value (False)
cursor.Visible = False
End Sub
[Cicode]
INT visibility;
visibility = _ObjectGetProperty(hCursor, Visible);
// Setting Property to False (0)
_ObjectSetProperty(hCursor, Visible, 0);
END
ITrendCursor.Collection
[Property][Get]
Obtain a reference to the ICursors collection that contains the cursor.
Defined As
[VBA] Object Collection
[Cicode] OBJECT Collection
[C++] HRESULT Collection(ICursors **cursor)
Execution Result
Calling Syntax
[VBA]
Dim cursors As Object
Getting Property collection
Set cursors = cursor.Collection
End Sub
[Cicode]
OBJECT hCursors;
// Getting collection
hCursors = _ObjectGetProperty(hCursor, Collection);
END
ITrendCursor.Name
[Property][Get/Set]
Get or Set the Name of the cursor.
Defined As
[VBA] String Name
[Cicode] STRING Name
[C++] BSTR Name
Execution Result
variable is bad, the return value will be InvalidArgument. If the name is 0
characters or greater than 250, the return value will be InvalidArgument.
If the cursor is deleted, the return value will be GeneralFailure.
Remarks
When setting the name property, remember that cursor names must be unique.
Setting the Name property will fail if a cursor with that name already exists.
Calling Syntax
[VBA]
Dim name As String
name = cursor.Name
cursor.Name = NewCursor
End Sub
[Cicode]
STRING name;
name = _ObjectGetProperty(hCursor, Name);
// Setting Property
_ObjectSetProperty(hCursor, Name, NewCursor);
END
ITrendCursor.PenLabel
Visible [Property][Get/
Set]
Get or Set the label visibility of the specified pen on this cursor.
Defined As
[VBA] Boolean PenLabelVisible(pen As Object)
[Cicode] INT PenLabelVisible(OBJECT pen)
[C++] HRESULT PenLabelVisible(IPen* pen, VARIANT_BOOL labelVisible)
Parameters
pen
[in] The pen for which cursor label is to be referenced.
Execution Result
Limits
True (-1): Label is visible.
False (0): Label is hidden.
Remarks
Setting the visibility of the cursor using the Visible property will override the
pen label visibility. For example, if a particular label is hidden using
PenLabelVisible, this label will be shown again if Visible is set to True (-1).
See Also ITrendCursor.Visible [Property][Get/Set]
Calling Syntax
[VBA]
Dim labelVisible As Boolean
labelVisible = cursor.PenLabelVisible(pen)
cursor.PenLabelVisible(pen) = False
End Sub
[Cicode]
INT labelVisible;
labelVisible = _ObjectCallMethod(hCursor,
"get_PenLabelVisible", hPen);
// Setting Property to FALSE
_ObjectCallMethod(hCursor , "put_PenLabelVisible", hPen, 0);
END
Width [Property][Get/
Set]
Get or Set the label width of the specified pen on this cursor.
Defined As
[VBA] Double PenLabelWidth(pen As Object)
[Cicode] REAL PenLabelWidth (OBJECT pen)
[C++] HRESULT PenLabelWidth (IPen* pen, double labelWidth)
Parameters
pen
Execution Result
Remarks
The value of width is represented in pixels.
See Also ITrendCursor.PenLabelHeight [Property][Get/Set],
ITrendCursor.PenLabelX [Property][Get/Set], ITrendCursor.PenLabelY
[Property][Get/Set]
Calling Syntax
[VBA]
Dim labelWidth As Double
labelWidth = cursor.PenLabelWidth(pen)
Setting Property value (100)
cursor.PenLabelWidth(pen) = 100
End Sub
[Cicode]
REAL labelWidth;
labelWidth = _ObjectCallMethod(hCursor , "get_PenLabelWidth",
hPen);
_ObjectCallMethod(hCursor , "put_PenLabelWidth", hPen, 100);
END
Height [Property][Get/
Set]
Get or Set the label height of the specified pen on this cursor.
Defined As
[VBA] Double PenLabelHeight(pen As Object)
[Cicode] REAL PenLabelHeight (OBJECT pen)
[C++] HRESULT PenLabelHeight (IPen* pen, double labelHeight)
Parameters
pen
Execution Result
Remarks
The value of height is represented in pixels.
See Also ITrendCursor.PenLabelWidth [Property][Get/Set],
ITrendCursor.PenLabelX [Property][Get/Set], ITrendCursor.PenLabelY
[Property][Get/Set]
Calling Syntax
[VBA]
Dim labelHeight As Double
labelHeight = cursor.PenLabelHeight(pen)
cursor.PenLabelHeight (pen) = 100
End Sub
[Cicode]
REAL labelHeight;
labelHeight = _ObjectCallMethod(hCursor , "get_PenLabelHeight",
hPen);
_ObjectCallMethod(hCursor , "put_PenLabelHeight", hPen, 100);
END
X [Property][Get/Set]
Get or Set the labels X-Axis position of the specified pen on this cursor.
Defined As
[VBA] Double PenLabelX(pen As Object)
[Cicode] REAL PenLabelX (OBJECT pen)
[C++] HRESULT PenLabelX (IPen* pen, double labelX)
Parameters
pen
Execution Result
Remarks
The label position is represented in pixels.
See Also ITrendCursor.PenLabelWidth [Property][Get/Set],
ITrendCursor.PenLabelHeight [Property][Get/Set],
ITrendCursor.PenLabelY [Property][Get/Set]
Calling Syntax
[VBA]
Dim labelX As Double
labelX = cursor.PenLabelX(pen)
cursor.PenLabelX(pen) = 100
End Sub
[Cicode]
REAL labelX;
labelX = _ObjectCallMethod(hCursor , "get_PenLabelX", hPen);
_ObjectCallMethod(hCursor , "put_PenLabelX", hPen, 100);
END
Y [Property][Get/Set]
Get or Set the labels Y-Axis position of the specified pen on this cursor.
Defined As
[VBA] Double PenLabelY(pen As Object)
[Cicode] REAL PenLabelY (OBJECT pen)
[C++] HRESULT PenLabelY (IPen* pIPen, double labelY)
Remarks
The label position is represented in pixels
Syntax ITrendCursor.PenLabelWidth [Property][Get/Set],
ITrendCursor.PenLabelHeight [Property][Get/Set],
ITrendCursor.PenLabelX [Property][Get/Set]
Calling Syntax
[VBA]
Dim labelY As Double
labelY = cursor.PenLabelY(pen)
cursor.PenLabelY(pen) = 100
End Sub
[Cicode]
REAL labelY;
labelY = _ObjectCallMethod(hCursor , "get_PenLabelY", hPen);
_ObjectCallMethod(hCursor , "put_PenLabelY", hPen, 100);
END
ITrendCursor.LabelsLoc
ked [Property][Get/Set]
Get or Set whether the cursor label positions are locked.
Defined As
[VBA] Boolean LabelsLocked
[Cicode] INT LabelsLocked
[C++] VARIANT_BOOL LabelsLocked
Limits
True (-1): Labels are locked
False (0): Labels are unlocked
Remarks
If labels are locked, they will not move when the cursor position is changed.
Calling Syntax
[VBA]
Dim labelsLocked As Boolean
labelsLocked = cursor.LabelsLocked
cursor.LabelsLocked = False
End Sub
[Cicode]
INT labelsLocked;
labelsLocked = _ObjectGetProperty(hCursor, LabelsLocked);
// Setting Property to False (0)
_ObjectSetProperty(hCursor, LabelsLocked, 0);
END
IPen Interface
Methods
IPen.AddSample
IPen.Clear [Method]
IPen.Delete [Method]
IPen.GetDefaultSpan [Method]
IPen.GetHorizontalAxisTimeSpan [Method]
IPen.GetInformation [Method]
IPen.GetStatistic [Method]
IPen.GetVerticalAxisSpan [Method]
IPen.GoToNow [Method]
IPen.HorizontalScrollBy [Method]
IPen.HorizontalZoom [Method]
IPen.PutHorizontalAxisTimeSpan [Method]
IPen.PutVerticalAxisSpan [Method]
IPen.RefreshData [Method]
IPen.ResetToDefaultSpan [Method]
IPen.Select [Method]
IPen.SetDefaultSpan [Method]
IPen.SetQualityCompactionPointType [Method]
IPen.SetQualityLineStyle [Method]
IPen.SetVerticalAxisLabelValue [Method]
IPen.VerticalScrollBy [Method]
IPen.VerticalZoom [Method]
Properties
IPen.AxisBackgroundColor [Property][Get/Set]
IPen.BlockRepaint [Property][Get/Set]
IPen.Collection [Property][Get]
IPen.DataPoint [Property][Get/Set]
IPen.DataServer [Property][Get/Set]
IPen.Height [Property][Get/Set]
IPen.HorizontalAxisColor [Property][Get/Set]
IPen.HorizontalAxisResize [Property][Get/Set]
IPen.HorizontalAxisScroll [Property][Get/Set]
IPen.HorizontalAxisWidth [Property][Get/Set]
IPen.HorizontalGridlinesColor [Property][Get/Set]
IPen.HorizontalGridlinesStyle [Property][Get/Set]
IPen.HorizontalGridlinesWidth [Property][Get/Set]
IPen.HorizontalMinorGridlinesColor [Property][Get/Set]
IPen.HorizontalMinorGridlinesStyle [Property][Get/Set]
IPen.IsDeleted [Property][Get]
IPen.IsSelected [Property][Get]
IPen.LocalTime [Property][Get/Set]
IPen.Name [Property][Get/Set]
IPen.PointsVisible [Property][Get/Set]
IPen.RequestMode [Property][Get/Set]
IPen.Stacked [Property][Get/Set]
IPen.TrendCursorLabelFillColor [Property][Get/Set]
IPen.TrendCursorLabelLineColor [Property][Get/Set]
IPen.TrendCursorLabelTextColor [Property][Get/Set]
IPen.VerticalAxisAutoscale [Property][Get/Set]
IPen.VerticalAxisColor [Property][Get/Set]
IPen.VerticalAxisLabelType [Property][Get/Set]
IPen.VerticalAxisResize [Property][Get/Set]
IPen.VerticalAxisScroll [Property][Get/Set]
IPen.VerticalAxisWidth [Property][Get/Set]
IPen.VerticalGridlinesColor [Property][Get/Set]
IPen.VerticalGridlinesStyle [Property][Get/Set]
IPen.VerticalGridlinesWidth [Property][Get/Set]
IPen.VerticalMinorGridlinesColor [Property][Get/Set]
IPen.VerticalMinorGridlinesStyle [Property][Get/Set]
IPen.Visible [Property][Get/Set]
IPen.AddSample
Adds a temporary sample to a pen.
Defined As
[VBA] AddSample(value As Double, timeStamp as Date, milli as Integer,
qualityType as Integer, compactionType as Integer)
[Cicode] AddSample(REAL value, DATE timeStamp, INT milli, INT
qualityType, INT compactionType)
[C++] HRESULT AddSample(double value, DATE timeStamp, short milli,
QualityType qualityType, QualityCompactionType compactionType)
Parameters
value
[in] Indicates the value of the sample that will be added.
timeStamp
[in] Indicates at what time the sample will occur in UTC time.
milli
[in] Indicates the millisecond component of the time stamp (0 to 999).
qualityType
[in] Indicates the quality of the sample that will be added.
compactionType
[in] Indicates what display type the sample will be represented as.
Execution Result
If the function succeeds, the return value will be Success. If an argument is bad,
the return value will be InvalidArgument. If an argument is out of range, the
return value will be InvalidArgument. If the pen is deleted, the return value will
be GeneralFailure. If any other unexpected error occurs, the return value will be
GeneralFailure.
Remarks
This function has limited use as the samples added are stored in a temporary
cache; they can be cleared anytime by time span changes, data refresh calls, or
automation.
You can only add samples to analog or digital pens.
See Also QualityType [Enumeration], QualityCompactionType [Enumeration]
Calling Syntax
Assumes you have passed a valid pen object into the function.
[VBA]
Sub Example(pen As Object)
Dim timeStamp As Date
timestamp = Now
pen.AddSample 75.0, timeStamp, 100, 0, 0
End Sub
[Cicode]
FUNCTION Example(OBJECT hPen)
DATE timeStamp;
timestamp = TimeCurrent(); // Returns seconds since 1970
timestamp = CitectToUTC(timestamp); // Convert to OLE UTC time
_ObjectCallMethod(hPen, AddSample, 75.0, timeStamp, 100, 0,
0);
END
IPen.Clear [Method]
Clears all samples belonging to this pen from the internal cache. (Note: This does
not remove logged samples from the server)
Defined As
[VBA] Clear()
[Cicode] Clear()
[C++] HRESULT Clear()
Execution Result
If the function succeeds the return value will be Success. If the pen is deleted
then the return value will be GeneralFailure.
Calling Syntax
[VBA]
pen.Clear
End Sub
[Cicode]
_ObjectCallMethod(hPen, Clear);
END
IPen.Delete [Method]
Deletes the pen from the Process Analyst.
Defined As
[VBA] Delete()
[Cicode] Delete()
Execution Result
If the function succeeds, the return value will be Success. If the pen is already
Remarks
Calling this method will mark the pen for deletion, meaning any further calls to
methods or properties on the pen will result in a GeneralFailure error. The pen
will be removed from the display immediately after making this call.
See Also IPen.IsDeleted [Property][Get]
Calling Syntax
[VBA]
pen.Delete
End Sub
[Cicode]
_ObjectCallMethod(hPen, Delete);
END
IPen.GetDefaultSpan
[Method]
Returns the default time span for this pen as a series of time components.
Defined As
[VBA] GetDefaultSpan(weeks As Integer, days As Integer, hours As Integer,
minutes As Integer, seconds As Integer, milliseconds As Integer)
[Cicode] GetDefaultSpan (INT weeks, INT days, DATE hours, INT minutes,
INT seconds, INT milliseconds)
[C++] HRESULT GetDefaultSpan (short* weeks, short* days, short* hours,
short* minutes, short* seconds, short* milliseconds)
Parameters
weeks
[out] Indicates the number of weeks in the span.
days
[out] Indicates the number of days in the span.
hours
[out] Indicates the number of hours in the span.
minutes
[out] Indicates the number of minutes in the span.
seconds
[out] Indicates the number of seconds in the span.
milliseconds
[out] Indicates the number of milliseconds in the span.
Execution Result
the return value will be InvalidArgument. If the pen is deleted, the return value
will be GeneralFailure. If any other unexpected error occurs, the return value
will be GeneralFailure.
See Also IPen.SetDefaultSpan [Method], IPen.ResetToDefaultSpan [Method]
Calling Syntax
[VBA]
Dim weeks As Integer
Dim days As Integer
Dim hours As Integer
Dim minutes As Integer
Dim seconds As Integer
Dim milliseconds As Integer
pen.GetDefaultSpan weeks, days, hours, minutes, seconds,
milliseconds
End Sub
[Cicode]
INT weeks;
INT days;
INT hours;
INT minutes;
INT seconds;
INT milliseconds;
_ObjectCallMethod(hPen, GetDefaultSpan, weeks, days, hours,
minutes, seconds, milliseconds);
END
IPen.GetHorizontalAxis
TimeSpan [Method]
Returns the start and end time of this pen in local or UTC time format.
Defined As
[VBA] GetHorizontalAxisTimeSpan(startTime As Date, startMs as Integer,
endTime as Date, endMs as Integer, localTime as Boolean)
[Cicode] GetHorizontalAxisTimeSpan (REAL startTime, INT startMs, REAL
endTime, INT endMs, INT localTime)
[C++] HRESULT GetHorizontalAxisTimeSpan (DATE* startTime, short*
startMs, DATE* endTime, short* endMs, VARIANT_BOOL localTime)
Parameters
startTime
[out] This will contain the beginning date and time without milliseconds of
the time span.
startMs
[out] This will contain the milliseconds component of the start time.
endTime
[out] This will contain the end date and time without milliseconds.of the
time span.
endMs
[out] This will contain the milliseconds component of the end time.
localTime
[in] Indicates whether the times returned are in local time or UTC. True = -
1, False (0) = UTC.
Execution Result
See Also IPen.PutHorizontalAxisTimeSpan [Method]
Calling Syntax
[VBA]
Dim startDate As Date
Dim endDate As Date
Dim startMs As Integer
Dim endMs As Integer
pen.GetHorizontalAxisTimeSpan startDate, startMs, endDate,
endMs, True
End Sub
[Cicode]
REAL startDate;
REAL endDate;
INT startMs;
INT endMs;
_ObjectCallMethod(hPen, GetHorizontalAxisTimeSpan, startDate,
startMs, endDate, endMs, -1);
END
IPen.GetInformation
[Method]
Returns information associated with this pen.
Defined As
[VBA] GetInformation(name As String) As String
[Cicode] STRING GetInformation(STRING name)
[C++] HRESULT GetDefaultSpan (BSTR name, BSTR* value)
Parameters
name
[in] Specify the pen information attribute you want to get the value for. See
Remarks below for supported attributes.
value
[out] Indicates the value of the specified information attribute.
Execution Result
the return value will be InvalidArgument. If the attribute does not exist, the
GeneralFailure.
Information Attributes
Calling Syntax
[VBA]
Dim duration As String
duration = pen.GetInformation "Duration"
End Sub
[Cicode]
Attribute Returns Applies to
Alarm Area Alarm tag field Alarm
Alarm Category Alarm tag field Alarm
Alarm Desc Alarm tag field Alarm
Alarm Name Alarm tag field Alarm
Alarm Type Alarm tag field Alarm
Comment Alarm/Trend tag comment field All
Duration Process Analyst time span All
End Time Process Analyst axis end time All
Engineering Full Scale Trend tag field Analog, Digital
Engineering Units Trend tag field Analog, Digital
Engineering Zero Scale Trend tag field Analog, Digital
Error Process Analyst error status All
Full Scale Process Analyst vertical axis max scale Analog,
Name Process Analyst pen name All
Raw Full Scale Trend tag field Analog, Digital
Raw Zero Scale Trend tag field Analog, Digital
Sample Period Trend tag field Analog, Digital
Start Time Process Analyst axis start time All
Tag Process Analyst source binding field All
Trend Type Trend tag field Analog, Digital
Zero Scale Process Analyst vertical axis min scale Analog
Scale Process Analyst vertical axis scale range Analog, Digital
Engineering Scale Engineering scale range Analog, Digita
STRING duration;
duration = _ObjectCallMethod(hPen, "GetInformation",
"Duration");
END
IPen.GetStatistic
[Method]
Returns the result of a specified Process Analyst statistical operation.
Defined As
[VBA] GetStatistic(name As String, value As String)
[Cicode] GetStatistic(STRING name, STRING value)
[C++] HRESULT GetStatistic(BSTR name, BSTR* value)
Parameters
name
[in] Specify the statistic attribute you want to get the value for. See Remarks
below for supported attributes.
value
[out] Indicates the value of the specified statistic attribute.
Execution Result
the return value will be InvalidArgument. If the attribute does not exist, the
GeneralFailure.
Information Attributes
Calling Syntax
[VBA]
Dim average As String
pen.GetStatistic Average, average
End Sub
[Cicode]
Attribute Returns Applies to
Average Process Analyst real-time average Analog, Digital
Maximum Process Analyst real-time maximum Analog
Minimum Process Analyst real-time minimum Analog
STRING average;
_ObjectCallMethod(hPen, GetStastic, Average, average);
END
IPen.GetVerticalAxisSp
an [Method]
Returns the current span of the pens vertical axis.
Defined As
[VBA] GetVerticalAxisSpan(startValue As Double, endValue As Double)
[Cicode] GetVerticalAxisSpan (REAL startValue, REAL endValue)
[C++] HRESULT GetVerticalAxisSpan (double* startValue, double*
endValue)
Parameters
startValue
[out] The current lower bound of the vertical axis.
endValue
[out] The current upper bound of the vertical axis.
Execution Result
See Also IPen.PutVerticalAxisSpan [Method]
Calling Syntax
[VBA]
Dim startValue As Double
Dim endValue As Double
pen.GetVerticalAxisSpan startValue, endValue
End Sub
[Cicode]
REAL startValue;
REAL endValue;
_ObjectCallMethod(hPen, GetVerticalAxisSpan, startValue,
endValue);
END
IPen.GoToNow [Method]
Synchronizes the end time of the pens span with your computers current local
time. The start time will also be moved to maintain the pens current time span.
Defined As
[VBA] GoToNow()
[Cicode] GoToNow()
[C++] HRESULT GoToNow()
Execution Result
If the function succeeds, the return value will be Success. If the pen is deleted,
Calling Syntax
[VBA]
pen.GoToNow
End Sub
[Cicode]
_ObjectCallMethod(hPen, GoToNow);
END
IPen.HorizontalScrollBy
[Method]
Scrolls the horizontal axis by the specified factor.
Defined As
[VBA] HorizontalScrollBy(factor As Double)
[Cicode] HorizontalScrollBy(REAL factor)
[C++] HRESULT HorizontalScrollBy(double factor)
Parameters
factor
[in] Controls the direction and amount the axis will be scrolled. A negative
value will move the axis back in time; a positive value will move the axis
forward in time. The value is a percentage representing the current viewable
span. So if the pen span is 1 hour, and you specify a factor of 0.5, you will
move the time span 30 minutes into the future.
Execution Result
If the function succeeds, the return value will be Success. If the argument is bad,
See Also IPen.VerticalScrollBy [Method]
Calling Syntax
[VBA]
Move the pen span back one complete span into history
pen.HorizontalScrollBy -1.0
End Sub
[Cicode]
// Move the pen span back one complete span into history
_ObjectCallMethod(hPen, HorizontalScrollby, -1.0);
END
IPen.HorizontalZoom
[Method]
Zooms centrally into the time span by the given factor.
Defined As
[VBA] HorizontalZoom(factor As Double)
[Cicode] HorizontalZoom(REAL factor)
[C++] HRESULT HorizontalZoom(double factor)
Parameters
factor
[in] Controls the direction and amount the axis will be zoomed. Acceptable
zoom values are 0 to 1 (Zoom out) and > 1 (zoom in).
Execution Result
If the function succeeds the return value will be Success. If the argument is bad
then the return value will be InvalidArgument. If the argument is out of range
then the return value will be InvalidArgument. If the pen is deleted then the
See Also IPen.VerticalZoom [Method]
Calling Syntax
[VBA]
Zoom out 50%
pen.HorizontalZoom 0.5
Undo the Zoom
pen.HorizontalZoom 1.5
End Sub
[Cicode]
// Zoom out 50%
_ObjectCallMethod(hPen, HorizontalZoom, 0.5);
// Undo the Zoom
_ObjectCallMethod(hPen, HorizontalZoom, 2.0);
END
IPen.PointsVisible
[Property][Get/Set]
Gets or Sets whether the sample points are displayed or hidden on the pen.
Defined As
[VBA] Boolean PointsVisible
[Cicode] INT PointsVisible
[C++] VARIANT_BOOL PointsVisible
Execution Results
Limits
True(-1): Points are visible
False(0): Points are hidden
Remarks
By default this property is False, meaning that any point type you have set using
the SetQualityCompactionPointType function will be hidden.
Calling Syntax
[VBA]
Dim visible As Boolean
visible = pen.PointsVisible
pen.PointsVisible = True
End Sub
[Cicode]
INT visible;
visible = _ObjectGetProperty(hPen, "PointsVisible");
// Setting Property value
_ObjectSetProperty(hPen, "PointsVisible", -1);
END
IPen.PutHorizontalAxis
TimeSpan [Method]
Sets the start and end time of this pen.
Defined As
[VBA] PutHorizontalAxisTimeSpan(startTime As Date, startMs as Integer,
endTime as Date, endMs as Integer)
[Cicode] PutHorizontalAxisTimeSpan (REAL startTime, INT startMs, REAL
endTime, INT endMs)
[C++] HRESULT PutHorizontalAxisTimeSpan (DATE* startTime, short*
startMs, DATE* endTime, short* endMs)
Parameters
startTime
[in] Indicates the beginning date and time without milliseconds of the time
span in UTC format.
startMs
[in] Indicates the milliseconds component of the start time.
endTime
[in] Indicates the end date and time without milliseconds of the time span
in UTC format.
endMs
[in] This will contain the milliseconds component of the end time.
Execution Result
If the function succeeds the return value will be Success. If an argument is bad
then the return value will be InvalidArgument. If an argument is out of range
return value will be GeneralFailure. If any other unexpected error occurs the
Remarks
The Process Analyst only supports setting its axis in UTC (Universal Co-
ordinated Time) format. This means you must convert from local to UTC format
yourself to make the axis display correctly in local time. Cicode provides several
functions to do these conversions.
Limits
The horizontal axis has an upper limit of 1/1/2100 12:00:00.000 and a lower limit
of 1/1/1900 12:00:00.000. The minimum span is 100 milliseconds. The maximum
span is 200 years.
See Also IPen.GetHorizontalAxisTimeSpan [Method]
Calling Syntax
[VBA]
Dim startDate As Date
Dim endDate As Date
Dim startMs As Integer
Dim endMs As Integer
startDate = CDate(16/6/2004 11:30:00)
endDate = CDate(16/6/2004 12:29:00)
startMs = 0
endMs = 0
pen.PutHorizontalAxisTimeSpan startDate, startMs, endDate,
endMs
End Sub
[Cicode]
REAL startDate;
REAL endDate;
startDate = StrToDate("16/6/04") + StrToTime("9:30:00");
endDate = StrToDate("16/6/04") + StrToTime("10:29:00");
startDate = TimeToOLEDate(startDate, 0); // Convert to UTC
endDate = TimeToOLEDate(endDate, 0); // Convert to UTC
_ObjectcallMethod(hPen, "PutHorizontalAxisTimeSpan", startDate,
0, endDate, 0);
END
IPen.PutVerticalAxisSpa
n [Method]
Sets the current position and span of the pens vertical axis.
Defined As
[VBA] GetVerticalAxisSpan(startValue As Double, endValue As Double)
[Cicode] GetVerticalAxisSpan (REAL startValue, REAL endValue)
[C++] HRESULT GetVerticalAxisSpan (double* startValue, double*
endValue)
Parameters
startValue
[in] Indicates the new lower bound of the vertical axis.
endValue
[in] Indicates the new upper bound of the vertical axis.
Execution Result
the return value will be InvalidArgument. If an argument is out of range, or the
span is out of range, the return value will be InvalidArgument. If the pen is
Limits
The vertical axis has a upper limit of 1+e10 and a lower limit of 1-e10. However,
the maximum span supported is 1+e10. The minimum span is 0.00001.
See Also IPen.GetVerticalAxisSpan [Method]
Calling Syntax
[VBA]
pen.PutVerticalAxisSpan 200.5, 300.34
End Sub
[Cicode]
_ObjectCallMethod(hPen, PutVerticalAxisSpan, 200.5, 300.34);
END
IPen.RefreshData
[Method]
Clears all samples belonging to this pen from the internal cache and then issues
a new request for data.
Defined As
[VBA] RefreshData()
[Cicode] RefreshData ()
[C++] HRESULT RefreshData ()
Execution Result
If the function succeeds the return value will be Success. If the pen is deleted
then the return value will be GeneralFailure.
Calling Syntax
[VBA]
pen.RefreshData
End Sub
[Cicode]
_ObjectCallMethod(hPen, RefreshData);
END
IPen.ResetToDefaultSpa
n [Method]
Resets the span of this pen to its default span.
Defined As
[VBA] ResetToDefaultSpan()
[Cicode] ResetToDefaultSpan()
[C++] HRESULT ResetToDefaultSpan()
Execution Result
Remarks
The default span of all pens is 10 minutes. This can be modified by using
IPen.SetDefaultSpan.
See Also IPen.GetDefaultSpan [Method], IPen.SetDefaultSpan [Method]
Calling Syntax
[VBA]
pen.ResetToDefaultSpan
End Sub
[Cicode]
_ObjectCallMethod(hPen, ResetToDefaultSpan);
END
IPen.Select [Method]
Makes this pen the primary selected pen.
Defined As
[VBA] Select()
[Cicode] Select()
[C++] HRESULT Select()
Execution Result
Remarks
Calling this method will also trigger PenSelectionChanged [Event].
Calling Syntax
[VBA]
pen.Select
End Sub
[Cicode]
_ObjectCallMethod(hPen, Select);
END
IPen.SetDefaultSpan
[Method]
Sets the default time span for this pen.
Defined As
[VBA] SetDefaultSpan(weeks As Integer, days As Integer, hours As Integer,
minutes As Integer, seconds As Integer, milliseconds As Integer)
[Cicode] SetDefaultSpan (INT weeks, INT days, DATE hours, INT minutes,
INT seconds, INT milliseconds)
[C++] HRESULT SetDefaultSpan (short weeks, short days, short hours, short
minutes, short seconds, short milliseconds)
Parameters
weeks
[in] Indicates the number of weeks in the span.
days
[in] Indicates the number of days in the span.
hours
[in] Indicates the number of hours in the span.
minutes
[in] Indicates the number of minutes in the span.
seconds
[in] Indicates the number of seconds in the span.
milliseconds
[in] Indicates the number of milliseconds in the span.
Execution Result
See Also IPen.GetDefaultSpan [Method], IPen.ResetToDefaultSpan [Method]
Calling Syntax
[VBA]
Set span to 2 hours and 30 minutes
pen.GetDefaultSpan 0, 0, 2, 30, 0, 0
End Sub
[Cicode]
// Set span to 2 hours and 30 minutes
_ObjectCallMethod(hPen, SetDefaultSpan, 0, 0, 2, 30, 0, 0);
END
IPen.SetQualityCompac
tionPointType [Method]
Use this function to indicate what visual cue to display for single and multiple
samples.
Defined As
[VBA] SetQualityCompactionPoinType(compactionType As Integer,
pointType As Integer)
[Cicode] SetQualityCompactionPoinType(INT compactionType, INT
pointType)
[C++] HRESULT SetQualityCompactionPoinType(QualityCompactionType
compactionType, PointType pointType)
Parameters
compactionType
[in] Indicates which sample compaction type you want to set the visual cue
for.
pointType
[in] Indicates which visual cue to use for the selected compaction type.
Execution Result
See Also QualityCompactionType [Enumeration], PointType [Enumeration]
Calling Syntax
[VBA]
Set single samples to lsook like triangles
pen.SetQualityCompactionType 0, 5
End Sub
[Cicode]
// Set single samples to look like triangles
_ObjectCallMethod(hPen, "SetQualityCompactionPointType", 0, 5);
END
IPen.SetQualityLineStyl
e [Method]
This function can be used to change the type of line drawn for each of the quality
states defined by the Process Analyst for this Pen only.
Defined As
[VBA] SetQualityLineStyle(qualityType As Integer, lineStyle As Integer)
[Cicode] SetQualityLineStyle(INT qualityType, INT lineStyle)
[C++] HRESULT SetQualityLineStyle(QualityType qualityType, LineStyle
lineStyle)
Parameters
qualityType
[in] Indicates which quality type you want to set the visual cue for.
lineStyle
[in] Indicates which line style visual cue to use for the selected quality type.
Execution Result
Remarks
When a sample is added to the display, its quality value indicates how the line
drawn from that sample to the next one will be displayed.
See Also QualityType [Enumeration], LineStyle [Enumeration]
Calling Syntax
[VBA]
Set all lines drawn after NA samples to be drawn as dash_dot
pen.SetQualityLineStyle 1, 3
End Sub
[Cicode]
// Set all lines drawn after NA samples to be drawn as dash_dot
_ObjectCallMethod(hPen, SetQualityLineStyle, 1, 3);
END
IPen.SetVerticalAxisLab
elValue [Method]
This function can be used to display custom text for a particular value on the
Vertical Axis.
Defined As
[VBA] SetVerticalAxisLabelValue(value As Double, label As String)
[Cicode] SetVerticalAxisLabelValue(REAL value, STRING label)
[C++] HRESULT SetVerticalAxisLabelValue(double value, BSTR label)
Parameters
value
[in] Indicates which value you want to replace with a custom label.
label
[in] Indicates the text that will be displayed instead of the specified value.
Execution Result
Calling Syntax
[VBA]
Change the vertical axis to display High High instead of 95
pen.SetVerticalAxisLabelValue 95, High High
End Sub
[Cicode]
// Change the vertical axis to display High High instead of 95
_ObjectCallMethod(hPen, SetVerticalAxisLabelValue, 95, High
High);
END
IPen.VerticalScrollBy
[Method]
Scrolls the vertical axis by the specified factor.
Defined As
[VBA] VerticalScrollBy(factor As Double)
[Cicode] VerticalScrollBy(REAL factor)
[C++] HRESULT VerticalScrollBy(double factor)
Parameters
factor
[in] Controls the direction and amount the axis will be scrolled. A negative
value will move the axis in the negative direction. A positive value will
move the axis forward in the positive direction. The value is a percentage
representing the current viewable span. So if the pen span is 100 units (10 to
110), and you specify a factor of 0.5 then you will move the span 50 units (60
to 160).
Execution Result
See Also IPen.HorizontalScrollBy [Method]
Calling Syntax
[VBA]
Move the pen span forward one complete span
pen.VerticalScrollBy 1.0
End Sub
[Cicode]
// Move the pen span forward one complete span
_ObjectCallMethod(hPen, VerticalScrollby, 1.0);
END
IPen.VerticalZoom
[Method]
Zooms centrally into the time span by the given factor on the vertical axis
Defined As
[VBA] VerticalZoom(factor As Double)
[Cicode] VerticalZoom (REAL factor)
[C++] HRESULT VerticalZoom (double factor)
Parameters
factor
[in] Controls the direction and amount the axis will be zoomed. Acceptable
zoom values are 0 to 1 (Zoom out) and > 1 (zoom in).
Execution Result
then the return value will be InvalidArgument. If the argument is out of range
See Also IPen.HorizontalZoom [Method]
Calling Syntax
[VBA]
Zoom out 50%
pen.VerticalZoom 0.5
Undo the Zoom
pen.VerticalZoom 1.5
End Sub
[Cicode]
// Zoom out 50%
_ObjectCallMethod(hPen, VerticalZoom, 0.5);
// Undo the Zoom
_ObjectCallMethod(hPen, VerticalZoom, 2.0);
END
IPen.AxisBackgroundC
olor [Property][Get/Set]
Gets or sets the background color of the axis of this pen.
Defined As
[C++] OLE_COLOR BackgroundColor
Execution Result
deleted then the return value will be GeneralFailure.
Remarks
The background is the area underneath the axis lines and values.
To calculate the integer value required for a color apply the following formula
(65536 * Blue) + (256 * Green) + (Red). Where Red, Green and Blue are 0-255
Calling Syntax
[VBA]
backgroundColor = pen.AxisBackgroundColor
pen.AxisBackgroundColor = 255
End Sub
[Cicode]
INT backgroundColor;
backgroundColor = _ObjectGetProperty(hPen,
AxisBackgroundColor);
_ObjectSetProperty(hPen, AxisBackgroundColor, PackedRGB(255,
0, 0));
END
IPen.BlockRepaint
[Property][Get/Set]
Use this property to halt or continue any drawing updates to this pen.
Defined As
[VBA] Boolean BlockRepaint
[Cicode] INT BlockRepaint
[C++] VARIANT_BOOL BlockRepaint
Execution Result
Remarks
This property is useful if you are modifying several properties at once as it will
help reduce flicker and the amount of processing required. Simply set the
property to True (-1), change as many properties as you want, and then set the
property to False (0).
Calling Syntax
[VBA]
Dim blockRepaint As Boolean
blockRepaint = pen.BlockRepaint
pen.BlockRepaint = True
End Sub
[Cicode]
INT bBlockRepaint;
bBlockRepaint = _ObjectGetProperty(hPen, BlockRepaint);
// Setting Property
_ObjectSetProperty(hPen, BlockRepaint, -1);
END
IPen.Collection
[Property][Get]
Returns a reference to the Pens collection object that this pen belongs to.
Defined As
[C++] IPen* Collection
Execution Result
Calling Syntax
[VBA]
Dim pens As Object
Set pens = pen.Collection
End Sub
[Cicode]
OBJECT pens;
pens = _ObjectGetProperty(hPen, Collection);
END
IPen.DataPoint
[Property][Get/Set]
Get or Set the trend/alarm tag which this pen is bound to.
Defined As
[VBA] String DataPoint
[Cicode] STRING DataPoint
[C++] BSTR DataPoint
Execution Result
variable is bad, the return value will be InvalidArgument. If the tag is greater
than 79 characters, the return value will be InvalidArgument. If the pen is
Remarks
This property works in conjunction with the DataServer property. This property
can be changed during the lifetime of the pen. Changing the DataPoint property
will result in the data cache being cleared and a new data request issued. A
request for the tags information will also be issued.
See Also IPen.DataServer [Property][Get/Set]
Calling Syntax
[VBA]
Dim tag As String
tag = pen.DataPoint
pen.DataPoint = LOOP_1_PV
End Sub
[Cicode]
STRING tag;
tag = _ObjectGetProperty(hPen, DataPoint);
// Setting Property
_ObjectSetProperty(hPen, DataPoint, LOOP_1_PV);
END
IPen.DataServer
[Property][Get/Set]
Get or Set the server that this pen is bound to.
Defined As
[VBA] String DataServer
[Cicode] STRING DataServer
[C++] BSTR DataServer
Execution Result
variable is bad, the return value will be InvalidArgument. If the server
connection cannot be found, the return value will be InvalidArgument. If the
pen is deleted, the return value will be GeneralFailure.
Remarks
This property currently only supports two options, localhost and (empty
string), which indicates an unbound connection. Local host means the pen will
use the local CitectSCADA client to source data from the CitectSCADA trend/
alarm servers.
This property works in conjunction with the DataPoint property. This property
can be changed during the lifetime of the pen.
See Also IPen.DataPoint [Property][Get/Set]
Calling Syntax
[VBA]
Dim server As String
server = pen.DataServer
pen.DataPoint = localhost
End Sub
[Cicode]
STRING server;
server = _ObjectGetProperty(hPen, DataServer);
// Setting Property
_ObjectSetProperty(hPen, DataServer, localhost);
END
IPen.Height
[Property][Get/Set]
Get or Set the physical height in pixels that the pen will allocate for itself when
displayed in Stacked mode.
Defined As
[VBA] Integer Height
[Cicode] INT Height
[C++] double Height
Execution Result
variable is bad, the return value will be InvalidArgument. If height set is out of
range (16 1000), the return value will be InvalidArgument. If the pen is deleted,
Remarks
This property is ignored when the pen is not in Stacked mode.
See Also IPen.Stacked [Property][Get/Set]
Calling Syntax
[VBA]
Dim height As Boolean
`Getting Property value
height = pen.Height
`Setting Property value
pen.Height = 75
End Sub
[Cicode]
INT height;
height = _ObjectGetProperty(hPen, "Height");
// Setting Property
_ObjectSetProperty(hPen, "Height", 75);
END
IPen.HorizontalAxisCol
or [Property][Get/Set]
Gets or sets the color used to draw the line, labels, and interval markers of the
horizontal axis of this pen.
Defined As
[VBA] Long HorizontalAxisColor
[Cicode] INT HorizontalAxisColor
[C++] OLE_COLOR HorizontalAxisColor
Execution Result
Remarks
To calculate the integer value required for a color apply the following formula:
(65536 * Blue) + (256 * Green) + (Red)
See Also IPen.VerticalAxisColor [Property][Get/Set]
Calling Syntax
[VBA]
Dim color As Long
color = pen.HorizontalAxisColor
pen.HorizontalAxisColor = 255
End Sub
[Cicode]
INT color;
color = _ObjectGetProperty(hPen, HorizontalAxisColor);
_ObjectSetProperty(hPen, HorizontalAxisColor, PackedRGB(255,
0, 0));
END
IPen.HorizontalAxisResi
ze [Property][Get/Set]
Gets or sets whether this pen allows the operator to interactively scale the
horizontal axis using the mouse.
Defined As
[VBA] Boolean HorizontalAxisResize
[Cicode] INT HorizontalAxisResize
[C++] VARIANT_BOOL HorizontalAxisResize
Execution Result
Limits
True (-1): Axis can be resized
False (0): Axis cannot be resized
See Also IPen.VerticalAxisResize [Property][Get/Set]
Calling Syntax
[VBA]
Dim resize As Boolean
resize = pen.HorizontalAxisResize
pen.HorizontalAxisResize = False
End Sub
[Cicode]
INT bResize;
bResize = _ObjectGetProperty(hPen, HorizontalAxisResize);
// Setting Property
_ObjectSetProperty(hPen, HorizontalAxisResize,0);
END
IPen.HorizontalAxisScr
oll [Property][Get/Set]
Gets or sets whether this pen allows the operator to interactively scroll the
horizontal axis using the mouse.
Defined As
[VBA] Boolean HorizontalAxisScroll
[Cicode] INT HorizontalAxisScroll
[C++] VARIANT_BOOL HorizontalAxisScroll
Execution Result
Limits
True (-1): Axis can be scrolled
False (0): Axis cannot be scrolled
See Also IPen.VerticalAxisScroll [Property][Get/Set]
Calling Syntax
[VBA]
Dim scroll As Boolean
scroll = pen.HorizontalAxisScroll
pen.HorizontalAxisScroll = False
End Sub
[Cicode]
INT bScroll;
bScroll = _ObjectGetProperty(hPen, HorizontalAxisScroll);
// Setting Property
_ObjectSetProperty(hPen, HorizontalAxisScroll, 0);
END
IPen.HorizontalAxisWid
th [Property][Get/Set]
Gets or sets the width of the horizontal axis line and the associated interval
markers.
Defined As
[VBA] Integer HorizontalAxisWidth
[Cicode] INT HorizontalAxisWidth
[C++] short HorizontalAxisWidth
Execution Result
Limits
A valid width is 0-8 pixels.
See Also IPen.VerticalAxisWidth [Property][Get/Set]
Calling Syntax
[VBA]
Dim width As Integer
width = pen.HorizontalAxisWidth
pen.HorizontalAxisWidth = 3
End Sub
[Cicode]
INT width;
width = _ObjectGetProperty(hPen, HorizontalAxisWidth);
// Setting Property
_ObjectSetProperty(hPen, HorizontalAxisWidth, 3);
END
IPen.HorizontalGridline
sColor [Property][Get/
Set]
Gets or sets the color used to draw the major horizontal gridlines.
Defined As
[VBA] Long HorizontalGridlinesColor
[Cicode] INT HorizontalGridlinesColor
[C++] OLE_COLOR HorizontalGridlinesColor
Execution Result
Limits
Remarks
(65536 * Blue) + (256 * Green) + (Red). Where Red, Green and Blue are 0-255
See Also IPen.HorizontalMinorGridlinesColor [Property][Get/Set]
Calling Syntax
[VBA]
Dim color As Long
color = pen.HorizontalGridlinesColor
pen.HorizontalGridlinesColor = 255
End Sub
[Cicode]
INT color;
color = _ObjectGetProperty(hPen, HorizontalGridlinesColor);
_ObjectSetProperty(hPen, HorizontalGridlinesColor,
PackedRGB(255, 0, 0));
END
sStyle [Property][Get/
Set]
Gets or sets the line style used to draw the major horizontal gridlines.
Defined As
[VBA] Long HorizontalGridlinesStyle
[Cicode] INT HorizontalGridlinesStyle
[C++] LineStyle HorizontalGridlinesStyle
Execution Result
variable is bad, the return value will be InvalidArgument. If the style is out of
See Also IPen.HorizontalMinorGridlinesColor [Property][Get/Set], LineStyle
[Enumeration]
Calling Syntax
[VBA]
Dim style As Long
style = pen.HorizontalGridlinesStyle
Setting Property value to Dot
pen.HorizontalGridlinesColor = 2
End Sub
[Cicode]
INT style;
style = _ObjectGetProperty(hPen, HorizontalGridlinesStyle);
// Setting Property to Dot
_ObjectSetProperty(hPen, HorizontalGridlinesStyle, 2);
END
sWidth [Property][Get/
Set]
Gets or sets the line width used when drawing the major horizontal gridlines.
Defined As
[VBA] Integer HorizontalGridlinesWidth
[Cicode] INT HorizontalGridlinesWidth
[C++] short HorizontalGridlinesWidth
Execution Result
variable is bad, the return value will be InvalidArgument. If the width is out of
Calling Syntax
[VBA]
width = pen.HorizontalGridlinesWidth
pen.HorizontalGridlinesWidth = 3
End Sub
[Cicode]
INT width;
width = _ObjectGetProperty(hPen, HorizontalGridlinesWidth);
// Setting Property t
_ObjectSetProperty(hPen, HorizontalGridlinesWidth, 3);
END
IPen.HorizontalMinorGri
dlinesColor
[Property][Get/Set]
Gets or sets the color used to draw the minor horizontal gridlines.
Defined As
[VBA] Long HorizontalMinorGridlinesColor
[Cicode] INT HorizontalMinorGridlinesColor
[C++] OLE_COLOR HorizontalMinorGridlinesColor
Execution Result
Remarks
To calculate the integer value required for a color apply the following formula:
(65536 * Blue) + (256 * Green) + (Red)
See Also IPen.HorizontalGridlinesColor [Property][Get/Set]
Calling Syntax
[VBA]
Dim color As Long
color = pen.HorizontalMinorGridlinesColor
pen.HorizontalMinorGridlinesColor = 255
End Sub
[Cicode]
INT color;
color = _ObjectGetProperty(hPen,
HorizontalMinorGridlinesColor);
_ObjectSetProperty(hPen, HorizontalMinorGridlinesColor,
END
IPen.HorizontalMinorGri
dlinesStyle
[Property][Get/Set]
Gets or sets the line style used to draw the minor horizontal gridlines.
Defined As
[VBA] Long HorizontalMinorGridlinesStyle
[Cicode] INT HorizontalMinorGridlinesStyle
[C++] LineStyle HorizontalMinorGridlinesStyle
Execution Result
See Also IPen.HorizontalGridlinesStyle [Property][Get/Set], LineStyle
[Enumeration]
Calling Syntax
[VBA]
Dim style As Long
style = pen.HorizontalMinorGridlinesStyle
pen.HorizontalMinorGridlinesColor = 2
End Sub
[Cicode]
INT style;
style = _ObjectGetProperty(hPen,
HorizontalMinorGridlinesStyle);
_ObjectSetProperty(hPen, HorizontalMinorGridlinesStyle, 2);
END
IPen.IsDeleted
[Property][Get]
Returns whether this pen has been marked for deletion. That is, whether
someone has called the Delete method on it or deleted it from the display.
Defined As
[VBA] Boolean IsDeleted
[Cicode] INT IsDeleted
[C++] VARIANT_BOOL IsDeleted
Execution Result
See Also IPen.Delete [Method]
Calling Syntax
[VBA]
Dim deleted As Boolean
deleted = pen.IsDeleted
End Sub
[Cicode]
INT bDeleted;
bDeleted = _ObjectGetProperty(hPen, IsDeleted);
END
IPen.IsSelected
[Property][Get]
Returns whether this pen has been selected in the Process Analyst.
Defined As
[VBA] Boolean IsSelected
[Cicode] INT IsSelected
[C++] VARIANT_BOOL IsSelected
Execution Result
See Also IPen.Select [Method]
Calling Syntax
[VBA]
Dim selected As Boolean
selected = pen.IsSelected
End Sub
[Cicode]
INT bSelected;
bSelected = _ObjectGetProperty(hPen, IsSelected);
END
IPen.LocalTime
[Property][Get/Set]
Get or Set whether the axis will display time in the computers current local
format or in UTC (Universal Time Coordinate).
Defined As
[VBA] Boolean LocalTime
[Cicode] INT LocalTime
[C++] VARIANT_BOOL LocalTime
Execution Result
Limits
True (-1): Local format
False (0): UTC format
Calling Syntax
[VBA]
Dim localTime As Boolean
localTime = pen.LocalTime
Display time in UTC
pen.LocalTime = False
End Sub
[Cicode]
INT bLocalTime;
bLocalTime = _ObjectGetProperty(hPen, LocalTime);
// Display time in UTC
_ObjectSetProperty(hPen, LocalTime, 0);
END
IPen.Name
[Property][Get/Set]
Get or Set the name of this pen.
Defined As
[VBA] String Name
[C++] BSTR Name
Execution Result
variable is bad, the return value will be InvalidArgument. If the length of the
name is wrong then the return value will be InvalidArgument. If the pen is
Remarks
The Process Analyst will use this name extensively throughout the user interface
to reference this pen.
The name of the pen does not have to be unique, but it must be between 1 and
250 character long.
Calling Syntax
[VBA]
Dim name As String
name = pen.Name
Setting property value
pen.Name = NicePen
End Sub
[Cicode]
STRING name;
name = _ObjectGetProperty(hPen, Name);
_ObjectSetProperty(hPen, Name, NicePen);
END
IPen.RequestMode
[Property][Get/Set]
Get or Set how multiple samples will be calculated on the server.
Defined As
[VBA] Integer RequestMode
[Cicode] INT RequestMode
[C++] RequestMode RequestMode
Execution Result
variable is bad, the return value will be InvalidArgument. If the mode is out of
Remarks
When the pen makes a request for data and samples need to be compacted, it
will use this mode to determine how the compaction will occur.
Changing this mode will clear the data cache and issue a new request for data.
See Also RequestMode [Enumeration]
Calling Syntax
[VBA]
Dim requestMode As Integer
requestMode = pen.RequestMode
Setting mode to minimum
pen.RequestMode = 1
End Sub
[Cicode]
INT requestMode;
requestMode = _ObjectGetProperty(hPen, RequestMode);
// Setting mode to minimum
_ObjectSetProperty(hPen, RequestMode, 1);
END
IPen.Stacked
[Property][Get/Set]
Get or Set whether the pen is visually displayed stacked or overlaid.
Defined As
[VBA] Boolean Stacked
[Cicode] INT Stacked
[C++] VARIANT_BOOL Stacked
Execution Result
Limits
True (-1): Stacked
False (0): Overlaid
Remarks
When stacked, pens will be drawn under each other; when overlaid, the pens
will be drawn over the top of each other.
Calling Syntax
[VBA]
Dim stacked As Boolean
stacked = pen.Stacked
pen.Stacked = True
End Sub
[Cicode]
INT bStacked;
bStacked = _ObjectGetProperty(hPen, Stacked);
_ObjectSetProperty(hPen, Stacked, -1);
END
IPen.TrendCursorLabel
FillColor [Property][Get/
Set]
Gets or sets the fill color used for any cursor label associated with this pen.
Defined As
[VBA] Long TrendCursorLabelFillColor
[Cicode] INT TrendCursorLabelFillColor
[C++] OLE_COLOR TrendCursorLabelFillColor
Execution Result
Remarks
(65536 * Blue) + (256 * Green) + (Red). Where Red, Green and Blue are 0-255.
Calling Syntax
[VBA]
Dim color As Long
color = pen. TrendCursorLabelFillColor
pen. TrendCursorLabelFillColor = 255
End Sub
[Cicode]
INT color;
color = _ObjectGetProperty(hPen, TrendCursorLabelFillColor);
_ObjectSetProperty(hPen, TrendCursorLabelFillColor,
END
LineColor
[Property][Get/Set]
Gets or sets the border color used for any cursor label associated with this pen.
Defined As
[VBA] Long TrendCursorLabelLineColor
[Cicode] INT TrendCursorLabelLineColor
[C++] OLE_COLOR TrendCursorLabelLineColor
Execution Result
Remarks
Calling Syntax
[VBA]
Dim color As Long
color = pen. TrendCursorLabelLineColor
pen. TrendCursorLabelLineColor = 255
End Sub
[Cicode]
INT color;
color = _ObjectGetProperty(hPen, TrendCursorLabelLineColor);
_ObjectSetProperty(hPen, TrendCursorLabelLineColor,
END
TextColor
[Property][Get/Set]
Gets or sets the text color used for any cursor label associated with this pen.
Defined As
[VBA] Long TrendCursorLabelTextColor
[Cicode] INT TrendCursorLabelTextColor
[C++] OLE_COLOR TrendCursorLabelTextColor
Execution Result
Remarks
Calling Syntax
[VBA]
Dim color As Long
color = pen. TrendCursorLabelTextColor
pen. TrendCursorLabelTextColor = 255
End Sub
[Cicode]
INT color;
color = _ObjectGetProperty(hPen, TrendCursorLabelTextColor);
_ObjectSetProperty(hPen, TrendCursorLabelTextColor,
END
IPen.VerticalAxisAutosc
ale [Property][Get/Set]
Gets or sets whether the vertical axis will automatically calculate its physical
limits based on the sample values within its internal cache.
Defined As
[VBA] Boolean VerticalAxisAutoscale
[Cicode] INT VerticalAxisAutoscale
[C++] VARIANT_BOOL VerticalAxisAutoscale
Execution Result
Remarks
Setting this property will turn off interactive Scrolling
(IPen.HorizontalAxisScroll) and Scaling (IPen.HorizontalAxisResize).
Limits
True (-1): Autoscale enabled
False (0): Autoscale disabled
Calling Syntax
[VBA]
Dim autoScale As Long
autoScale = pen. VerticalAxisAutoscale
pen. VerticalAxisAutoscale = True
End Sub
[Cicode]
INT autoScale;
autoScale = _ObjectGetProperty(hPen, VerticalAxisAutoscale);
// Setting Property
_ObjectSetProperty(hPen, VerticalAxisAutoscale, -1);
END
IPen.VerticalAxisColor
[Property][Get/Set]
Gets or sets the color used to draw the line, labels and interval markers of the
vertical axis of this pen.
Defined As
[VBA] Long VerticalAxisColor
[Cicode] INT VerticalAxisColor
[C++] OLE_COLOR VerticalAxisColor
Execution Result
Remarks
See Also IPen.HorizontalAxisColor [Property][Get/Set]
Calling Syntax
[VBA]
Dim color As Long
color = pen.VerticalAxisColor
pen.VerticalAxisColor = 255
End Sub
[Cicode]
INT color;
color = _ObjectGetProperty(hPen, VerticalAxisColor);
_ObjectSetProperty(hPen, VerticalAxisColor, PackedRGB(255, 0,
0));
END
IPen.VerticalAxisLabelT
ype [Property][Get/Set]
Gets or sets a unit type which can be applied to the axis labels. This allows
numbers on the axis to display with their unit. For example, setting the unit to
kg will display 10 Kg on the axis.
Defined As
[VBA] Integer VerticalAxisLabelType
[Cicode] INT VerticalAxisLabelType
[C++] AxisLabelType VerticalAxisLabelType
Execution Result
Remarks
Label Types are fixed and cannot be added to.
See Also AxisLabelType [Enumeration]
Calling Syntax
[VBA]
Dim labelType As Integer
labelType = pen.VerticalAxisLabelType
Setting Property value to Percent
pen.VerticalAxisLabelType= 3
End Sub
[Cicode]
INT labelType;
labelType = _ObjectGetProperty(hPen, VerticalAxisLabelType);
// Setting Property to Percent
_ObjectSetProperty(hPen, VerticalAxisLabelType, 3);
END
IPen.VerticalAxisResize
[Property][Get/Set]
Gets or sets whether this pen allows the operator to interactively scale the
vertical axis by using the mouse.
Defined As
[VBA] Boolean VerticalAxisResize
[Cicode] INT VerticalAxisResize
[C++] VARIANT_BOOL VerticalAxisResize
Execution Result
Limits
True (-1): Enable resize
False (0): Disable resize
Remarks
This only applies to analog pens.
See Also IPen.HorizontalAxisResize [Property][Get/Set]
Calling Syntax
[VBA]
Dim resize As Boolean
resize = pen. VerticalAxisResize
pen. VerticalAxisResize = False
End Sub
[Cicode]
INT bResize;
bResize = _ObjectGetProperty(hPen, VerticalAxisResize);
// Setting Property
_ObjectSetProperty(hPen, VerticalAxisResize,0);
END
IPen.VerticalAxisScroll
[Property][Get/Set]
Gets or sets whether this pen allows the operator to interactively scroll the
vertical axis by using the mouse.
Defined As
[VBA] Boolean VerticalAxisScroll
[Cicode] INT VerticalAxisScroll
[C++] VARIANT_BOOL VerticalAxisScroll
Execution Result
Limits
True (-1): Enable scrolling
False (0): Disable scrolling
Remarks
See Also IPen.HorizontalAxisScroll [Property][Get/Set]
Calling Syntax
[VBA]
Dim scroll As Boolean
scroll = pen.VerticalAxisScroll
pen.VerticalAxisScroll = False
End Sub
[Cicode]
INT bScroll;
bScroll = _ObjectGetProperty(hPen, VerticalAxisScroll);
// Setting Property
_ObjectSetProperty(hPen, VerticalAxisScroll, 0);
END
IPen.VerticalAxisWidth
[Property][Get/Set]
Gets or sets the width of the vertical axis line and the associated interval
markers.
Defined As
[VBA] Integer VerticalAxisWidth
[Cicode] INT VerticalAxisWidth
[C++] short VerticalAxisWidth
Execution Result
Limits
Remarks
See Also IPen.HorizontalAxisWidth [Property][Get/Set]
Calling Syntax
[VBA]
width = pen.VerticalAxisWidth
pen.VerticalAxisWidth = 3
End Sub
[Cicode]
INT width;
width = _ObjectGetProperty(hPen, VerticalAxisWidth);
// Setting Property
_ObjectSetProperty(hPen, VerticalAxisWidth, 3);
END
IPen.VerticalGridlinesC
olor [Property][Get/Set]
Gets or sets the color used to draw the major vertical gridlines.
Defined As
[VBA] Long VerticalGridlinesColor
[Cicode] INT VerticalGridlinesColor
[C++] OLE_COLOR VerticalGridlinesColor
Execution Result
Remarks
See Also IPen.VerticalMinorGridlinesColor [Property][Get/Set]
Calling Syntax
[VBA]
Dim color As Long
color = pen.VerticalGridlinesColor
pen. VerticalGridlinesColor = 255
End Sub
[Cicode]
INT color;
color = _ObjectGetProperty(hPen, VerticalGridlinesColor);
_ObjectSetProperty(hPen, VerticalGridlinesColor,
END
IPen.VerticalGridlinesSt
yle [Property][Get/Set]
Gets or sets the line style used to draw the major vertical gridlines.
Defined As
[VBA] Long VerticalGridlinesColor
[Cicode] INT VerticalGridlinesColor
[C++] LineStyle VerticalGridlinesColor
Execution Result
See Also IPen.VerticalMinorGridlinesStyle [Property][Get/Set], LineStyle
[Enumeration]
Calling Syntax
[VBA]
Dim style As Long
style = pen.VerticalGridlinesColor
pen.VerticalGridlinesColor = 2
End Sub
[Cicode]
INT style;
style = _ObjectGetProperty(hPen, VerticalGridlinesStyle);
_ObjectSetProperty(hPen, VerticalGridlinesStyle, 2);
END
IPen.VerticalGridlinesWi
dth [Property][Get/Set]
Gets or sets the line width used when drawing the major vertical gridlines.
Defined As
[VBA] Integer VerticalGridlinesWidth
[Cicode] INT VerticalGridlinesWidth
[C++] short VerticalGridlinesWidth
Execution Result
Limits
Calling Syntax
[VBA]
width = pen.VerticalGridlinesWidth
pen.VerticalGridlinesWidth = 3
End Sub
[Cicode]
INT width;
width = _ObjectGetProperty(hPen, VerticalGridlinesWidth);
// Setting Property t
_ObjectSetProperty(hPen, VerticalGridlinesWidth, 3);
END
IPen.VerticalMinorGridli
nesColor
[Property][Get/Set]
Gets or sets the color used to draw the minor vertical gridlines.
Defined As
[VBA] Long VerticalMinorGridlinesColor
[Cicode] INT VerticalMinorGridlinesColor
[C++] OLE_COLOR VerticalMinorGridlinesColor
Execution Result
Remarks
See Also IPen.VerticalGridlinesColor [Property][Get/Set]
Calling Syntax
[VBA]
Dim color As Long
color = pen. VerticalMinorGridlinesColor
pen.VerticalMinorGridlinesColor = 255
End Sub
[Cicode]
INT color;
color = _ObjectGetProperty(hPen,
VerticalMinorGridlinesColor);
_ObjectSetProperty(hPen, VerticalMinorGridlinesColor,
END
IPen.VerticalMinorGridli
nesStyle [Property][Get/
Set]
Gets or sets the line style used to draw the minor vertical gridlines.
Defined As
[VBA] Long VerticalMinorGridlinesStyle
[Cicode] INT VerticalMinorGridlinesStyle
[C++] LineStyle VerticalMinorGridlinesStyle
Execution Result
See Also IPen.VerticalGridlinesStyle [Property][Get/Set], LineStyle
[Enumeration]
Calling Syntax
[VBA]
Dim style As Long
style = pen.VerticalMinorGridlinesStyle
pen.VerticalMinorGridlinesColor = 2
End Sub
[Cicode]
INT style;
style = _ObjectGetProperty(hPen,
VerticalMinorGridlinesStyle);
_ObjectSetProperty(hPen, VerticalMinorGridlinesStyle, 2);
END
IPen.Visible
[Property][Get/Set]
Get or set whether this pen will be visually shown (True) or hidden (False) to the
operator.
Defined As
Execution Result
Limits
True (-1): Visible
False (0): Hidden
Calling Syntax
[VBA]
Get the property value
visible = pen.Visible
Set the property value
pen.Visible = False
End Sub
[Cicode]
INT bVisible;
// Get the property value
bVisible = _ObjectGetProperty(hPen, Visible, 0.5);
// Set the property value
_ObjectSetProperty(hPen, Visible, 0);
END
IObjectView Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IObjectView
Methods (0)
Properties (7)
IObjectView.Visible [Property][Get/Set]
IObjectView.Height [Property][Get/Set]
IObjectView.BackgroundColor [Property][Get/Set]
IObjectView.ForeColor [Property][Get/Set]
IObjectView.Columns [Property][Get]
IObjectView.Items [Property][Get]
IObjectView.SelectedItem [Property][Get]
IObjectView.Visible
[Property][Get/Set]
Gets or Sets the visibility of the Object View window.
Defined As
Execution Result
Limits
True (-1): Visible
False (0): Hidden
Remarks
By hiding the ObjectView, the chart gains the real estate previously held by it,
and likewise the chart loses real estate when the ObjectView gets shown.
Calling Syntax
Assume that there is an IObjectView object being passed in as a parameter.
[VBA]
Sub Example(objectView As Object)
visible = objectView.Visible
objectView.Visible = False
End Sub
[Cicode]
FUNCTION Example(OBJECT hObjectView)
INT bVisible = 0
bVisible = _ObjectGetProperty(hObjectView, "Visible");
// Setting Property to false
_ObjectSetProperty(hObjectView, "Visible", 0);
END
IObjectView.Height
[Property][Get/Set]
Gets or Sets the height in pixels of the Object View window.
Defined As
[VBA] Long Height
[Cicode] INT Height
[C++] int Height
Execution Result
variable is bad, the return value will be InvalidArgument. A height value less
than 0 will be InvalidArgument.
Limits
Height must be 0 or greater.
Remarks
As the ObjectView and chart both share the same window, by enlarging the
ObjectView, you make the Chart smaller and vice versa.
Calling Syntax
This example assumes that there is an IObjectView object being passed in as a
parameter.
[VBA]
Dim height As Long
height = objectView.Height
objectView.Height = 25
End Sub
[Cicode]
INT nHeight = 0;
nHeight = _ObjectGetProperty(hObjectView, "Height");
// Setting Property to false
_ObjectSetProperty(hObjectView, "Height", 25);
END
IObjectView.Backgroun
dColor [Property][Get/
Set]
Gets or Sets the background color of the ObjectView. This number is treated as
an OLE_COLOR inside the Process Analyst.
Defined As
Execution Result
Remarks
Calling Syntax
parameter.
[VBA]
backgroundColor = objectView.BackgroundColor
Setting Property value to red
objectView.BackgroundColor = 255
End Sub
[Cicode]
INT nBackgroundColor =
_ObjectGetProperty(hObjectView,"BackgroundColor");
_ObjectSetProperty(hObjectView, "BackgroundColor", 255);
END
IObjectView.ForeColor
[Property][Get/Set]
Gets or Sets the Fore color (text and color box outlines) of the ObjectView. This
number is treated as an OLE_COLOR inside the Process Analyst.
Defined As
[VBA] Long ForeColor
[Cicode] INT ForeColor
[C++] OLE_COLOR ForeColor
Execution Result
Remarks
Calling Syntax
parameter.
[VBA]
Dim foreColor As Long
foreColor = objectView.ForeColor
objectView.ForeColor = 255
End Sub
[Cicode]
INT nForeColor = 0;
nForeColor = _ObjectGetProperty(hObjectView, "ForeColor");
// Setting Property to red
_ObjectSetProperty(hObjectView, "ForeColor", 255);
END
IObjectView.Columns
[Property][Get]
Gets the automation object representing the collection of columns currently
visible in the ObjectView.
Defined As
[VBA] Object Columns
[Cicode] OBJECT Columns
[C++] IObjectViewColumns* Columns
Execution Result
Calling Syntax
parameter.
[VBA]
Dim columns As Object
Set columns = objectView.Columns
End Sub
[Cicode]
OBJECT hColumns = _ObjectGetProperty(hObjectView, "Columns");
END
IObjectView.Items
[Property][Get]
Gets the automation object representing the collection of items at the root of the
ObjectView tree.
Defined As
[VBA] Object Items
[Cicode] OBJECT Items
[C++] IObjectViewItems* Items
Execution Result
Remarks
The method will provide a list of all the pane items in tree. Each pane item has
an Items property which allows access to the pen items listed under it.
Calling Syntax
parameter.
[VBA]
Dim items As Object
Set items = objectView.Items
End Sub
[Cicode]
OBJECT hItems = _ObjectGetProperty(hObjectView, "Items");
END
IObjectView.SelectedIte
m [Property][Get]
Gets the current primary selection in the ObjectView. This is the pen item that
was last selected.
Defined As
[VBA] Object SelectedItem
[Cicode] OBJECT SelectedItem
[C++] IObjectViewItem* SelectedItem
Execution Result
Calling Syntax
parameter.
[VBA]
Dim selectedItem As Object
Set selectedItem = objectView.SelectedItem
End Sub
[Cicode]
OBJECT hSelectedItem = _ObjectGetProperty(hObjectView,
"SelectedItem");
END
IObjectViewItems Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IObjectViewItems
Methods (0)
Properties (3)
IObjectViewItems.Count [Property][Get]
IObjectViewItems.Item [Property][Get]
IObjectViewItems._NewEnum [Property][Get]
IObjectViewItems.Count
[Property][Get]
Gets the number of child items under this item.
Defined As
[VBA] Long Count
[Cicode] INT Count
[C++] int Count
Execution Result
Calling Syntax
This example assumes there is a valid Items collection as retrieved from an
ObjectView. (e.g., VBA: objectView.Items)
[VBA]
Sub Example(Items As Object)
Dim count As Long
count = Items.Count
End Sub
[Cicode]
FUNCTION Example(OBJECT hItems)
INT nCount = _ObjectGetProperty(hItems, "Count");
END
IObjectViewItems.Item
[Property][Get]
Gets the ObjectViewItem at a supplied index location in this collection.
Defined As
[VBA] Item(index As Long) as Object
[Cicode] OBJECT Item(INT index)
[C++] Item(int index, IObjectViewItem* Item)
Parameters
index
[in] Indicates the index location of the child item to return from this
collection. (One based)
Calling Syntax
ObjectView. (e.g., VBA: objectView.Items).
[VBA]
Dim item As Object
Set item = Items.Item(1)
End Sub
[Cicode]
FUNCTION Example(OBJECT hItems)
OBJECT hItem = _ObjectCallMethod(hItems, "get_Item", 1);
END
IObjectViewItems._New
Enum [Property][Get]
This allows For.. Each.. Next integration in VB.
Calling Syntax
ObjectView. (e.g., VBA: objectView.Items). This property is not applicable to
Cicode.
[VBA]
Dim item As Object
Dim count Object
Using Property
For Each item In Items
count = count + 1
Next Item
End Sub
IObjectViewItem Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IObjectViewItem
Methods (2)
IObjectViewItem.GetField [Method]
IObjectViewItem.PutField [Method]
Properties (3)
IObjectViewItem.Expanded [Property][Get/Set]
IObjectViewItem.Tag [Property][Get/Set]
IObjectViewItem.Items [Property][Get]
IObjectViewItem.GetFiel
d [Method]
Returns the string value of a displayed field for a specified column on this item.
Defined As
[VBA] GetField(ColumnName As String) as String
[Cicode] STRING GetField (STRING ColumnName)
[C++] HRESULT GetField (BSTR ColumnName, BSTR *Val)
Parameters
ColumnName
[in] The string ID uniquely identifying the column whose field value is
being queried for.
Execution Result
variable is bad, the return value will be InvalidArgument. If the ColumnName
does not exist, InvalidArgument will be returned.
Calling Syntax
This example assumes there is a valid Item as retrieved from an Items Collection
from an ObjectView. (e.g., VBA: objectView.Items.Item(1))
[VBA]
Sub Example(Item As Object)
String fieldValue As String
fieldValue = Item.GetField(DataPoint)
End Sub
[Cicode]
FUNCTION Example(OBJECT hItem)
STRING sFieldValue = _ObjectCallMethod(hItem, "GetField",
DataPoint);
END
IObjectViewItem.PutFiel
d [Method]
Sets the display string in a fields cell for a specified column on this item.
Defined As
[VBA] PutField(columnName As String, fieldValue as String)
[Cicode] PutField (STRING columnName, STRING fieldValue)
[C++] HRESULT PutField (BSTR columnName, BSTR fieldValue)
Parameters
columnName
[in] The string ID uniquely identifying the column whose field value is
being set.
fieldValue
[in] The string you would like to be displayed in the field for this column/
pen intersection.
Execution Result
variable is bad, the return value will be InvalidArgument. If the field cannot be
set, then GeneralFailure is returned.
Calling Syntax
from an ObjectView. (e.g., VBA: objectView.Items.Item(1)).
[VBA]
Sub Example(Item As Object)
Item.PutField Custom1, Custom Data
End Sub
[Cicode]
FUNCTION Example(OBJECT hItem)
_ObjectCallMethod(hItem, "PutField", Custom1 , Custom
Data);
END
IObjectViewItem.Expan
ded [Property][Get/Set]
Gets or Sets the expanded state of an item in the ObjectView. This change is
reflected immediately in the visualization of the ObjectView.
Defined As
[VBA] Boolean Expanded
[Cicode] INT Expanded
[C++] VARIANT_BOOL Expanded
Execution Result
Limits
True (-1): Expanded
False (0): Collapsed
Calling Syntax
[VBA]
Sub Example(objectViewItem As Object)
Dim expanded As Boolean
expanded = objectViewItem.Expanded
objectViewItem.Expanded = False
End Sub
[Cicode]
FUNCTION Example(OBJECT hObjectViewItem)
INT nExpanded = _ObjectGetProperty(hObjectViewItem,
"Expanded");
// Setting Property
_ObjectSetProperty(hObjectViewItem, "Expanded", 0);
END
IObjectViewItem.Tag
[Property][Get/Set]
Gets or Sets a user specified piece of data to associate with this Item.
Defined As
[VBA] <Any Type> Tag
[Cicode] <Any Type> Tag
[C++] VARIANT Tag
Remarks
The user can associate any variant of data with a pen. This is handy for
associating some custom data with a pen item, and then having direct access to it
whenever any events with a pen item target occur.
Calling Syntax
[VBA]
Dim tag As Variant
tag = objectViewItem.Tag
objectViewItem.Tag = tag
End Sub
[Cicode]
INT nTag = _ObjectGetProperty(hObjectViewItem, "Tag");
// Setting Property to red
_ObjectSetProperty(hObjectView, "Tag", nTag);
END
IObjectViewItem.Items
[Property][Get]
Gets the automation object representing the collection of child items under this
item.
Defined As
[VBA] Object Items
[Cicode] OBJECT Items
[C++] IObjectViewItems* Items
Execution Result
Remarks
Pane nodes are currently the only nodes that can have children.
Calling Syntax
This example assumes there is a valid item as retrieved from an ObjectView.
(e.g., VBA: objectView.Items.Item(1). This will be a pane).
[VBA]
Dim items As Object
Set items = objectViewItem.Items
End Sub
[Cicode]
OBJECT hItems = _ObjectGetProperty(hObjectViewItem, "Items");
END
IObjectViewPenItem Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IObjectViewPenItem
Methods (0)
Properties (3)
IObjectViewPenItem.BlockColor [Property][Get])
IObjectViewPenItem.Checked [Property][Get/Set]
IObjectViewPenItem.Selected [Property][Get]
IObjectViewPenItem.Blo
ckColor [Property][Get]
Gets the color representing this item in the ObjectView.
Defined As
[VBA] Long BlockColor
[Cicode] INT BlockColor
[C++] OLE_COLOR BlockColor
Execution Result
Remarks
Blue) + (256 * Green) + (Red) where red, green, and blue are 0-255.
Calling Syntax
This example assumes there is a valid pen item as retrieved from an ObjectView.
(e.g., VBA: ObjectView.Items.Item(1).Items.Item(1) This will be a pen).
[VBA]
Sub Example(objectViewPenItem As Object)
Dim blockColor As Long
blockColor = objectViewPenItem.BlockColor
End Sub
[Cicode]
FUNCTION Example(OBJECT hObjectViewPenItem)
INT blockColor = _ObjectGetProperty(hObjectViewItem,
"BlockColor");
END
IObjectViewPenItem.Ch
ecked [Property][Get/
Set]
Gets or Sets whether or not this pen item is checked.
Defined As
[VBA] Boolean Checked
[Cicode] INT Checked
[C++] VARIANT_BOOL Checked
Execution Result
Limits
True (-1): Checked
False (0): Unchecked
Remarks
This reflects the pens visibility property directly, and any sets to this property
will reflect immediately in the update of the Process Analyst display.
See Also OVItemChecked [Event]
Calling Syntax
(e.g., VBA: objectView.Items.Item(1).Items.Item(1) This will be a pen).
[VBA]
Dim checked As Boolean
checked = objectViewPenItem.Checked
objectViewPenItem.Checked = False
End Sub
[Cicode]
INT checked = _ObjectGetProperty(hObjectViewItem, "Checked");
_ObjectSetProperty(hObjectViewItem, "Checked", 0);
END
IObjectViewPenItem.Sel
ected [Property][Get]
Gets whether or not this pen is the selected pen in its pane.
Defined As
[VBA] Boolean Selected
[Cicode] INT Selected
[C++] VARIANT_BOOL Selected
Execution Result
Limits
True (-1): Selected
False (0): Unselected
Remarks
Each Pane has one selected pen. It is visually emphasized by a vertical gradient
fill.
Calling Syntax
(e.g., VBA: objectView.Items.Item(1).Items.Item(1) This will be a pen).
[VBA]
Dim selected As Boolean
selected = objectViewPenItem.Selected
End Sub
[Cicode]
INT selected = _ObjectGetProperty(hObjectViewItem, "Selected");
END
IObjectViewColumns Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IObjectViewColumns
Methods (4)
IObjectViewColumns.Add [Method]
IObjectViewColumns.Hide [Method]
IObjectViewColumns.Remove [Method]
IObjectViewColumns.Show [Method]
Properties (4)
IObjectViewColumns.Count [Property][Get]
IObjectViewColumns.Item [Property][Get]
IObjectViewColumns.ItemByName [Property][Get]
IObjectViewColumns._NewEnum [Property][Get]
IObjectViewColumns.A
dd [Method]
Adds a visible custom column to the ObjectView.
Defined As
[VBA] Add(name As String, DisplayText As String, Width As Long)
[Cicode] Add(STRING name, STRING DisplayText, INT Width)
[C++] HRESULT Add (BSTR name, BSTR text, int width)
Parameters
name
[in] The string ID uniquely identifying this column (1-64).
text
[in] The title to be displayed in the column header (0-256).
width
[in] The width of this column in pixels (0-1000).
Execution Result
If the method succeeds, the return value will be Success. If an argument is out of
range, the return value will be InvalidArgument. If the column cannot be added,
the return value is GeneralFailure.
See Also OVColumnAdded [Event]
Calling Syntax
This example assumes there is a valid Columns collection as retrieved from an
ObjectView. (e.g., VBA: objectView.Columns).
[VBA]
Sub Example(Columns As Object)
Columns.Add "NameID", "New Column", 120;
End Sub
[Cicode]
FUNCTION Example(OBJECT hColumns)
_ObjectCallMethod(hColumns, "Add", "NameID", "New Column",
120);
END
IObjectViewColumns.Hi
de [Method]
Makes the specified column hidden within the Object View.
Defined As
[VBA] Hide(columnName As String)
[Cicode] Hide(STRING columnName)
[C++] HRESULT Hide(BSTR columnName)
Parameters
columnName
[in] The string ID uniquely identifying the column you want to hide
Execution Result
set, GeneralFailure is returned.
See Also IObjectViewColumns.Show [Method]
Calling Syntax
This example assumes there is a columns Collection from an ObjectView. (e.g.,
VBA: objectView.Columns).
[VBA]
Sub Example(columns As Object)
columns.Hide "Error"
End Sub
[Cicode]
_ObjectCallMethod(hColumns, "Hide", "Error");
END
IObjectViewColumns.Re
move [Method]
Removes the specified custom column from the Object View columns.
Defined As
[VBA] Remove(columnName As String)
[Cicode] OBJECT Remove(STRING columnName)
[C++] Remove(STRING columnName)
Parameters
columnName
[in] Indicates the unique name of the column to remove from this collection.
Execution Results
If the method succeeds, the return value will be Success. If the column cannot be
Remarks
Only user created custom columns can be removed.
Calling Syntax
This example assumes there is a valid Columns collection object to be passed
into the example methods.
[VBA]
Dim column As Object
Set column = columns.Remove(MyCustomColumn)
End Sub
[Cicode]
OBJECT hColumn = _ObjectCallMethod(hColumns, "get_ItemByName",
"MyCustomColumn");
END
IObjectViewColumns.Sh
ow [Method]
Makes the specified column visible within the Object View.
Defined As
[VBA] Show(columnName As String)
[Cicode] Show(STRING columnName)
[C++] HRESULT Show(BSTR columnName)
Parameters
columnName
[in] The string ID uniquely identifying the column you want to make
visible
Execution Result
set, then GeneralFailure is returned.
See Also IObjectViewColumns.Hide [Method]
Calling Syntax
This example assumes there is a columns Collection from an ObjectView. (e.g.,
VBA: objectView.Columns).
[VBA]
columns.Show "Error"
End Sub
[Cicode]
_ObjectCallMethod(hColumns, "Show", "Error");
END
IObjectViewColumns.C
ount [Property][Get]
Gets the number of Columns in this columns collection.
Defined As
[VBA] Long Count
[Cicode] INT Count
[C++] int Count
Execution Result
Calling Syntax
ObjectView. (e.g., VBA: ObjectView.Columns).
[VBA]
Function Example(Columns As Object)
Dim count As Long
count = Columns.Count
End Function
[Cicode]
INT nCount = _ObjectGetProperty(hColumns, "Count");
END
IObjectViewColumns.Ite
m [Property][Get]
Gets the ObjectViewItem at a supplied index location in this collection.
Defined As
[C++] Item(int index, IObjectViewColumn* Item)
Parameters
index
[in] Indicates the index location of the column to return from this
Calling Syntax
ObjectView (e.g., VBA: objectView.Columns).
[VBA]
Set column = Columns.Item(1)
End Sub
[Cicode]
OBJECT hColumn = _ObjectCallMethod(hColumns, "get_Item", 1);
END
IObjectViewColumns.Ite
mByName
[Property][Get]
Returns a reference to the column object with the given name from this columns
collection.
Defined As
[VBA] ItemByName(columnName As String) as Object
[Cicode] OBJECT ItemByName(STRING columnName)
[C++] ItemByName(STRING columnName, IObjectViewColumn* Item)
Parameters
columnName
[in] Indicates the unique name of the column item to return from this
collection.
Execution Results
If the method succeeds, the return value will be Success. If the column cannot be
Calling Syntax
This example assumes there is a valid Columns collection object to be passed
into the example methods.
[VBA]
Set column = columns.ItemByName(Duration)
End Sub
[Cicode]
OBJECT hColumn = _ObjectCallMethod(hColumns, "get_ItemByName",
"Duration");
END
IObjectViewColumns._N
ewEnum [Property][Get]
This allows For Each Next integration in VB.
Calling Syntax
ObjectView. (e.g., VBA: objectView.Columns). This property is not applicable in
Cicode.
[VBA]
Dim count Object
Using Property
For Each column In Columns
count = count + 1
Next column
End Sub
IObjectViewColumn Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IObjectViewColumn
Methods (0)
Properties (3)
IObjectViewColumn.Name [Property][Get]
IObjectViewColumn.Text [Property][Get]
IObjectViewColumn.Width [Property][Get/Set]
IObjectViewColumn.Na
me [Property][Get]
Retrieves the unique identifier of this column.
Defined As
[VBA] String Name
[C++] BSTR Name
Execution Result
Calling Syntax
This example assumes there is a valid column as retrieved from an ObjectView.
(e.g., VBA: objectView.Columns.Item(1)).
[VBA]
Sub Example(objectViewColumn As Object)
Dim name As String
name = objectViewColumn.Name
End Sub
[Cicode]
FUNCTION Example(OBJECT hObjectViewColumn)
STRING name = _ObjectGetProperty(hObjectViewColumn, "Name");
END
IObjectViewColumn.Tex
t [Property][Get]
Gets the Text that is being displayed for this columns header.
Defined As
[VBA] String Text
[Cicode] STRING Text
[C++] BSTR Text
Execution Result
Calling Syntax
[VBA]
Dim text As String
text = objectViewColumn.Text
End Sub
[Cicode]
STRING text = _ObjectGetProperty(hObjectViewColumn, "Text");
END
IObjectViewColumn.Wid
th [Property][Get/Set]
Gets or Sets the width in pixels of this column.
Defined As
[VBA] Long Width
[Cicode] INT Width
[C++] int Width
Execution Result
range, the result will be InvalidArgument.
Limits
A valid width is 0-1000.
Calling Syntax
[VBA]
Dim width As Long
width = objectViewColumn.Width
objectViewColumn.Width = 150
End Sub
[Cicode]
INT width = _ObjectGetProperty(hObjectViewColumn, "Width");
_ObjectSetProperty(hObjectViewColumn, "Width", 150);
END
ICommandSystem Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] ICommandSystem
Methods (3)
ICommandSystem.Create [Method]
ICommandSystem.Execute [Method]
ICommandSystem.Remove [Method]
Properties (4)
ICommandSystem.Count [Property][Get]
ICommandSystem.Item [Property][Get]
ICommandSystem._NewEnum [Property][Get]
ICommandSystem.ItemById [Property][Get]
ICommandSystem.Cou
nt [Property][Get]
Gets the number of commands in the command system.
Defined As
[VBA] Long Count
[Cicode] INT Count
[C++] int Count
Execution Result
If the property get succeeds, the return value will be Success.
Calling Syntax
This example assumes there is a valid CommandSystem object as retrieved from
a Process Analyst. (e.g., VBA: ProcessAnalyst.CommandSystem).
[VBA]
Function Example(CommandSystem As Object)
Dim count As Long
count = CommandSystem.Count
End Function
[Cicode]
FUNCTION Example(OBJECT hCommandSystem)
INT nCount = _ObjectGetProperty(hCommandSystem, "Count");
END
ICommandSystem.Item
[Property][Get]
Gets the Command at a supplied index location in this collection.
Defined As
[C++] Item(int index, ICommand* Item)
Parameters
index
[in] Indicates the index location of the command to return from this
Execution Result
If the property get succeeds, the return value will be Success. If the index is out
of range, the return value will be InvalidArgument.
Calling Syntax
[VBA]
Sub Example(CommandSystem As Object)
Dim command As Object
Set command = CommandSystem.Item(1)
End Sub
[Cicode]
OBJECT hCommand = _ObjectCallMethod(hCommandSystem, "get_Item",
1);
END
ICommandSystem._Ne
wEnum [Property][Get]
This allows For Each Next integration in VB.
Calling Syntax
a Process Analyst. (e.g., VBA: ProcessAnalyst.CommandSystem). This property
is not applicable to Cicode.
[VBA]
Dim count Object
Using Property
For Each command In CommandSystem
count = count + 1
Next command
End Sub
ICommandSystem.Item
ById [Property][Get]
Gets the Command at a supplied index location in this collection.
Defined As
[VBA] Object Command
[Cicode] OBJECT hCommand
[C++] ICommand* Command
Parameters
commandId
[in] Indicates command ID of the command to return from this collection.
Calling Syntax
[VBA]
Set command = CommandSystem.ItemById(Citect_Command_AddPen)
End Sub
[Cicode]
OBJECT hCommand = _ObjectCallMethod (hCommandSystem,"
get_ItemById",Citect_Command_AddPen);
END
ICommandSystem.Crea
te [Method]
Creates a new Command object that is added to the CommandSystem.
Defined As
[VBA] object Create (commandID As String, buttonType As Integer, tooltip
As String, iconPath As String, privilege As Integer)
[Cicode] OBJECT Create (STRING commandID, INT buttonType, STRING
tooltip, STRING iconPath, INT Pprivilege)
[C++] HRESULT Create (BSTR commandID, ToolbarButtonType
ButtonType, BSTR tooltip, BSTR iconPath, int privilege, ICommand** Val)
Parameters
commandID
[in] A unique identifier for this command (1-64 characters).
buttonType
[in] A value representing a button type.
ToolbarButtonType_Push = 0
ToolbarButtonType_Toggle = 1
ToolbarButtonType_Separator = 2
tooltip
[in] The text to be displayed as a tooltip for this command (1-64 characters).
iconPath
[in] The path to an icon file that will be used as this commands picture.
privilege
[in] A privilege value required by the Citect user to gain access to this
command (0-8).
Execution Result
If the method succeeds, the return value is Success. If an argument is invalid or
out of range, the return value is InvalidArgument. If the command was not
created, the return value is GeneralFailure.
Remarks
The commandID cannot begin with the prefix Citect_.
Calling Syntax
[VBA]
Set command = CommandSystem.Create(CommandIO, "Some tooltip
text", "c:\someicon.ico", 5)
End Sub
[Cicode]
OBJECT hCommand = _ObjectCallMethod(hCommandSystem, "Create",
CommandIO, "Some tooltip text", "c:\someicon.ico", 5);
END
ICommandSystem.Exec
ute [Method]
Executes the specified commands action.
Defined As
[VBA] Execute (commandId As String)
[Cicode] Execute (STRING commandId)
[C++] HRESULT Execute(BSTR commandId)
Parameters
commandId
[in] The unique ID of the command whose action is to be executed.
Execution Result
If this method succeeds, the retun value will be Success. If the command is
invalid, the return value will be InvalidArgument.
Remarks
If the current Operator does not have the correct privilege, the command will
not execute.
Calling Syntax
[VBA]
CommandSystem.Execute(Citect_Command_AddPen)
End Sub
[Cicode]
_ObjectCallMethod(hCommandSystem, "Execute",
Citect_Command_AddPen);
END
ICommandSystem.Rem
ove [Method]
Removes the specified command.
Defined As
[VBA] Remove (commandId As String)
[Cicode] Remove (STRING CommandId)
[C++] HRESULT Remove(BSTR CommandId)
Parameters
commandId
[in] The ID of the command to be removed.
Calling Syntax
[VBA]
CommandSystem.Remove(MyCommand1)
End Sub
[Cicode]
_ObjectCallMethod(hCommandSystem, "Remove", MyCommand1);
END
ICommand Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] ICommand
Methods (0)
Properties (6)
ICommand.CommandId [Property][Get]
ICommand.ButtonType [Property][Get]
ICommand.Enabled [Property][Get/Set]
ICommand.Pressed [Property][Get/Set]
ICommand.Tooltip [Property][Get]
ICommand.Privilege [Property][Get]
ICommand.CommandId
[Property][Get]
Gets the CommandId of this command.
Defined As
[VBA] String CommandId
[Cicode] STRING hCommandId
[C++] BSTR CommandId
Calling Syntax
This example assumes there is a valid Command object as retrieved from a
Process Analysts CommandSystem (e.g., VBA:
ProcessAnalyst.CommandSystem.Item(1)).
[VBA]
Sub Example(Command As Object)
Dim commandId As String
commandId = Command.CommandId
End Sub
[Cicode]
FUNCTION Example(OBJECT hCommand)
STRING nCommandId = _ObjectGetProperty(hCommand,"CommandID");
END
ICommand.ButtonType
[Property][Get]
Gets this commands button type.
Defined As
[VBA] Long ButtonType
[Cicode] INT ButtonType
[C++] ToolbarButtonType ButtonType
Execution Results
If the property get succeeds, the return value will be Success. If the return value
is invalid, the return value will be InvalidArgument. If the command has been
Remarks
The return value meaning is as follows:
ToolbarButtonType_Push = 0
ToolbarButtonType_Toggle = 1
ToolbarButtonType_Separator = 2
Calling Syntax
Process Analysts CommandSystem. (e.g., VBA:
ProcessAnalyst.CommandSystem.Item(1))
[VBA]
Dim buttonType As Long
buttonType = Command.ButtonType
End Sub
[Cicode]
INT nButtonType = _ObjectGetProperty(hCommand, "ButtonType");
END
ICommand.Enabled
[Property][Get/Set]
Gets this commands enabled state.
Defined As
[VBA] Boolean Enabled
[Cicode] INT Enabled
[C++] VARIANT_BOOL Enabled
Execution Result
If the property get succeeds, the return value will be Success. If the return value
is invalid, the return value will be InvalidArgument.
Limits
True (-1): Enabled
Falso (0): Disabled
Remarks
The setting of this property is only valid for custom commands.
Calling Syntax
[VBA]
Dim enabled As Boolean
enabled = Command.Enabled
Command.Enabled = True
End Sub
[Cicode]
INT nEnabled = _ObjectGetProperty(hCommand, "Enabled");
_ObjectSetProperty(hCommand, "Enabled", -1);
END
ICommand.Pressed
[Property][Get/Set]
Gets and Sets this commands Pressed state.
Defined As
[VBA] Boolean Pressed
[Cicode] INT Pressed
[C++] VARIANT_BOOL Pressed
Execution Result
Limits
True (-1): Pressed
False (0): UnPressed
Remarks
This is only useful for toggle buttons, indicating whether or not the button is in a
pressed down state. The setting of this property is only valid for custom
commands.
Calling Syntax
[VBA]
Dim pressed As Boolean
pressed = Command.Pressed
Command.Pressed = True
End Sub
[Cicode]
INT nPressed = _ObjectGetProperty(hCommand, "Pressed");
_ObjectSetProperty(hCommand, "Pressed", -1);
END
ICommand.Tooltip
[Property][Get]
Gets this commands Tooltip text.
Defined As
[VBA] String Tooltip
[Cicode] STRING Tooltip
[C++] VARIANT_BOOL Tooltip
Execution Result
variable is invalid, the return value will be InvalidArgument. If the command
has been deleted, the return value will be GeneralFailure.
Remarks
This returns the text that is displayed in a tooltip window when the mouse
pointer hovers over the commands button.
Calling Syntax
[VBA]
Dim tooltip As String
tooltip = Command.Tooltip
End Sub
[Cicode]
STRING sTooltip = _ObjectGetProperty(hCommand, "Tooltip");
END
ICommand.Privilege
[Property][Get]
Gets the privilege required to gain access to this command.
Defined As
[VBA] Integer Privilege
[Cicode] INT Privilege
[C++] int Privilege
Execution Result
variable is invalid, the return value will be InvalidArgument. If the command
has been deleted, the return value will be GeneralFailure.
Remarks
This is the required privilege level of the currently logged in Citect user to
enable the state of this command, and hence allow access through the user
interface. If the currently logged in Citect user doesnt have this privilege, any
buttons tied to this command will be disabled.
Calling Syntax
[VBA]
Dim privilege As Integer
privilege = Command.Privilege
End Sub
[Cicode]
INT nPrivilege = _ObjectGetProperty(hCommand, "Privilege");
END
IToolbars Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IToolbar
Methods (0)
Properties (3)
IToolbars.Count [Property][Get]
IToolbars.Item [Property][Get]
IToolbars._NewEnum [Property][Get]
IToolbars.Count
[Property][Get]
Gets the number of Toolbars in this collection.
Defined As
[VBA] Long Count
[Cicode] INT Count
[C++] int Count
Execution Result
Calling Syntax
This example assumes there is a valid Toolbars collection as retrieved from an
ObjectView. (e.g., VBA: objectView.Toolbars).
[VBA]
Sub Example(Toolbars As Object)
Dim count As Long
count = Toolbars.Count
End Sub
[Cicode]
FUNCTION Example(OBJECT hToolbars)
INT nCount= _ObjectGetProperty(hToolbars, "Count");
END
IToolbars.Item
[Property][Get]
Gets the Toolbar at a supplied index location in this collection.
Defined As
[C++] Item(int index, IToolbar* Item)
Parameters
index
[in] Indicates the index location of the child item to return from this
collection. (One based) 1 = Main toolbar; 2 = Navigation toolbar.
Execution Result
of range, the return value will be InvalidArgument.
Calling Syntax
ObjectView. (e.g., VBA: objectView.Toolbars)
[VBA]
Dim toolbar As Object
Set toolbar = Toolbars.Item(1)
End Sub
[Cicode]
FUNCTION Example(OBJECT hToolbars)
OBJECT hToolbar = _ObjectCallMethod(hToolbars, "get_Item", 1);
END
IToolbars._NewEnum
[Property][Get]
Calling Syntax
ObjectView (e.g., VBA: objectView.Toolbars). This property is not applicable to
Cicode.
[VBA]
Dim count Object
Using Property
For Each toolbar In Toolbars
count = count + 1
Next toolbar
End Sub
IToolbar Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IToolbar
Methods (0)
Properties (2)
IToolbar.Visible [Property][Get/Set]
IToolbar.Buttons [Property][Get]
IToolbar.Visible
[Property][Get/Set]
Gets and Sets this Toolbars Visible state.
Defined As
Execution Result
Limits
True (-1): Visible
False (0): Invisible
Remarks
If the toolbar is not visible, all buttons tied to it will not appear. Only the main
toolbar can be hidden. Setting the new toolbar to invisible will result in a
GeneralFailure.
Calling Syntax
This example assumes there is a valid Toolbar object as retrieved from a Process
Analysts Toolbars collection. (e.g., VBA: ProcessAnalyst.Toolbars.Item(1))
[VBA]
Sub Example(Toolbar As Object)
visible = Command.Visible
Command.Visible = False
End Sub
[Cicode]
FUNCTION Example(OBJECT hToolbar)
INT nVisible = _ObjectGetProperty(hToolbar, "Visible");
_ObjectSetProperty(hToolbar, "Visible", 0);
END
IToolbar.Buttons
[Property][Get]
Gets this Toolbars collection of Buttons.
Defined As
[VBA] Object Buttons
[Cicode] OBJECT Buttons
[C++] IToolbarButtons* Buttons
Execution Result
Calling Syntax
This example assumes there is a valid Toolbar object as retrieved from a Process
Analysts Toolbars collection. (e.g., VBA: ProcessAnalyst.Toolbars.Item(1))
[VBA]
Sub Example(Toolbar As Object)
Dim buttons As Object
Set buttons = Command.Buttons
End Sub
[Cicode]
FUNCTION Example(OBJECT hToolbar)
OBJECT hButtons = _ObjectGetProperty(hToolbar, "Buttons");
END
IToolbarButtons Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IToolbar
Methods (3)
IToolbarButtons.Add [Method]
IToolbarButtons.Remove [Method]
IToolbarButtons.RemoveAll [Method]
Properties (3)
IToolbarButtons.Count [Property][Get]
IToolbarButtons.Item [Property][Get]
IToolbarButtons._NewEnum [Property][Get]
IToolbarButtons.Add
[Method]
Adds a toolbar button linked to the command identified by the supplied
Command Id to this Toolbar.
Defined As
[VBA] Add(CommandId as String)
[Cicode] Add (STRING CommandId)
[C++] HRESULT Add (BSTR CommandId)
Parameters
CommandId
[in] The Command ID of a command to link to the new button that is being
added.
Execution Result
If this method succeeds, the return value will be Success. If the command ID is
invalid, the return value will be InvalidArgument.
Remarks
If this method succeeds, the ID supplied will be linked to the new button that is
added. The Commands properties will be applied to that button. (its icon,
tooltip, security) If this button is pressed, the CommandExecuted event will
raise with this Command ID.
See Also CommandExecuted [Event]
Calling Syntax
This example assumes there is a valid ToolbarButtons collection as retrieved
from an ObjectView (e.g., VBA: objectView.Toolbars.Item(1).Buttons).
[VBA]
Sub Example(Buttons As Object)
Buttons.Add(Citect_Command_Help)
End Sub
[Cicode]
FUNCTION Example(OBJECT hButtons)
_ObjectCallMethod(hButtons, Add, Citect_Command_Help);
END
IToolbarButtons.Remov
e [Method]
Removes a button from this toolbar at the supplied index.
Defined As
[VBA] Remove(Index as Integer)
[Cicode] Remove (INT Index)
[C++] HRESULT Remove (int Index)
Parameters
Index
[in] The index of the button to remove from this toolbar. (1 Based)
Execution Results
If the method succeeds, the return value will be Success. If the index is out of
range, the return value will be InvalidRange. If the method fails, the return value
Calling Syntax
from an ObjectView. (e.g., VBA: objectView.Toolbars.Item(1).Buttons).
[VBA]
Buttons.Remove(1)
End Sub
[Cicode]
_ObjectCallMethod(hButtons, Remove, 1);
END
IToolbarButtons.Remov
eAll [Method]
Removes all buttons from this Toolbar.
Defined As
[VBA] RemoveAll()
Execution Results
If this method succeeds, the return value will be Success. If this method fails, the
Calling Syntax
from an ObjectView. (e.g., VBA: objectView.Toolbars.Item(1).Buttons)
[VBA]
Buttons.RemoveAll()
End Sub
[Cicode]
_ObjectCallMethod(hButtons, RemoveAll);
END
IToolbarButtons.Count
[Property][Get]
Gets the number of Buttons in this collection.
Defined As
[VBA] Long Count
[Cicode] INT Count
[C++] int Count
Calling Syntax
from an ObjectView. (e.g., VBA: objectView.Toolbars.Item(1).Buttons).
[VBA]
Dim count As Long
count = Buttons.Count
End Sub
[Cicode]
INT nCount = _ObjectGetProperty(hButtons, "Count");
END
IToolbarButtons.Item
[Property][Get]
Gets the button at a supplied index location in this collection.
Defined As
[C++] Item(int index, IToolbarButton* Item)
Parameters
index
[in] Indicates the index location of the button to return from this collection.
(One based)
Execution Results
If the property get succeeds, the return value will be success. If the index is out
of range, the return value will be InvalidArgument. If the method fails, the
Calling Syntax
[VBA]
Set toolbar = Buttons.Item(1)
End Sub
[Cicode]
OBJECT hToolbar = _ObjectCallMethod(hButtons, "get_Item", 1);
END
IToolbarButtons._NewE
num [Property][Get]
Calling Syntax
from an ObjectView (e.g., VBA: objectView.Toolbars.Item(1).Buttons). This
property is not applicable to Cicode.
[VBA]
Dim button As Object
Dim count Object
Using Property
For Each button In Buttons
count = count + 1
Next button
End Sub
IToolbarButton Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IToolbar
Methods (0)
Properties (1)
IToolbarButton.CommandId [Property][Get]
IToolbarButton.Comma
ndId [Property][Get]
Gets the ID of the associated command for this button.
Defined As
[VBA] String CommandId
[Cicode] STRING CommandId
[C++] BSTR CommandId
Calling Syntax
[VBA]
Dim commandId As String
commandId = Buttons.CommandId
End Sub
[Cicode]
STRING nCommandId = _ObjectGetProperty(hButtons, "CommandId");
END
IPanes Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IPanes
Methods (2)
IPanes.Create [Method]
IPanes.RemoveAll [Method]
Properties (4)
IPanes.Count [Property][Get]
IPanes.Item [Property][Get]
IPanes._NewEnum [Property][Get]
IPanes.ItemByName [Property][Get]
IPanes.Create [Method]
Adds a pane to this collection and returns a reference to it.
Defined As
[VBA] Create(name as String) as Object
[Cicode] OBJECT Create (STRING name)
[C++] HRESULT Create(BSTR name, IPane** pane)
Parameters
name
[in] The name to give to the pane (0-250 characters).
Execution Result
If the method succeeds, the return value will be Success. If a pane of the same
name exists, the return value will be InvalidArgument. If the panes collection is
Remarks
When this method succeeds it will return a reference to the new IPane object.
See Also IPanes Interface
Calling Syntax
This example assumes there is a valid Panes collection object to be passed into
[VBA]
Sub Example(Panes As Object)
Dim pane As Object
Set pane = Panes.Create(Alarm Pane)
End Sub
[Cicode]
FUNCTION Example(OBJECT hPanes)
OBJECT hPane = _ObjectCallMethod(hPanes, Create, Alarm
Pane);
END
IPanes.RemoveAll
[Method]
Removes all Panes from this Pane collection.
Defined As
[VBA] RemoveAll()
Execution Result
If the method succeeds, the return value will be Success. If the panes collection is
Calling Syntax
[VBA]
Sub Panes(Buttons As Object)
Panes.RemoveAll()
End Sub
[Cicode]
_ObjectCallMethod(hPanes, RemoveAll);
END
IPanes.Count
[Property][Get]
Gets the number of Panes in this collection.
Defined As
[VBA] Long Count
[Cicode] INT Count
[C++] int Count
Execution Result
If the property get succeeds, the return value will be Success. If the panes
Calling Syntax
[VBA]
Dim count As Long
count = Panes.Count
End Sub
[Cicode]
INT nCount = _ObjectGetProperty(hPanes, "Count");
END
IPanes.Item
[Property][Get]
Gets the Pane at the given index in this Pane collection.
Defined As
[C++] Item(int index, IPane* Item)
Parameters
index
[in] Indicates the location of the Pane item to return from this collection.
(One based)
Execution Result
If the property get succeeds the return value will be Success. If the index is out of
range then the return value will be InvalidArgument. If the panes collection is
See Also IPane Interface
Calling Syntax
[VBA]
Dim pane As Object
Set pane = Panes.Item(1)
End Sub
[Cicode]
OBJECT hPane = _ObjectCallMethod(hPanes, "get_Item", 1);
END
IPanes._NewEnum
[Property][Get]
Calling Syntax
the example methods. This property is not applicable to Cicode.
[VBA]
Dim pane As Object
Dim count As Long
Using Property
For Each pane In Panes
count = count + 1
Next pane
End Sub
IPanes.ItemByName
[Property][Get]
Returns a reference to the pane object with the given name from this Panes
collection.
Defined As
[VBA] ByName(name As String) as Object
[Cicode] OBJECT ByName(STRING name)
[C++] ByName(STRING name, IPane* Item)
Parameters
name
[in] Indicates the name of the Pane item to return from this collection.
Execution Result
If the property get succeeds, the return value will be Success. If the pane cannot
be found, the return value will be InvalidArgument. If the panes collection is
Calling Syntax
[VBA]
Dim pane As Object
Set pane = Panes.ItemByName(Alarm Pane)
End Sub
[Cicode]
OBJECT hPane = _ObjectCallMethod(hPanes, "get_ItemByName",
"Alarm Pane");
END
IPane Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IPanes
Methods (1)
IPane.Delete [Method]
Properties (6)
IPane.Height [Property][Get/Set]
IPane.Collection [Property][Get]
IPane.Name [Property][Get/Set]
IPane.BackgroundColor [Property][Get/Set]
IPane.FixedHeight [Property][Get/Set]
IPane.Pens [Property][Get]
IPane.Delete [Method]
Removes this Pane from the collection and the display.
Defined As
[VBA] Delete()
[Cicode] Delete()
Execution Result
If the method succeeds, the return value will be Success. If the pane is already
Remarks
Any pen associated with the pane will also be deleted.
Calling Syntax
This example assumes there is a valid Pane object to be passed into the example
methods.
[VBA]
Sub Panes(Pane As Object)
Pane.Delete()
End Sub
[Cicode]
FUNCTION Example(OBJECT hPane)
_ObjectCallMethod(hPane, Delete);
END
IPane.Height
[Property][Get/Set]
Gets or Sets the height of this pane.
Defined As
[VBA] Long Height
[Cicode] INT Height
[C++] int Height
Execution Result
If the property get/set succeeds, the return value will be Success. If the height is
out of range (16-1000), the return value will be InvalidArgument. If the pane is
Remarks
This property affects the visible height of the Pane in two different ways based
on the Boolean value of the FixedHeight property. If the FixedHeight property is
True, the Pane takes on a pixel height equivalent to the Height property value.
All pens inside the Pane are adjusted to fit. If the FixedHeight property is False,
the Height property value is used as a ratio of the available Variable real estate
(all the left over room in the Process Analyst after Fixed Height panes have been
added) which is shared out between all the Variable Height panes.
See Also IPane.FixedHeight [Property][Get/Set]
Calling Syntax
methods.
[VBA]
Sub Example(Pane As Object)
Dim height As Long
height = Pane.Height
Pane.Height = 250
End Sub
[Cicode]
INT nHeight = _ObjectGetProperty(hPane, "Height");
_ObjectSetProperty(hPane, "Height", 250);
END
IPane.Collection
[Property][Get]
Returns a reference to the Panes collection that this Pane belongs to.
Defined As
[C++] IPanes* Collection
Execution Result
If the property get succeeds the return value will be Success. If the pane is
See Also IPanes Interface
Calling Syntax
methods.
[VBA]
Sub Example(pane As Object)
Dim panes As Object
Set panes = pane.Collection
End Sub
[Cicode]
OBJECT hPanes = _ObjectGetProperty(hPane, "Collection");
END
IPane.Name
[Property][Get/Set]
Gets or Sets the name of this pane.
Defined As
[VBA] String Name
[C++] BSTR Name
Execution Result
If the property get/set succeeds, the return value will be Success. If a pane of the
same name exists, the return value will be InvalidArgument. If the panes
Limits
Name must be between 1-250 characters.
Remarks
Pane names must be unique.
Calling Syntax
methods.
[VBA]
Dim name As String
name = pane.Name
pane.Name = "Alarms"
End Sub
[Cicode]
STRING sName = _ObjectGetProperty(hPane, "Name");
_ObjectSetProperty(hPane, "Name", "Alarms");
END
IPane.BackgroundColor
[Property][Get/Set]
Gets or Sets the color of this Pane.
Defined As
Execution Result
If the property get/set succeeds, the return value will be Success. If the pane is
Remarks
Calling Syntax
methods.
[VBA]
Sub Example(Pane As Object)
backgroundColor = Pane.BackgroundColor
Pane.BackgroundColor = 255
End Sub
[Cicode]
INT nColor = _ObjectGetProperty(hPane, "BackgroundColor");
_ObjectSetProperty(hPane, "Name", 255);
END
IPane.FixedHeight
[Property][Get/Set]
Gets or Sets whether this pane has a fixed height.
Defined As
[VBA] Boolean FixedHeight
[Cicode] INT FixedHeight
[C++] VARIANT_BOOL FixedHeight
Execution Result
If the property get/set succeeds, the return value will be Success. If the pane is
Limits
True (-1): Height is fixed
False (0): Height is variable
Remarks
When this property is true, the panes Height reflects the pixel value size as
gotten from the Panes Height property. If the FixedHeight property is false, the
Height property value is used as a ratio of the available Variable real estate (all
the left over room in the Process Analyst after Fixed Height panes have been
added) which is shared out between all the Variable Height panes.
See Also IPane.Height [Property][Get/Set]
Calling Syntax
methods.
[VBA]
Dim fixedHeight As Boolean
fixedHeight = pane.FixedHeight
pane.FixedHeight = True
End Sub
[Cicode]
INT bFixedHeight = _ObjectGetProperty(hPane, "FixedHeight");
_ObjectSetProperty(hPane, "FixedHeight", -1);
END
IPane.Pens
[Property][Get]
Gets a reference to the pens collection object containing the pens for this pane.
Defined As
[VBA] Object Pens
[Cicode] OBJECT Pens
[C++] IPens* Pens
Execution Result
If the property get succeeds the return value will be Success. If the pane is
See Also IPens Interface
Calling Syntax
methods.
[VBA]
Dim pens As Object
Set pens = pane.Pens
End Sub
[Cicode]
OBJECT hPens = _ObjectGetProperty(hPane, "Pens");
END
IPens Interface
Defined As
[VBA] Object
[Cicode] OBJECT
[C++] IPens
Methods (2)
IPens.Create [Method]
IPens.RemoveAll [Method]
Properties (5)
IPens.Count [Property][Get]
IPens.Item [Property][Get]
IPens._NewEnum [Property][Get]
IPens.ItemByName [Property][Get]
IPens.Pane[Property][Get]
IPens.Create [Method]
Creates a new pen and adds it to this collection.
Defined As
[VBA] Create(penType As Integer, nameMode As Integer) as Object
[Cicode] OBJECT Create (INT penType, INT nameMode)
[C++] HRESULT Create(PenType penType, PenNameMode penNameMode,
IPen** pen)
Parameters
penType
[in] Indicates the type of pen that will be created. See PenType
Enumeration for the types of pen that can be created.
penNameMode
[in] Indicates how the name will be obtained for this pen. The Process
Analyst provides options of PenNameMode_Comment,
PenNameMode_Tag, and PenNameMode_Custom. Specifying
PenNameMode_Comment will mean that the Process Analyst names the
pen from the Comment field of the trend/alarm tag associated with the
IPen.DataPoint property. Specifying PenNameMode_Tag will mean that the
Process Analyst will name the pen as the value of the IPen.DataPoint
property. Specifying PenNameMode_Custom causes the Process Analyst to
provide a default name and leave setting the name to you via the IPen.Name
property.
Execution Results
If the method succeeds the return value will be Success. If the pens collection is
Remarks
If this method succeeds, a new Pen of the specified type is created and appended
to the pens collection.
See Also IPen Interface, PenType [Enumeration], PenNameMode [Enumeration]
Calling Syntax
This example assumes there is a valid Pens collection object to be passed in to the
example methods.
[VBA]
Sub Example(pens As Object)
Dim pen As Object
Set pen = pens.Create(4097, 1)
End Sub
[Cicode]
FUNCTION Example(OBJECT hPens)
OBJECT hPen = _ObjectCallMethod(hPens, Create , 4097, 1);
END
IPens.RemoveAll
[Method]
Removes all Pens from the Pens collection.
Defined As
[VBA] RemoveAll()
Execution Result
If the property get/set succeeds the return value will be Success. If the pens
collection is deleted the return value will be GeneralFailure.
Calling Syntax
This example assumes there is a valid Pens collection object to be passed into the
example methods.
[VBA]
Sub Panes(pens As Object)
pens.RemoveAll()
End Sub
[Cicode]
_ObjectCallMethod(hPens, RemoveAll);
END
IPens.Count
[Property][Get]
Gets the number of Pens in this collection.
Defined As
[VBA] Long Count
[Cicode] INT Count
[C++] int Count
Execution Result
If the property get succeeds, the return value will be Success. If the pens
Calling Syntax
example methods.
[VBA]
Sub Example(Pens As Object)
Dim count As Long
count = Pens.Count
End Sub
[Cicode]
INT nCount = _ObjectGetProperty(hPens, "Count");
END
IPens.Item
[Property][Get]
Gets the Pen at the given index from this pens collection.
Defined As
[C++] Item(int index, IPen* Item)
Parameters
index
[in] Indicates the index of the pen item to return from this collection. (One
based)
Execution Result
of range, the return value will be InvalidArgument. If the pens collection is
Calling Syntax
example methods.
[VBA]
Dim pen As Object
Set pen = pens.Item(1)
End Sub
[Cicode]
OBJECT hPen = _ObjectCallMethod(hPens, "get_Item", 1);
END
IPens._NewEnum
[Property][Get]
Calling Syntax
example methods. This property is not applicable to Cicode.
[VBA]
Dim pen As Object
Dim count As Long
Using Property
For Each pen In Pens
count = count + 1
Next pen
End Sub
IPens.ItemByName
[Property][Get]
Gets the Pen of the given name from this Pens collection.
Defined As
[VBA] ItemByName(name As String) as Object
[Cicode] OBJECT ItemByName(STRING name)
[C++] ItemByName(STRING name, IPen* Item)
Parameters
name
[in] Indicates the name of the Pen item to return from this collection.
Execution Result
If the property get succeeds, the return value will be Success. If the pen does not
exist, the return value will be InvalidArgument. If the pens collection is deleted,
Calling Syntax
example methods.
[VBA]
Dim pen As Object
Set pen = Pens.ItemByName(CPU Usage)
End Sub
[Cicode]
OBJECT hPen = _ObjectCallMethod(hPens, "get_ItemByName", "CPU
Usage");
END
IPens.Pane[Property][G
et]
Gets the Pane that this Pens collection belongs to.
Defined As
[VBA] Object Pane
[Cicode] OBJECT Pane
[C++] HRESULT Pane(IPane** Pane)
Execution Result
If the property get succeeds the return value will be Success. If the pens
collection is deleted the return value will be GeneralFailure.
Remarks
Each Pens collection belongs to a Pane.
Calling Syntax
example methods.
[VBA]
Dim pane As Object
Set pane = pens.Pane
End Sub
[Cicode]
OBJECT hPane = _ObjectGetProperty(hPens, "Pane");
END
Chapter 14: Cicode Programming Reference
Automation Examples
The best way of understanding how to use the Process Analysts automation
model is to see some example code. The following examples cover the most
important concepts of extensibility offered by the Process Analyst:
Event handling
Enumerating collections
Custom commands
Custom columns
All of the samples assume you are using the CSV example project and have
pasted a new Process Analyst onto the test page provided by the project.
You will also need to configure the Process Analyst objects Name and Event
class by doing the following:
1 In the CSV example project open the test page in Graphics Builder
2 Click the Process Analyst icon in the toolbox to insert the control.
3 Resize the control to fit the test page.
4 Double-click the Process Analyst.
5 Click the Access/Identification tab.
6 Change the Object Name to CPA.
7 Change the Event class to CPA_E.
8 Click Apply and OK.
Handling an Event
The Process Analyst contains many events that are triggered when certain
actions occur. See Events.
To handle an event you must provide a handler for the event by prepending
your Process Analysts event class name with the event name you want to handle
and an underscore. To configure the event class, see Automation Examples.
The example below shows how to define a handler for the MouseClick event
with an event class defined as CPA_E.
[VBA]
Sub CPA_E_MouseClick(pen As Object, button As Integer)
End Sub
Chapter 14: Cicode Programming Reference 302
[Cicode]
FUNCTION CPA_E_MouseClick(OBJECT hPA, OBJECT hPen, INT button)
END
The following example uses the MouseClick event to cancel the box zoom
operation when the right mouse button is clicked.
Note: When referring to an ActiveX object in VBA, you need to prepend it with
the page name and an underscore. In the example below, the page name is called
test. The object name is CPA and the event class name is CPA_E.
[VBA]
Sub CPA_MouseClick(pen As Object, button As Integer)
Dim bZoomMode As Boolean
If (button = 1) Then
bZoomMode = test_CPA.ZoomMode
If (bZoomMode = True) Then
test_CPA.ZoomMode = False
End If
End If
End Sub
[Cicode]
FUNCTION CPA_E_MouseClick(OBJECT hPA, OBJECT hPen, INT button)
INT bZoomMode = 0;
IF (button = 1) THEN
bZoomMode = _ObjectGetProperty(hPA, "ZoomMode")
IF (bZoomMode = -1) THEN
_ObjectSetProperty(hPA, "ZoomMode", 0)
END
END
END
Enumerating
collections
The Process Analyst contains many collections such as Panes, Pens, Cursors,
Commands, and so on. This example shows you how to enumerate through the
buttons on the navigation toolbar.
[VBA]
Sub EnumerateToolbarButtons()
Dim navBar As Object
Dim iButton As Integer
Dim button As Object
Dim nButtons As Integer
The Navigation toolbar is the 2nd toolbar in the collection
Set navBar = test_CPA.Toolbars.Item(2)
If IsNull(navBar) = False Then
nButtons = navBar.Buttons.Count
For iButton = 1 To nButtons
Set button = navBar.Buttons(iButton)
Next iButton
End If
End Sub
[Cicode]
FUNCTION EnumerateToolbarButtons()
OBJECT hPA = ObjectByName("CPA");
OBJECT hToolbars = _ObjectGetProperty(hPA, "Toolbars");
// The Navigation toolbar is the 2nd toolbar in the collection
OBJECT hNavBar = _ObjectCallMethod(hToolbars, "get_Item", 2);
OBJECT hButtons;
OBJECT hButton;
INT nButtons;
INT iButton;
IF (ObjectIsValid(hNavBar)) THEN
hButtons = _ObjectGetProperty(hNavBar, "Buttons");
nButtons = _ObjectGetProperty(hButtons, "Count");
FOR iButton = 1 TO nButtons DO
hButton = _ObjectCallMethod(hButtons, "get_Item",
iButton);
END
END
END
Note: Many collections have an ItemById property that allows you to get the
item you want without having to enumerate through the collection to find the
item you want.
Implementing a custom
command
Custom commands are easy to implement and involve creating a new
command, adding it to a toolbar, and responding to the CommandExecuted
event.
To add a new command and add it to the toolbar as a button:
1 Display the properties for your Process Analyst in the Graphics Builder
2 See Adding New Commands.
3 Use the following settings:
ID =SelectedPen
Tooltip = Show the name of the selected pen
Button style = <Push>
Enabled = <Checked>
Once youve done this, you need to write an event handler for the
CommandExecuted event. This event will be called when the command is
executed, whether by Cicode or by clicking on the respective toolbar button.
The CommandExecuted event when triggered has a commandId parameter
identifying the command executed by the operator.
This example implements a command that displays a message box showing the
name of the primary selected pen.
See Also CommandExecuted [Event]
[VBA]
Sub CPA_E_CommandExecuted(commandId As String)
Select Case commandId
Case "SelectedPen"
Call OnSelectedPen()
End Select
End Sub
Sub OnSelectedPen()
Dim pen As Object
Dim sName As String
Dim sMessage As String
Set pen = test_CPA.LastSelectedPen
If IsNull(pen) = False Then
sName = pen.Name
End If
sMessage = "The name of the selected pen is:" + Chr(13) + sName
MsgBox sMessage, 48, "Citect"
End Sub
[Cicode]
FUNCTION CPA_E_CommandExecuted(OBJECT hPA, STRING commandId)
SELECT CASE commandId
CASE "SelectedPen"
OnSelectedPen(hPA);
END SELECT
END
FUNCTION OnSelectedPen(OBJECT hPA)
OBJECT hPen;
STRING sName;
STRING sMessage;
IF ObjectIsValid(hPA) THEN
hPen = _ObjectGetProperty(hPA, "LastSelectedPen");
IF ObjectIsValid(hPen) THEN
sName = _ObjectGetProperty(hPen, "Name");
END
sMessage = "The name of the selected pen is:^n" + sName;
Message("Citect", sMessage, 48);
END
END
Enabling and Disabling a Command
You can also respond to the UpdateCommand event to control the enable/disable
state of the commands toolbar button. The example below disables the button if
there are no pens.
[VBA]
Sub CPA_E_UpdateCommand(commandId As String)
Select Case commandId
Case "SelectedPen"
Call OnUpdatedSelectedPen()
End Select
End Sub
Sub OnUpdatedSelectedPen()
Dim pen As Object
Dim sName As String
On Error Goto errHandler
Set command = test_CPA.CommandSystem.ItemById("SelectedPen")
Set pen = test_CPA.LastSelectedPen
sName = pen.Name
command.Enabled = True
Exit Sub
errHandler:
command.Enabled = False
End Sub
[Cicode]
FUNCTION CPA_E_UpdateCommand(OBJECT hPA, STRING commandId)
SELECT CASE commandId
CASE "PaneLock"
OnUpdatePaneLock(hPA);
CASE "SelectedPen"
OnUpdateSelectedPen(hPA);
END SELECT
END
FUNCTION OnUpdateSelectedPen(OBJECT hPA)
OBJECT hPen = _ObjectGetProperty(hPA, "LastSelectedPen");
OBJECT hCommandSystem = _ObjectGetProperty(hPA,
"CommandSystem");
OBJECT hCommand = _ObjectCallMethod(hCommandSystem,
"get_ItemById", "SelectedPen");
INT iError = 0;
ErrSet(1);
_ObjectGetProperty(hPen, "Name");
iError = IsError();
IF (iError <> 0) THEN
_ObjectSetProperty(hCommand, "Enabled", 0);
ELSE
_ObjectSetProperty(hCommand, "Enabled", -1);
END
ErrSet(0);
END
See Also UpdateCommand [Event]
Implementing a custom
column
Custom columns are added to the Object View allowing you to display your
own information associated with a pen.
The sample below implements a column that calculates the Display Period for
each pen on the Process Analyst. The sample consists of three functions: an
update function and two event handlers to ensure the column is updated when
new pens are added and when the time span is changed.
The Update Function
The update function is complex since it needs to match an Object View pen item
with a real pen object; however, this isnt too difficult because the Object View
tree always reflects how many panes and pens are being displayed.
The code achieves this by iterating through each pane and pen object in the
Process Analyst while simultaneously keeping a running index count of which
pane/pen item it matches up to in the Object View tree.
By using these indexes the code knows which row to update. A row update is
achieved using the PutField method.
Note: Implementing your own column is CPU-intensive. Try to keep the amount
of code required to calculate a row value as efficient as possible and be aware
how often the code will be executed. Note also that, for efficiency, the
BlockUpdates and UnblockUpdates functions are used to limit the number of
updates made to the Object View.
Event Handlers
Once you have a function that implements your custom column, you need to
know when to update that column. The most common method of doing this is to
implement event handlers for particular Process Analyst events. The example
below uses the PenCreated event and the HorizontalAxisChanged event.
These events will ensure that the column values will be updated when pens are
added to the display and when the time span changes.
See Also IObjectViewItem.PutField [Method], IProcessAnalyst.BlockUpdates [Method],
IProcessAnalyst.UnBlockUpdates [Method], PenCreated [Event],
HorizontalAxisChanged [Event]
[VBA]
Sub UpdateMyColumn()
Dim iPaneItem As Integer
Dim iPane As Integer
Dim nPanes As Integer
Dim nSamples As Integer
Dim penItem As Object
Dim paneItem As Object
nSamples = test_CPA.NumberOfSamples
iPaneItem = 0
nPanes = test_CPA.Panes.Count
For iPane = 1 To nPanes
Dim pane As Object
Set pane = test_CPA.Panes.Item(iPane)
If IsNUll(pane) = False Then
Dim pen As Object
Dim iPen As Integer
Dim iPenItem As Integer
Dim nPens As Integer
iPaneItem = iPaneItem + 1
Set paneItem = test_CPA.ObjectView.Items.Item(iPaneItem)
test_CPA.BlockUpdates
iPenItem = 0
nPens = pane.Pens.Count
For iPen = 1 To nPens
Set pen = pane.pens.Item(iPen)
If IsNUll(pen) = False Then
Dim dDiff As Double
Dim sText As string
Dim dtStart As Date
Dim dtEnd As Date
Dim dtStartMs As Integer
Dim dtEndMs As Integer
iPenItem = iPenItem + 1
pen.GetHorizontalAxisTimeSpan dtStart, dtStartMs, dtEnd, dtEndMs, False
dDiff = ((CDbl(dtEnd) - CDbl(dtStart)) / nSamples) * 86400
If (dDiff >= 0.001) Then
sText = CStr(Format(dDiff, "#0.000")) + " seconds"
Else
sText = "0.001 seconds"
End If
Set penItem = paneItem.Items.Item(iPenItem)
If IsNUll(penItem) = False Then
penItem.Putfield "DisplayPeriod", sText
End If
End If
Next
test_CPA.UnblockUpdates
End If
Next
End Sub
Sub CPA_E_HorizontalAxisChanged(hPen As Object)
UpdateMyColumn
End Sub
Sub CPA_E_PenCreated(hPen As Object)
UpdateMyColumn
End Sub
[Cicode]
FUNCTION UpdateMyColumn()
OBJECThPA = ObjectByName("CPA");
OBJECThPanes = _ObjectGetProperty(hPA, "Panes");
OBJECThPane;
OBJECThPens;
OBJECThPen;
OBJECThObjectView = _ObjectGetProperty(hPA, "ObjectView");
OBJECThPaneItems = _OBJECTGetProperty(hObjectView, "Items");
OBJECThPaneItem;
OBJECThPenItems;
OBJECThPenItem;
INT nPanes = _ObjectGetProperty(hPanes, "Count");
INT nPens;
INT iPen;
INT iPane = 0;
INT nSamples = _ObjectGetProperty(hPA, "NumberOfsamples");
INT iPenItem = 0;
INT iPaneItem = 0;
REAL dDiff;
REAL dtStart;
REAL dtEnd;
INT dtStartMs;
INT dtEndMs;
STRINGsText;
FOR iPane = 1 TO nPanes DO
hPane = _ObjectCallMethod(hPanes, "get_Item", iPane);
IF ObjectIsValid(hPane) THEN
hPens = _ObjectGetProperty(hPane, "Pens");
nPens = _ObjectGetProperty(hPens, "Count");
iPaneItem = iPaneItem + 1;
_ObjectCallMethod(hPA, "BlockUpdates");
hPaneItem = _ObjectCallMethod(hPaneItems, "get_Item", iPaneItem);
iPenItem = 0;
FOR iPen = 1 TO nPens DO
hPen = _ObjectCallMethod(hPens, "get_Item", iPen);
IF ObjectIsValid(hPen) THEN
iPenItem = iPenItem + 1;
_ObjectCallMethod(hPen, "GetHorizontalAxisTimeSpan", dtStart, dtStartMs,
dtEnd, dtEndMs, 0);
dDiff = ((dtEnd - dtStart) / nSamples) * 86400;
IF dDiff > 0.001 THEN
sText = StrFormat(dDiff, 10, 3, "seconds");
ELSE
sText = "0.001 seconds"
END
hPenItems = _ObjectGetProperty(hPaneItem, "Items");
hPenItem = _ObjectCallMethod(hPenItems, "get_Item", iPenItem);
_ObjectCallMethod(hPenItem, "PutField", "DisplayPeriod", sText);
END
END
_ObjectCallMethod(hPA, "UnblockUpdates");
END
END
END
FUNCTION CPA_E_HorizontalAxisChanged(OBJECT hPA, OBJECT hPen)
UpdateMyColumn();
END
FUNCTION CPA_E_PenCreated(OBJECT hPA, OBJECT hPen)
UpdateMyColumn();
END
Index
A
acknowledgement, alarm, 17
Add Cursor command, 31
Add New Pens dialog box, 34
Add Pane command, 54, 74
Add Pen command, 74
adding
panes, 54
pens, 34
toolbar commands, 65, 89
alarm acknowledgement, 17
alarm label value, 32
alarm pen types, 18
alarm pens, 16, 56
alarm states, 17
alarm types, 16
AlarmType enumeration, 143
analog pens, 15
association, tag, 77
automation model, 97
Autoscale Vertical Axis command, 74
autoscaling, 74
Autoscroll command, 26
autoscrolling, 26
axis
configuring, 58
horizontal, 11
vertical, 13
AxisLabelType enumeration, 143
B
Back Half a Span command, 72
Back One Span command, 72
background color, configuring, 52, 55
Boolean terms during searches, 34
C
columns, configuring Object View, 66
command system, 95
CommandExecuted event, 95, 141
commands
Add Cursor, 31
Add Pane, 54, 74
Add Pen, 74
adding new, 89
Autoscale Vertical Axis, 74
Autoscroll, 26
Back Half a Span, 72
Back One Span, 72
Copy to Clipboard, 46, 73
Copy to File, 46
Edit Span, 28, 72
Edit Vertical Scale, 28, 72
editing, 90
export, 73
Forward Half a Span, 72
Forward One Span, 72
general, 74
Help, 74
interface, 73
Load View, 69, 71
Lock/Unlock Cursor Labels, 31, 73
Lock/Unlock Pens, 20, 73
Lock/Unlock Vertical Axis Scrolling, 74
navigation, 72
Print, 74
Refresh Data, 74
Remove Pane, 74
Remove Pen, 35, 74
Reset to Default Span, 29, 72
Save View, 68, 71
Show Properties, 74
Show/Hide Cursor, 31, 73
Show/Hide Cursor Labels, 31, 73
Show/Hide Points, 73
Synchronize to Now, 26, 73
Toggle Auto-Scrolling, 26, 73
Toggle Box Zoom, 27, 72
Toggle Object View, 38, 74
Toggle Span Lock, 25, 72
Undo Last Zoom, 27, 72
view, 71
zoom, 72
Zoom In 50%, 26
Zoom in 50%, 72
Zoom Out 50%, 26
312 Index
Zoom out 50%, 72
compaction, data, 9
comparison, trend, 20
configuring
appearance of pens, 55
axes, 58
chart panes, 54
chart-wide properties, 51
columns in Object View, 66
cursor labels, 62
cursors, 63
data connection, 61
defaults, 64
design time properties, 89
general properties, 52
gridlines, 57
pen quality, 60
refresh rate, 52
report options, 43, 45
server paths, 53
toolbars, 65
connection, data, 61
context menu. See right-click menu
Copy to Clipboard command, 46, 73
Copy to File command, 46
copying data, 47
Create method, 95
creating custom commands, 95
cursor labels, 29, 62
CursorMoved event, 135
cursors, 29
configuring, 63
custom commands, 95
custom commands, adding, 89
D
data
copying, 47
exporting, 46
data compaction, 9
data connection, configuring, 61
data quality, 11
data request mode, 62
data request rate, configuring, 52
date/time axis, 11
Daylight Savings, 23
Daylight Savings time, 12
defaults, configuring, 64
deleting
pens, 35
design time properties, configuring, 89
digital pens, 16
display, time, 12
E
Edit Command dialog box, 91
Edit Span command, 28, 72
Edit Span dialog box, 28
Edit Vertical Scale command, 28, 72
Edit Vertical Scale dialog box, 28
editing commands, 90
effect, halo, 19
end time, specifying, 22
Error event, 135
ErrorNotifyCode enumeration, 148
execution result, 97
export commands, 73
exporting data, 46
F
FileLocation enumeration, 150
filtering pens, 34
Fit to unit, 25
fixed height for panes, specifying, 55
Forward Half a Span command, 72
Forward One Span command, 72
G
general commands, 74
general properties, configuring, 52
GetCommandSystem() property, 95
graphics page, inserting onto, 77
gridlines, 14, 57
H
halo effect, 19
HatchStyle enumeration, 145
Help command, 74
HorizontalAxisChanged event, 133
313 Index
I
IAlarmPen interface, 157
IAlarmPen.AlarmType property, 159
IAlarmPen.GetFillColor method, 160
IAlarmPen.GetHatchColor method, 162
IAlarmPen.GetHatchStyle method, 164
IAlarmPen.LineColor property, 157
IAlarmPen.LineWidth property, 158
IAlarmPen.SetFillColor method, 161
IAlarmPen.SetHatchColor method, 163
IAlarmPen.SetHatchStyle method, 165
IAnalogPen interface, 150
IAnalogPen.LineColor property, 150
IAnalogPen.LineInterpolation property, 151
IAnalogPen.LineWidth property, 152
ICommand interface, 269
ICommand.ButtonType property, 270
ICommand.CommandId property, 269
ICommand.Enabled property, 271
ICommand.Pressed property, 272
ICommand.Privilege property, 273
ICommand.Tooltip property, 273
ICommandSystem interface, 263
ICommandSystem._NewEnum property, 265
ICommandSystem.Count property, 264
ICommandSystem.Create method, 266
ICommandSystem.Execute method, 268
ICommandSystem.Item property, 264
ICommandSystem.ItemById property, 266
ICommandSystem.Remove method, 268
icons, custom, 96
ICursors interface, 165
ICursors._NewEnum property, 168
ICursors.Count property, 169
ICursors.Create method, 166
ICursors.Item property, 167
ICursors.ItemByName property, 169
ICursors.RemoveAll method, 167
IDigitalPen interface, 153
IDigitalPen.Fill property, 156
IDigitalPen.FillColor property, 153
IDigitalPen.LineColor property, 154
IDigitalPen.LineWidth property, 155
Insert ActiveX dialog box, 77
interface commands, 73
interfaces, automation model, 98
interpolation, 15, 56
IObjectView interface, 239
IObjectView.BackgroundColor property, 241
IObjectView.Columns property, 243
IObjectView.ForeColor property, 242
IObjectView.Height property, 241
IObjectView.Items property, 244
IObjectView.SelectedItem property, 245
IObjectView.Visible property, 240
IObjectViewColumn interface, 261
IObjectViewColumn.Name property, 261
IObjectViewColumn.Text property, 262
IObjectViewColumn.Width property, 263
IObjectViewColumns interface, 255
IObjectViewColumns._NewEnum property, 261
IObjectViewColumns.Add method, 255
IObjectViewColumns.Count property, 258
IObjectViewColumns.Hide method, 256
IObjectViewColumns.Item property, 259
IObjectViewColumns.ItemByName property, 260
IObjectViewColumns.Remove method, 257
IObjectViewColumns.Show method, 258
IObjectViewItem interface, 247
IObjectViewItem.Expanded property, 249
IObjectViewItem.GetField method, 248
IObjectViewItem.Items property, 251
IObjectViewItem.PutField method, 249
IObjectViewItem.Tag property, 250
IObjectViewItems interface, 245
IObjectViewItems._NewEnum property, 247
IObjectViewItems.Count property, 246
IObjectViewItems.Item property, 246
IObjectViewPenItem interface, 252
IObjectViewPenItem.BlockColor property, 252
IObjectViewPenItem.Checked property, 253
IObjectViewPenItem.Selected property, 254
IPane interface, 288
IPane.BackgroundColor property, 292
IPane.Collection property, 290
IPane.Delete method, 288
IPane.FixedHeight property, 293
IPane.Height property, 289
IPane.Name property, 291
IPane.Pens property, 294
314 Index
IPanes interface, 283
IPanes._NewEnum property, 287
IPanes.Count property, 285
IPanes.Create method, 284
IPanes.Item property, 286
IPanes.ItemByName property, 287
IPanes.RemoveAll method, 285
IPen interface, 183
IPen.AddSample method, 185
IPen.AxisBackgroundColor property, 207
IPen.BlockRepaint property, 208
IPen.Clear method, 186
IPen.Collection property, 209
IPen.DataPoint property, 209
IPen.DataServer property, 210
IPen.Delete method, 187
IPen.GetDefaultSpan method, 187
IPen.GetHorizontalAxisTimeSpan method, 189
IPen.GetInformation method, 190
IPen.GetStatistic method, 192
IPen.GetVerticalAxisSpan method, 193
IPen.GoToNow method, 194
IPen.Height property, 211
IPen.HorizontalAxisColor property, 212
IPen.HorizontalAxisResize property, 213
IPen.HorizontalAxisScroll property, 214
IPen.HorizontalAxisWidth property, 215
IPen.HorizontalGridlinesColor property, 216
IPen.HorizontalGridlinesStyle property, 217
IPen.HorizontalGridlinesWidth property, 218
IPen.HorizontalMinorGridlinesColor property, 219
IPen.HorizontalMinorGridlinesStyle property, 220
IPen.HorizontalScrollBy method, 194
IPen.HorizontalZoom method, 195
IPen.IsDeleted property, 220
IPen.IsSelected property, 221
IPen.LocalTime property, 222
IPen.Name property, 223
IPen.PointsVisible property, 196
IPen.PutHorizontalAxisTimeSpan method, 197
IPen.PutVerticalAxisSpan method, 198
IPen.RefreshData method, 199
IPen.RequestMode property, 224
IPen.ResetToDefaultSpan method, 200
IPen.Select method, 201
IPen.SetDefaultSpan method, 201
IPen.SetQualityCompactionPointType method, 202
IPen.SetQualityLineStyle method, 203
IPen.SetVerticalAxisLabelValue method, 204
IPen.Stacked property, 225
IPen.TrendCursorLabelFillColor property, 225
IPen.TrendCursorLabelLineColor property, 226
IPen.TrendCursorLabelTextColor property, 227
IPen.VerticalAxisAutoscale property, 228
IPen.VerticalAxisColor property, 229
IPen.VerticalAxisLabelType property, 230
IPen.VerticalAxisResize property, 231
IPen.VerticalAxisScroll property, 232
IPen.VerticalAxisWidth property, 233
IPen.VerticalGridlinesColor property, 234
IPen.VerticalGridlinesStyle property, 235
IPen.VerticalGridlinesWidth property, 236
IPen.VerticalMinorGridlinesColor property, 237
IPen.VerticalMinorGridlinesStyle property, 237
IPen.VerticalScrollBy method, 205
IPen.VerticalZoom method, 206
IPen.Visible property, 238
IPens interface, 294
IPens._NewEnum property, 298
IPens.Count property, 296
IPens.Create method, 295
IPens.Item property, 297
IPens.ItemByName property, 298
IPens.Pane property, 299
IPens.RemoveAll method, 296
IProcessAnalyst interface, 95, 99
IProcessAnalyst.AdminPrivilegeLevel property, 111
IProcessAnalyst.AutoScroll property, 112
IProcessAnalyst.BackgroundColor property, 113
IProcessAnalyst.BlockUpdates method, 100
IProcessAnalyst.CommandSystem property, 114
IProcessAnalyst.ContextMenu property, 115
IProcessAnalyst.CopyToClipboard method, 102
IProcessAnalyst.CopyToFile method, 103
IProcessAnalyst.Cursors property, 116
IProcessAnalyst.DataRequestRate property, 117
IProcessAnalyst.DisplayRefreshRate property, 118
IProcessAnalyst.Language property, 119
IProcessAnalyst.LastSelectedPen property, 120
IProcessAnalyst.LoadFromFile method, 105
315 Index
IProcessAnalyst.LockedPens property, 121
IProcessAnalyst.ObjectView property, 122
IProcessAnalyst.Panes property, 124
IProcessAnalyst.PrimaryPath property, 125
IProcessAnalyst.PrintAll method, 106
IProcessAnalyst.SaveToFile method, 107
IProcessAnalyst.SecondaryPath property, 126
IProcessAnalyst.ShowProperties method, 108
IProcessAnalyst.SubscribeForPropertyChange
method, 108
IProcessAnalyst.SynchroniseToNow method, 110
IProcessAnalyst.Toolbars property, 127
IProcessAnalyst.UnBlockUpdates method, 101
IProcessAnalyst.UnsubscribePropertyChange meth-
od, 110
IProcessAnalyst.WritePrivilegeLevel property, 127
IProcessAnalyst.ZoomMode property, 128
IToolbar interface, 276
IToolbar.Buttons property, 277
IToolbar.Visible property, 277
IToolbarButton interface, 283
IToolbarButton.CommandId property, 283
IToolbarButtons interface, 278
IToolbarButtons._NewEnum property, 282
IToolbarButtons.Add method, 279
IToolbarButtons.Count property, 281
IToolbarButtons.Item property, 281
IToolbarButtons.Remove method, 279
IToolbarButtons.RemoveAll method, 280
IToolbars interface, 274
IToolbars._NewEnum property, 276
IToolbars.Count property, 275
IToolbars.Item property, 275
ITrendCursor interface, 170
ITrendCursor.Collection property, 176
ITrendCursor.Color property, 173
ITrendCursor.Delete method, 172
ITrendCursor.GetValue method, 171
ITrendCursor.LabelsLocked property, 183
ITrendCursor.Name property, 177
ITrendCursor.PenLabelHeight property, 180
ITrendCursor.PenLabelVisible property, 178
ITrendCursor.PenLabelWidth property, 179
ITrendCursor.PenLabelX property, 181
ITrendCursor.PenLabelY property, 182
ITrendCursor.Position property, 174
ITrendCursor.Visible property, 175
ITrendCursor.Width property, 174
L
label value, alarm, 32
legends, report, 43
line styles, 11
LineStyle enumeration, 145
LineType enumeration, 148
Load dialog box, 69
Load View command, 69, 71
loading views, 69
Lock pens check box, 53
Lock/Unlock Cursor Labels, 73
Lock/Unlock Cursor Labels command, 31
Lock/Unlock Pens command, 20, 73
Lock/Unlock Vertical Axis Scrolling command, 74
locked pens, 20
M
main page (Properties dialog), 50
main toolbar, 7
menu, right-click, 32
mode, request, 10
model, automation, 97
mouse, using for interaction, 33
MouseClick event, 130
MouseDoubleClick event, 129
multi-language support, 79
multiple samples, 9
N
navigating time, 25
navigation commands, 72
navigation toolbar, 22
New Command dialog box, 89
Now indicator, 12
number of samples, 53
O
Object View, 37
basic functions, 38
configuring columns, 66
316 Index
creating columns, 91
default columns for, 38
editing columns, 91
Object View (Properties dialog), 51
Operator (term defined), 1
OVColumnAdded event, 140
OVColumnRemoved event, 140
overlaying pens, 14
OVItemAdded event, 137
OVItemChecked event, 139
OVItemRemoved event, 138
OVItemSelected event, 139
P
panes
adding, 54
configuring, 54
paths, server, configuring, 53
Pen Details box, 36
PenCreated event, 131
PenDeleted event, 131
PenNameMode enumeration, 146
PenRenamed event, 132
pens
adding, 34
alarm, 16
analog, 15
appearance, 55
axes, configuring, 58
deleting, 35
digital, 16
filtering, 34
gridlines, configuring, 57
locked, 20
overlaying, 14
quality, configuring, 60
selecting, 19
stacking, 14
unlocked, 20
viewing details, 36
PenSelectionChanged event, 132
PenType enumeration, 146
permissions, 77
persistence, 96
point styles, 10
pointer, mouse, 33
PointType enumeration, 146
primary file server, 54
Print command, 74
Print dialog box, 43
printing reports, 42
Process Analyst button, 77
Properties dialog box, 49
property tree, 50
PropertyChanged event, 136
Q
quality
configuring pen, 60
quality, data, 11
QualityCompactionType enumeration, 149
QualityType enumeration, 149
R
Refresh Data command, 74
refresh rate, configuring, 52
Remove Pane command, 74
Remove Pen command, 35, 74
removing
chart panes, 54
toolbar commands, 65
report legends, 43
report options, configuring, 43, 45
reports, 41
configuring, 43
printing, 42
request mode, data, 10, 62
RequestMode enumeration, 147
Reset to Default Span command, 29, 72
result, execution, 97
right-click menu, 32, 50
S
samples, number of, 53
Save Process Analyst View dialog box, 68
Save View command, 68, 71
saving views, 68
scaling, 21
scrolling, 21
317 Index
security, 77
selecting
pens, 19
time span, 25
server paths, configuring, 53
Shift by unit, 24
Show Properties command, 74
Show/Hide Cursor command, 31, 73
Show/Hide Cursor Labels command, 31, 73
Show/Hide Points command, 73
Span Picker, 25
stacked pens, 14
standby file server, 54
start time, specifying, 22
states, alarm, 17
statistical analysis options (reports), 44
stepped interpolation, 15, 56
straight interpolation, 15, 56
styles
line, 11
point, 10
Synchronize to Now command, 26, 73
system, command, 95
T
tag association, 77
tag properties, viewing, 36
time display, 12
time format, 23
time span
editing, 28
term defined, 25
time, navigating, 25
Toggle Auto-Scrolling command, 73
Toggle Auto-scrolling command, 26
Toggle Box Zoom command, 27, 72
Toggle Object View command, 38, 74
Toggle Span Lock command, 25, 72
toolbar, navigation, 22
ToolbarButtonType enumeration, 147
toolbars
adding commands to, 65
changing order of commands, 66
configuring, 65
removing commands from, 65
toolbars (Properties dialog), 51
Tooltip text, 90
tree, property, 50
types, alarm, 16
types, alarm pen, 18
U
Undo Last Zoom command, 27, 72
universal time coordinate (UTC) format, 60
unlocked pens, 20
unstacked pens, 14
UpdateCommand event, 95, 142
User (term defined), 1
V
value, alarm label, 32
variable height for panes, specifying, 55
vertical (value) axis, 13
VerticalAxisChanged event, 134
view commands, 71
viewing
pen details, 36
views, 68
loading, 69
saving, 68
Z
zoom commands, 72
Zoom In 50% command, 26
Zoom in 50% command, 72
Zoom Out 50% command, 26
Zoom out 50% command, 72
318 Index

CitectSCADA Process Analyst

Uploaded by

Copyright:

Available Formats

CitectSCADA Process Analyst

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

CitectSCADA Process Analyst

Uploaded by

Copyright:

Available Formats

Process Analyst User Guide

Citect Pty. Limited

You might also like