CitectSCADA-Process-Analyst.pdf
April 6, 2018 | Author: Anonymous |
Category:
Documents
Description
v7.10 Process Analyst User Guide November 2008 Legal Notice DISCLAIMER Citect Pty Ltd 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 replace- ment of this manual with another. Further, Citect Pty Ltd reserves the right to revise this publication at any time without incurring an obligation to notify any person of the revision. COPYRIGHT © Copyright 2008 Citect Pty Ltd All rights reserved. TRADEMARKS Citect Pty Ltd has made every effort to supply trademark information about company names, products and services mentioned in this manual. Citect, CitectHMI, and CitectSCADA are registered trademarks of Citect Pty. Ltd. IBM, IBM PC and IBM PC AT are registered trademarks of International Business Machines Corporation. MS-DOS, Windows, Windows NT, Microsoft, and Excel are either registered trademarks or trademarks of Mi- crosoft Corporation in the United States and/or other countries. DigiBoard, PC/Xi and Com/Xi are trademarks of Digi International Inc. Novell, Netware and Netware Lite are are either registered trademarks or trademarks of Novell, Inc. in the United States and other countries.. dBASE is a trademark of dataBased Intelligence, Inc. All other brands and products referenced in this document are acknowledged to be the trademarks or regis- tered trademarks of their respective holders. GENERAL NOTICE Some product names used in this manual are used for identification purposes only and may be trademarks of their respective companies. November 2008 edition for CitectSCADA Version v7.10 Manual Revision Version v7.10. Contact Citect today at www.Citect.com 3 Contents Legal Notice.....................................................................................2 Process Analyst for Developers ................................................13 Chapter: 1 Integration with CitectSCADA..................................15 Configuring the Process Analyst Control from Graphics Builder .......... 15 Tag Association........................................................................ 15 Security and Permissions ..................................................................... 15 Administration privilege ............................................................ 16 Command privilege................................................................... 16 Write privilege........................................................................... 16 Multi-language Support......................................................................... 17 Understanding the Process Analyst resources......................... 17 Using CitectSCADA to switch the Process Analyst language .. 17 Manually switching languages.................................................. 18 Specifying languages for the Web Client.................................. 18 Creating your own Process Analyst resource.dll ...................... 18 Persistence ........................................................................................... 22 Saving while using the Citect Graphics Builder ........................ 22 Using the Save View toolbar button ......................................... 23 Using the SaveToFile automation method ............................... 23 Saving between CitectSCADA page transitions (Run-time) ..... 23 Resetting back to the default state ........................................... 24 Backing up Projects .............................................................................. 24 Chapter: 2 Configuring Design Time Properties.......................25 Adding New Commands ....................................................................... 25 Editing Existing Custom Commands..................................................... 26 Creating or Editing Object View Columns............................................. 26 Process Analyst View Synchronization................................................. 27 Chapter: 3 Using the Process Analyst Command System.......29 Command System Overview ................................................................ 29 Custom Commands .............................................................................. 29 CommandExecuted.................................................................. 29 UpdateCommand ..................................................................... 29 Icons ..................................................................................................... 30 Chapter: 4 Automation Model .....................................................31 Execution Results ................................................................................. 31 Enumerations........................................................................................ 32 AlarmType [Enumeration]......................................................... 32 AxisLabelType [Enumeration]................................................... 33 Contents 4 ErrorNotifyCode [Enumeration] ................................................ 34 FileLocation [Enumeration]....................................................... 35 HatchStyle [Enumeration]......................................................... 35 LineStyle [Enumeration] ........................................................... 35 LineType [Enumeration] ........................................................... 36 PenNameMode [Enumeration] ................................................. 36 PenType [Enumeration]............................................................ 37 PointType [Enumeration] .......................................................... 37 QualityCompactionType [Enumeration].................................... 38 QualityType [Enumeration] ....................................................... 38 RequestMode [Enumeration].................................................... 38 ToolbarButtonType [Enumeration]............................................ 39 Events................................................................................................... 39 CommandExecuted [Event]...................................................... 40 CursorMoved [Event]................................................................ 40 Error [Event] ............................................................................. 41 HorizontalAxisChanged [Event]................................................ 42 MouseClick [Event]................................................................... 43 MouseDoubleClick [Event] ....................................................... 43 OVColumnAdded [Event] ......................................................... 44 OVColumnRemoved [Event] .................................................... 45 OVItemAdded [Event]............................................................... 45 OVItemChecked [Event] ........................................................... 46 OVItemRemoved [Event].......................................................... 47 OVItemSelected [Event] ........................................................... 47 PenCreated [Event] .................................................................. 48 PenDeleted [Event]................................................................... 49 PenRenamed [Event] ............................................................... 49 PenSelectionChanged [Event].................................................. 50 PropertyChanged [Event] ......................................................... 51 UpdateCommand [Event] ......................................................... 52 VerticalAxisChanged [Event] .................................................... 52 Interfaces .............................................................................................. 53 IAlarmPen Interface .............................................................................. 54 IAlarmPen.AlarmType [Property][Get/Set]................................ 54 IAlarmPen.GetFillColor [Method].............................................. 55 IAlarmPen.GetHatchColor [Method] ......................................... 56 IAlarmPen.GetHatchStyle [Method].......................................... 56 IAlarmPen.LineColor [Property][Get/Set].................................. 57 IAlarmPen.LineWidth [Property][Get/Set] ................................. 58 IAlarmPen.SetFillColor [Method] .............................................. 59 IAlarmPen.SetHatchColor [Method] ......................................... 60 IAlarmPen.SetHatchStyle [Method] .......................................... 61 IAnalogPen Interface ............................................................................ 62 IAnalogPen.LineColor [Property][Get/Set]................................ 62 IAnalogPen.LineInterpolation [Property][Get/Set]..................... 63 IAnalogPen.LineWidth [Property][Get/Set] ............................... 64 ICommand Interface ............................................................................. 65 ICommand.Tooltip [Property][Get]............................................ 65 ICommand.ButtonType [Property][Get] .................................... 66 ICommand.CommandId [Property][Get] ................................... 67 Contents 5 ICommand.Enabled [Property][Get/Set] ................................... 67 ICommand.Pressed [Property][Get/Set] ................................... 68 ICommand.Privilege [Property][Get]......................................... 69 ICommandSystem Interface ................................................................. 70 ICommandSystem._NewEnum [Property][Get] ........................ 70 ICommandSystem.Count [Property][Get] ................................. 71 ICommandSystem.Create [Method] ......................................... 71 ICommandSystem.Execute [Method] ....................................... 72 ICommandSystem.Item [Property][Get].................................... 73 ICommandSystem.ItemById [Property][Get] ............................ 74 ICommandSystem.Remove [Method]....................................... 75 ICursors Interface ................................................................................. 75 ICursors._NewEnum [Property][Get] ........................................ 76 ICursors.Count [Property][Get] ................................................. 76 ICursors.Create [Method] ......................................................... 77 ICursors.Item [Property][Get].................................................... 78 ICursors.ItemByName [Property][Get]...................................... 79 ICursors.RemoveAll [Method]................................................... 79 IDigitalPen Interface.............................................................................. 80 IDigitalPen.Fill [Property][Get/Set]............................................ 80 IDigitalPen.FillColor [Property][Get/Set] ................................... 81 IDigitalPen.LineColor [Property][Get/Set] ................................. 82 IDigitalPen.LineWidth [Property][Get/Set] ................................ 83 IObjectView Interface............................................................................ 84 IObjectView.BackgroundColor [Property][Get/Set]................... 84 IObjectView.Columns [Property][Get]....................................... 85 IObjectView.ForeColor [Property][Get/Set]............................... 86 IObjectView.Height [Property][Get/Set] .................................... 86 IObjectView.Items [Property][Get] ............................................ 87 IObjectView.SelectedItem [Property][Get] ................................ 88 IObjectView.Visible [Property][Get/Set] .................................... 89 IObjectViewColumn Interface ............................................................... 90 IObjectViewColumn.Name [Property][Get] ............................... 90 IObjectViewColumn.Text [Property][Get].................................. 91 IObjectViewColumn.Width [Property][Get/Set] ......................... 91 IObjectViewColumns Interface.............................................................. 92 IObjectViewColumns._NewEnum [Property][Get] .................... 92 IObjectViewColumns.Add [Method].......................................... 93 IObjectViewColumns.Count [Property][Get] ............................. 94 IObjectViewColumns.Hide [Method]......................................... 94 IObjectViewColumns.Item [Property][Get]................................ 95 IObjectViewColumns.ItemByName [Property][Get] .................. 96 IObjectViewColumns.Remove [Method]................................... 96 IObjectViewColumns.Show [Method] ....................................... 97 IObjectViewItem Interface..................................................................... 98 IObjectViewItem.Expanded [Property][Get/Set] ....................... 98 IObjectViewItem.GetField [Method].......................................... 99 IObjectViewItem.Items [Property][Get] ................................... 100 IObjectViewItem.PutField [Method] ........................................ 101 IObjectViewItem.Tag [Property][Get/Set] ............................... 102 IObjectViewItems Interface................................................................. 103 Contents 6 IObjectViewItems._NewEnum [Property][Get]........................ 103 IObjectViewItems.Count [Property][Get]................................. 103 IObjectViewItems.Item [Property][Get] ................................... 104 IObjectViewPenItem Interface ............................................................ 105 IObjectViewPenItem.BlockColor [Property][Get] .................... 105 IObjectViewPenItem.Checked [Property][Get/Set] ................. 106 IObjectViewPenItem.Selected [Property][Get]........................ 107 IPane Interface.................................................................................... 108 IPane.BackgroundColor [Property][Get/Set]........................... 108 IPane.Collection [Property][Get] ............................................. 109 IPane.Delete [Method]............................................................ 109 IPane.FixedHeight [Property][Get/Set] ................................... 110 IPane.Height [Property][Get/Set] ............................................ 111 IPane.Name [Property][Get/Set]............................................. 112 IPane.Pens [Property][Get]..................................................... 113 IPanes Interface.................................................................................. 114 IPanes._NewEnum [Property][Get] ........................................ 114 IPanes.Count [Property][Get] ................................................. 114 IPanes.Create [Method].......................................................... 115 IPanes.Item [Property][Get] .................................................... 116 IPanes.ItemByName [Property][Get] ...................................... 117 IPanes.RemoveAll [Method] ................................................... 117 IPen Interface...................................................................................... 118 IPen.AddSample..................................................................... 119 IPen.AxisBackgroundColor [Property][Get/Set]...................... 121 IPen.BlockRepaint [Property][Get/Set] ................................... 121 IPen.Clear [Method]................................................................ 122 IPen.Collection [Property][Get] ............................................... 123 IPen.DataPoint [Property][Get/Set]......................................... 123 IPen.DataServer [Property][Get/Set] ...................................... 124 IPen.Delete [Method].............................................................. 125 IPen.GetDefaultSpan [Method]............................................... 126 IPen.GetHorizontalAxisTimeSpan [Method] ........................... 127 IPen.GetInformation [Method] ................................................ 129 IPen.GetStatistic [Method]...................................................... 130 IPen.GetVerticalAxisSpan [Method] ....................................... 131 IPen.GoToNow [Method] ........................................................ 132 IPen.Height [Property][Get/Set] .............................................. 133 IPen.HorizontalAxisColor [Property][Get/Set]......................... 133 IPen.HorizontalAxisResize [Property][Get/Set] ...................... 134 IPen.HorizontalAxisScroll [Property][Get/Set] ........................ 135 IPen.HorizontalAxisWidth [Property][Get/Set] ........................ 136 IPen.HorizontalGridlinesColor [Property][Get/Set] ................. 137 IPen.HorizontalGridlinesStyle [Property][Get/Set] .................. 138 IPen.HorizontalGridlinesWidth [Property][Get/Set]................. 139 IPen.HorizontalMinorGridlinesColor [Property][Get/Set] ........ 139 IPen.HorizontalMinorGridlinesStyle [Property][Get/Set] ......... 140 IPen.HorizontalScrollBy [Method]........................................... 141 IPen.HorizontalZoom [Method]............................................... 142 IPen.IsDeleted [Property][Get]................................................ 143 IPen.IsSelected [Property][Get] .............................................. 144 Contents 7 IPen.LocalTime [Property][Get/Set]........................................ 144 IPen.Name [Property][Get/Set]............................................... 145 IPen.PointsVisible [Property][Get/Set].................................... 146 IPen.PutHorizontalAxisTimeSpan [Method] ........................... 147 IPen.PutVerticalAxisSpan [Method]........................................ 148 IPen.RefreshData [Method] .................................................... 149 IPen.RequestMode [Property][Get/Set] .................................. 150 IPen.ResetToDefaultSpan [Method]....................................... 151 IPen.Select [Method] .............................................................. 151 IPen.SetDefaultSpan [Method] ............................................... 152 IPen.SetQualityCompactionPointType [Method] .................... 153 IPen.SetQualityLineStyle [Method]......................................... 154 IPen.SetVerticalAxisLabelValue [Method] .............................. 155 IPen.Stacked [Property][Get/Set] ........................................... 156 IPen.TrendCursorLabelFillColor [Property][Get/Set] .............. 157 IPen.TrendCursorLabelLineColor [Property][Get/Set] ............ 158 IPen.TrendCursorLabelTextColor [Property][Get/Set]............ 158 IPen.VerticalAxisAutoscale [Property][Get/Set]...................... 159 IPen.VerticalAxisColor [Property][Get/Set] ............................. 160 IPen.VerticalAxisLabelType [Property][Get/Set]..................... 161 IPen.VerticalAxisResize [Property][Get/Set]........................... 162 IPen.VerticalAxisScroll [Property][Get/Set]............................. 163 IPen.VerticalAxisWidth [Property][Get/Set] ............................ 164 IPen.VerticalGridlinesColor [Property][Get/Set]...................... 165 IPen.VerticalGridlinesStyle [Property][Get/Set] ...................... 166 IPen.VerticalGridlinesWidth [Property][Get/Set] ..................... 166 IPen.VerticalMinorGridlinesColor [Property][Get/Set]............. 167 IPen.VerticalMinorGridlinesStyle [Property][Get/Set] ............. 168 IPen.VerticalScrollBy [Method] ............................................... 169 IPen.VerticalZoom [Method] ................................................... 170 IPen.Visible [Property][Get/Set].............................................. 171 IPens Interface.................................................................................... 171 IPens._NewEnum [Property][Get] .......................................... 172 IPens.Count [Property][Get] ................................................... 172 IPens.Create [Method]............................................................ 173 IPens.Item [Property][Get] ...................................................... 174 IPens.ItemByName [Property][Get] ........................................ 175 IPens.Pane[Property][Get]...................................................... 175 IPens.RemoveAll [Method] ..................................................... 176 IProcessAnalyst Interface ................................................................... 177 IProcessAnalyst.BlockUpdates [Method]................................ 178 IProcessAnalyst.UnBlockUpdates [Method] ........................... 178 IProcessAnalyst.CopyToClipboard [Method].......................... 179 IProcessAnalyst.CopyToFile [Method] ................................... 180 IProcessAnalyst.FreezeEvent [Method] ................................. 181 IProcessAnalyst.LoadFromFile [Method]................................ 182 IProcessAnalyst.PrintAll [Method] .......................................... 183 IProcessAnalyst.SaveToFile [Method].................................... 183 IProcessAnalyst.ShowProperties [Method] ............................ 184 IProcessAnalyst.SubscribeForPropertyChange [Method] ...... 185 IProcessAnalyst.SynchroniseToNow [Method]....................... 186 Contents 8 IProcessAnalyst.UnsubscribePropertyChange [Method]........ 187 IProcessAnalyst.AdminPrivilegeLevel [Property] [Get]........... 188 IProcessAnalyst.AutoScroll [Property][Get/Set]...................... 189 IProcessAnalyst.BackgroundColor [Property][Get/Set] .......... 190 IProcessAnalyst.CommandSystem [Property][Get]................ 191 IProcessAnalyst.ContextMenu [Property][Get/Set]................. 192 IProcessAnalyst.Cursors [Property][Get]................................ 192 IProcessAnalyst.DataRequestRate [Property][Get/Set] ......... 193 IProcessAnalyst.DisplayRefreshRate [Property][Get/Set] ...... 194 IProcessAnalyst.Language [Property] [Get/Set] ..................... 195 IProcessAnalyst.LastSelectedPen [Property][Get] ................. 196 IProcessAnalyst.LockedPens [Property][Get/Set] .................. 197 IProcessAnalyst.NumberofSamples[Property][Get/Set] ......... 198 IProcessAnalyst.ObjectView [Property][Get] .......................... 199 IProcessAnalyst.Panes [Property][Get] .................................. 200 IProcessAnalyst.PrimaryPath [Property][Get/Set] .................. 200 IProcessAnalyst.SecondaryPath [Property][Get/Set] ............. 201 IProcessAnalyst.Toolbars [Property][Get] .............................. 202 IProcessAnalyst.WritePrivilegeLevel [Property][Get].............. 203 IProcessAnalyst.ZoomMode [Property][Get/Set] .................... 204 IToolbar Interface................................................................................ 205 IToolbar.Buttons [Property][Get]............................................. 205 IToolbar.Visible [Property][Get/Set] ........................................ 206 IToolbars Interface.............................................................................. 207 IToolbars.Item [Property][Get] ................................................ 207 IToolbars._NewEnum [Property][Get]..................................... 208 IToolbars.Count [Property][Get].............................................. 208 IToolbarButton Interface ..................................................................... 209 IToolbarButton.CommandId [Property][Get] ........................... 209 IToolbarButtons Interface.................................................................... 210 IToolbarButtons._NewEnum [Property][Get] .......................... 210 IToolbarButtons.Add [Method]................................................ 210 IToolbarButtons.Count [Property][Get] ................................... 211 IToolbarButtons.Item [Property][Get]...................................... 212 IToolbarButtons.Remove [Method]......................................... 212 IToolbarButtons.RemoveAll [Method]..................................... 213 ITrendCursor Interface........................................................................ 214 ITrendCursor.Collection [Property][Get] ................................. 214 ITrendCursor.Color [Property][Get/Set] .................................. 215 ITrendCursor.Delete [Method] ................................................ 216 ITrendCursor.GetValue [Method] ........................................... 217 ITrendCursor.LabelsLocked [Property][Get/Set] .................... 218 ITrendCursor.Name [Property][Get/Set] ................................. 218 ITrendCursor.PenLabelHeight [Property][Get/Set] ................. 219 ITrendCursor.PenLabelVisible [Property][Get/Set]................. 220 ITrendCursor.PenLabelWidth [Property][Get/Set] .................. 221 ITrendCursor.PenLabelX [Property][Get/Set] ......................... 222 ITrendCursor.PenLabelY [Property][Get/Set] ......................... 223 ITrendCursor.Position [Property][Get/Set].............................. 224 ITrendCursor.Visible [Property][Get/Set] ................................ 225 ITrendCursor.Width [Property][Get/Set] ................................. 226 Contents 9 Chapter: 5 Automation Examples............................................227 Handling an Event .................................................................. 227 Enumerating collections ......................................................... 228 Implementing a custom command.......................................... 229 Implementing a custom column.............................................. 231 Process Analyst for Operators ................................................235 Chapter: 6 The Process Analyst: An Overview.......................237 Chapter: 7 Using the Main Toolbar...........................................239 Chapter: 8 Understanding Process Analyst Pens ..................241 Data Compaction.................................................................... 241 Data Quality............................................................................ 242 Date/Time (Horizontal) Axis.................................................... 243 Vertical (Value) Axis ............................................................... 244 Gridlines ................................................................................. 245 Pen Layout ............................................................................. 245 Pen Types........................................................................................... 246 Analog pens............................................................................ 246 Digital pens............................................................................. 247 Alarm pens ............................................................................. 247 Chapter: 9 Interacting with the Process Analyst ....................251 Pens: An Overview ............................................................................. 251 Pen Selection...................................................................................... 251 Locking/Unlocking Pens...................................................................... 252 Scrolling the Chart .............................................................................. 252 Scaling the Chart ................................................................................ 253 Using the Navigation Toolbar.............................................................. 253 Specifying a start time and end time ...................................... 254 About time spans.................................................................... 256 Span Lock............................................................................... 256 Navigating time....................................................................... 256 Synchronize to Now................................................................ 257 Toggle Autoscrolling............................................................... 257 Zoom In/Zoom Out ................................................................. 257 Undo Last Zoom..................................................................... 257 Toggle Box Zoom................................................................... 258 Edit Span................................................................................ 258 Edit Vertical Scale .................................................................. 259 Reset to Default Span ............................................................ 259 Using Cursors ..................................................................................... 260 Using Cursor Labels ........................................................................... 261 Using the Right-click Menu ................................................................. 262 Understanding Mouse Pointers........................................................... 262 Contents 10 Adding and Deleting Pens .................................................................. 263 Adding Pens ........................................................................... 263 Deleting Pens ......................................................................... 264 Viewing Pen Details............................................................................ 264 Chapter: 10 Using the Object View...........................................267 Object View Basics ............................................................................. 267 Using Object View............................................................................... 268 Chapter: 11 Printing and Exporting..........................................269 About Process Analyst Reports .......................................................... 269 Configuring Process Analyst Report Options...................................... 270 Setting up report legends ....................................................... 270 Setting up report options ........................................................ 271 Exporting Pen Data............................................................................. 272 Copying data to the Clipboard................................................ 273 Copying data to file................................................................. 273 Chapter: 12 Configuring the Process Analyst.........................275 Using the Process Analyst Properties Dialog Box .............................. 275 Main page............................................................................... 275 Toolbars.................................................................................. 276 Object View ............................................................................ 277 Configuring Chart-wide Properties...................................................... 277 Configuring general properties ............................................... 277 Configuring server paths ........................................................ 278 Configuring Chart Panes..................................................................... 279 Configuring Pens ................................................................................ 280 Configuring pen appearance .................................................. 280 Configuring pen gridlines........................................................ 282 Configuring pen axes.............................................................. 282 Configuring pen quality........................................................... 284 Configuring the pen data connection...................................... 284 Configuring cursor labels........................................................ 285 Configuring Cursors............................................................................ 286 Configuring Defaults ........................................................................... 286 Configuring Toolbars........................................................................... 287 Adding or removing toolbar commands.................................. 287 Changing the order of toolbar commands .............................. 288 Configuring the Object View ............................................................... 288 Object View properties page .................................................. 289 Working with Views............................................................................. 289 Saving a view ......................................................................... 290 Loading a view........................................................................ 290 Chapter: 13 Operator Command Reference............................293 View Commands................................................................................. 293 Zoom Commands ............................................................................... 293 Contents 11 Navigation Commands........................................................................ 294 Export Commands .............................................................................. 295 Interface Commands........................................................................... 295 General Commands............................................................................ 296 Glossary.......................................................................................297 Index.............................................................................................315 Contents 12 Process Analyst for Developers This section contains information for developers and describes the following: Integration with CitectSCADA Configuring Process Analyst Design Time Properties Using the Process Analyst Command System Automation Model Cicode Programming Reference Automation Examples 14 15 Chapter: 1 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 applica- tions. 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 Con- trols 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 You can create an association between a property of an ActiveX object and a variable tag. To create an association between a property of an ActiveX object and a variable tag: 1. Double-click the ActiveX object. The Properties dialog box appears. 2. Click the Tag Association tab. 3. Select a property from the Properties list. 4. Click the Wizard | Insert Tag button. 5. Select a tag from the list and click OK. See Also "ActiveX Object Properties" in CitectSCADA User Guide "Understanding Object Types" in CitectSCADA User Guide Security and Permissions The Process Analyst integrates seamlessly into the CitectSCADA security model by allow- ing access to certain Process Analyst features based on the privilege level of the currently logged in Operator. Chapter: 1 Integration with CitectSCADA 16 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) priv- ilege levels of security provided by CitectSCADA. The Process Analyst, by default, as- sumes 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 func- tion would then become available. The Process Analyst also supports the CitectSCADA Hi- erarchical 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-orient- ed 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 Administra- tion privilege level should never be zero on a running system as this would expose prop- erties to an Operator, which could adversely affect the performance of the client and/or server (for example, Number Of Samples property). The features that are disabled when an operator does not meet the Administration privi- lege 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 Chapter: 1 Integration with CitectSCADA 17 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 An- alyst; these native translations are considered the default language. For example, the Japa- nese 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_.dll, where 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, for example English) - Resources_fr.dll (French standard) - Resources_zh-CN.dll (Chinese PRC) - Resources_de.dll (German) Using CitectSCADA to switch the Process Analyst language CitectSCADA uses the Cicode function SetLanguage to switch languages at run time. To al- low the Process Analyst to determine the language it should display, you must map your CitectSCADA 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: Chapter: 1 Integration with CitectSCADA 18 LanguagePath.= where is the name of a specific CitectSCADA language translation database, and is the language code of the resources.dll file that has the equiva- lent translations. For example, [ProcessAnalyst] LanguagePath.French=fr LanguagePath.Chinese=zh-CN LanguagePath.German=de The last step is to verify each of your machines contains the necessary language fonts. Win- dows 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 sys- tem. 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.Lan- guage 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 lan- guage 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 down- load and use. (You can find these files in your \Program Files\Common Files\Citect fold- er.) 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. Chapter: 1 Integration with CitectSCADA 19 Note: To create your own resources.dll file, you'll 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 Ser- vices and Input Languages dialog box. 6. In the Installed services section, verify 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. (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 sys- tem, 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 Pro- grams section. 9. Click Apply and then OK (you may need to restart your system). Chapter: 1 Integration with CitectSCADA 20 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. Verify 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 similar. To change input language: 1. Click EN to display the input language option menu. Chapter: 1 Integration with CitectSCADA 21 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 localiz- ing. 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. Verify that the Files of type menu has Executable Files (.exe;.dll;*.ocx) selected. 5. Verify 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 con- ventions. Chapter: 1 Integration with CitectSCADA 22 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. Choose Properties from the right-click (context) menu (see below). 4. From the Language menu, select the language that you are localizing for. 5. Click Close 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 re- move 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 CitectSCADA 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 CitectSCADA 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, Chapter: 1 Integration with CitectSCADA 23 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 prop- erties 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 config- urations. Saving between CitectSCADA 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 Graphics Builder provides an option Persist Ac- tiveX 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 CitectSCADA Data directory in the format of .stg whenever you leave a page that contains an ActiveX object (for example, the Process Analyst). When you reenter the page, Cit- ectSCADA 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. Chapter: 1 Integration with CitectSCADA 24 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 An- alyst views, you should verify that the Save sub-directories option is selected in Citect Ex- plorer before backing up your project. 25 Chapter: 2 Configuring 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, usu- ally by a User. For information about configuring run time properties, see Using the Process Analyst Properties Dialog Box. See Also Adding New Commands | Editing Existing Custom Commands | Creating or Editing Ob- ject View Columns | Process Analyst View Synchronization 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 dia- log box appears. 2. 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 command in the CitectSCADA system. 3. 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. 4. Click Browse and navigate to the icon to represent the new command. The icon image appears on the toolbar command button. 5. To define how the command behaves, choose a button style from the Button style menu: 1. Push Button - click the Enabled check box to set the default appearance of the button when the button is enabled or disabled. 2. Toggle Button - click Enabled or Pressed to specify the "on" appearance. Chapter: 2 Configuring Design Time Properties 26 See Also Editing Existing Custom Commands 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 Creating or Editing Object View Columns Users can create or delete Object View columns (during design time), as well as edit exist- ing 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. Chapter: 2 Configuring Design Time Properties 27 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 ap- pears. 2. Modify the information as required, and then click OK. See Also Configuring the Object View Process Analyst View Synchronization 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 ver- sion 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 verify 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. Act i on Mode Pr i v i l ege Avai l abl e St or age Loca- t i ons* Chapter: 2 Configuring Design Time Properties 28 * 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, verify 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 Load Normal client Bot h* * The Primary and St andby op- t ions appear as configured as well as My Document s. I f ei- t her are invalid or unavailable pat hs, t hey do not appear. I f bot h are invalid or unavail- able, t he Local opt ion ap- pears. Default order is Primary, St andby, My Docu- ment s, and Local, My Docu- ment s respect ively. Synchronizat ion occurs when loading from a Primary or St andby locat ion. Load Web client Bot h* * The Local and My Document s opt ions are t he only ones available. Local maps t o t he proj ect direct ory\ Analyst Views. The default order is Lo- cal, My Document s. Save Normal client Privileged The Local and My Document s opt ions are t he only ones available. Local however will at t empt t o save t o all server locat ions as well as t he proj ect direct ory. The . pav file will be saved t o all available locat ions from primary, st andby and proj ect direct o- ries. Default order: Local, My Document s. Save Normal client Unprivileged The My Document s opt ion is t he only one available. Save Normal client Bot h* * The My Document s opt ion is t he only one available. 29 Chapter: 3 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 GetCommandSys- tem() 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 option- ally 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. The state of all commands (custom and pre-defined) will be saved to disk whenever the Process Analyst configuration is saved. Chapter: 3 Using the Process Analyst Command System 30 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. 31 Chapter: 4 Automation Model The automation model allows applications or solutions to programmatically configure the Process Analyst control’s appearance, performance, and behavior. The automation model also allows code, via automation events, to be attached to events fired from the Process An- alyst 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 be- low). To view information for an interface, click the name of the interface in the illustration be- low. 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. 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. Exit Sub errHandler: Print Err.Number, Err.Description Resume Next End Sub Ex ecut i on Resul t Ci code VBA C+ + I nvalidArgument 274 5 E_I NVALI ARG GeneralFailure 356 2147500037 E_FAI L Pat hNot Found 356 76 STG_E_PATHNOTFOUN D Success 0 - S_OK Chapter: 4 Automation Model 32 [Cicode] FUNCTION Test1(OBJECT hObject) ErrSet(1); // Enable User error checking (disabled HW alarm) IF ObjectIsValid(hObject) THEN _ObjectCallMethod(hObject, ""); 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 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] AlarmType [Enumeration] Specifies the visual representation for an alarm pen. Defined As - [VBA] Integer - [Cicode] INT - [C++] AlarmType Members Member Name Descr i pt i on Val ue AlarmType_Digit al The t ag is digit al alarm 0 AlarmType_Analog The t ag is an analog alarm 1 AlarmType_Advanced The t ag is an advanced alarm 2 AlarmType_TimeSt amped The t ag is a t ime- st amped alarm 3 AlarmType_Mult iDigit al The t ag is a mult i- digit al alarm 4 Chapter: 4 Automation Model 33 See Also IAlarmPen.AlarmType [Property][Get/Set] AxisLabelType [Enumeration] Specifies how the labels are drawn on the vertical axis. Defined As - [VBA] Integer - [Cicode] INT - [C++] AxisLabelType Members AlarmType_ArgyleAnalog The t ag is a legacy Argyle analog alarm 5 AlarmType_TimeSt ampedDigit a l The t ag is a digit al t ime- st amped alarm 6 AlarmType_TimeSt ampedAnalo g The t ag is a analog t ime- st amped alarm 7 Member Name Descr i pt i on Val ue AxisLabelType_NONE No labels will be visible on axis 0 AxisLabelType_DOUBLE Displays in decimal format 1 AxisLabelType_I NTEGER Displays in int eger 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_FEETPERMI N 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_GALLONSPERMI N Displays as "gal/ min" 11 AxisLabelType_GALLONSPERSEC Displays as "gal/ s" 12 AxisLabelType_HERTZ Displays as "Hz" 13 AxisLabelType_KI LOGRAMS Displays as "kg" 14 AxisLabelType_KI LOGRAMSPERH R Displays as "kg/ h" 15 AxisLabelType_KI LOGRAMSPERM I N Displays as " kg/ min" 16 AxisLabelType_KI LOGRAMSPERS EC Displays as "kg/ s" 17 AxisLabelType_KI LOMETRESPER HR Displays as "kg/ h" 18 AxisLabelType_KI LOPASCALS Displays as "kPa" 19 AxisLabelType_KI LOWATTS Displays as "kW" 20 AxisLabelType_LI TRES Displays as " l" 21 AxisLabelType_LI TRESPERHR Displays as "l/ h" 22 Chapter: 4 Automation Model 34 ErrorNotifyCode [Enumeration] Defines known errors that can occur during operation. Defined As - [VBA] Integer - [Cicode] INT - [C++] ErrorNotifyCode Members AxisLabelType_LI TRESPERMI N Displays as " l/ min" 23 AxisLabelType_LI TRESPERSEC Displays as " l/ s" 24 AxisLabelType_METRES Displays as "m" 25 AxisLabelType_METRESPERMI N 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_REVSPERMI N Displays as "RPM" 30 AxisLabelType_TONNES Displays as " t " 31 AxisLabelType_TONNESPERHR Displays as "t / h" 32 AxisLabelType_VOLTS Displays as "V" 33 AxisLabelType_WATTS Displays as "W" 34 AxisLabelType_LOOKUP Displays user- defined t ext for label 35 Member Name Descr i pt i on Val ue ErrorNot ifyCode_None No error. 0 ErrorNot ifyCode_I nvalidTag Occurs when t he t ag specified for t he pen does not exist . 1 ErrorNot ifyCode_Ct apiConnect i onOffline Occurs when connect ions cannot be made t o t he Trends and/ or Alarm Servers. 2 ErrorNot ifyCode_Unknown Occurs when an unknown Cit - ect SCADA or Windows error oc- curs. 3 ErrorNot ifyCode_NoServer Occurs when Cit ect SCADA cannot find a server t o get t he dat a from. 4 ErrorNot ifyCode_I nvalidArgume nt Occurs when an invalid argument is specified. 5 ErrorNot ifyCode_Out OfMemory Occurs when a memory error is de- t ect ed. 6 ErrorNot ifyCode_BadVersion Occurs when t he Trends and/ or Alarm Servers do not mat ch t he client version. 7 ErrorNot ifyCode_NoPrivilege Occurs when t he current user does not have t he required privileges t o view t he dat a. 8 Chapter: 4 Automation Model 35 See Also Error [Event] 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] 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] LineStyle [Enumeration] Defines the drawing style for a line. Defined As Member Name Descr i pt i on Val ue FileLocat ion_Local Refers t o t he proj ect folder 0 FileLocat ion_Server Refers t o t he bot h t he primary/ st andby server pat hs 1 FileLocat ion_User Refers t o t he My Document s folder 2 Member Name Descr i pt i on Val ue Hat chSt yle_None No pat t ern 0 Hat chSt yle_Horizont al Horizont al line pat t ern 1 Hat chSt yle_Vert ical Vert ical line pat t ern 2 Hat chSt yle_ForwardDiagonal Forward diagonal line pat t ern 3 Hat chSt yle_BackwardDiagonal Backward diagonal line pat t ern 4 Hat chSt yle_Cross Cross pat t ern 5 Hat chSt yle_DiagonalCross Diagonal cross pat t ern 6 Chapter: 4 Automation Model 36 - [VBA] Integer - [Cicode] INT - [C++] LineStyle Values 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] 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 Member Name Descr i pt i on Val ue LineSt yle_SOLI D Draws a solid line ( all line widt hs) 0 LineSt yle_DASH Draws a dashed line ( line widt h 1 only) 1 LineSt yle_DOT Draws a dot line ( line widt h 1 only) 2 LineSt yle_DASHDOT Draws a dash dot ( line widt h 1 only) 3 LineSt yle_DASHDOTDOT Draws a dash dot dot ( line widt h 1 only) 4 LineSt yle_NONE Draws no line 5 Member Name Descr i pt i on Val ue LineType_STRA I GHT A single line is drawn from point A t o point B. 0 LineType_STEP PED The line drawn will maint ain t he value of t he previ- ous sample. When t he samples differ, a vert ical line will be drawn t o t he new sample value. 1 Member Name Descr i pt i on Val ue PenNameMode_Com ment The comment field obt ained from t he Cit - ect SCADA t rend/ alarm t ag will be used as t he pen name. 1 Chapter: 4 Automation Model 37 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 Members See Also IPen.SetQualityCompactionPointType [Method] PenNameMode_Tag The value of t he I Pen. Dat aPoint propert y will be used as t he pen name. 2 PenNameMode_Cust o m I ndicat es t hat you will be set t ing t he name using t he I Pen. Name propert y. 3 Member Name Descr i pt i on Val ue PenType_ANALOG A pen wit h an analog range 4097 PenType_DI GI TAL A pen wit h a range of 0 and 1 4098 PenType_ALARM A pen represent ed as st at es 4099 Member Name Descr i pt i on Val ue Point Type_NONE No marker 0 Point Type_RECT A rect angular marker 1 Point Type_CI RCLE A circular marker 2 Point Type_PLUS A plus marker 3 Point Type_CROSS A cross marker 4 Point Type_TRI ANGLE A t riangular marker 5 Point Type_ELLI PSE A ellipt ical marker 6 Chapter: 4 Automation Model 38 QualityCompactionType [Enumeration] Specifies the different types of presentation used for a sample. Defined As - [VBA] Integer - [Cicode] INT - [C++] QualityCompactionType Members See Also IPen.SetQualityCompactionPointType [Method] 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] RequestMode [Enumeration] Defines the data acquisition method for a pen. Defined As - [VBA] Integer - [Cicode] INT - [C++] RequestMode Member Name Descr i pt i on Val ue Qualit yCompact ionType_Single Represent at ion when t he marker rep- resent s a single sample 0 Qualit yCompact ionType_Mult iple Represent at ion when t he marker rep- resent s a calculat ion of t wo or more samples 1 Qualit yCompact ionType_I nt erpolat e d Represent at ion when t he marker rep- resent s int erpolat ed samples 2 Member Name Descr i pt i on Val ue Qualit yType_Good The sample is good 0 Qualit yType_NA I ndicat es a loss of connect ion 1 Qualit yType_Gat ed I ndicat es t he dat a was marked as unwant ed 2 Chapter: 4 Automation Model 39 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 Members See Also ICommandSystem.Create [Method], ICommand.ButtonType [Property][Get] Events CommandExecuted [Event] CursorMoved [Event] Error [Event] HorizontalAxisChanged [Event] MouseClick [Event] MouseDoubleClick [Event] OVColumnAdded [Event] OVColumnRemoved [Event] OVItemAdded [Event] OVItemChecked [Event] OVItemRemoved[Event] OVItemSelected [Event] PenCreated [Event] Member Name Descr i pt i on Val ue Request Mode_Aver age The value will be an average of all t he individual samples wit hin t he mult iple sample, as will t he t imest amp 0 Request Mode_Mini mum The value will be t he minimum value out of all t he individ- ual samples wit hin t he mult iple sample. The t imest amp will be t he average of all t he individual samples. 1 Request Mode_Maxi mum The value will be t he maximum value out of all t he indi- vidual samples wit hin t he mult iple sample. The t imest amp will be t he average of all t he individual samples. 2 Request Mode_Newe st The value will t he lat est arrived value out of all t he indi- vidual samples wit hin t he mult iple sample. The t imest amp will be t he average of all t he individual samples. 3 Member Name Descr i pt i on Val ue ToolbarBut t onType_Push St andard push but t on behavior. 0 ToolbarBut t onType_Toggle The but t on has t wo st at es: On and Off. 1 ToolbarBut t onType_Separat or A visual marker used t o group but t ons. 2 Chapter: 4 Automation Model 40 PenDeleted [Event] PenRenamed [Event] PenSelectionChanged [Event] PropertyChanged [Event] UpdateCommand [Event] VerticalAxisChanged [Event] 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 [in] Indicates the Process Analyst object which raised the event. (Cicode 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 Assumes you have a Process Analyst on a page with an event class defined as myPage_AN35. [VBA] Sub myPage_AN35_CommandExecuted(commandId As String) End Sub [Cicode] FUNCTION myPage_AN35_CommandExecuted(OBJECT processAnalyst, STRING commandId) END CursorMoved [Event] This event is raised whenever the cursor position changes. Defined As - [VBA] CursorMoved(cursor As Object, position As Integer) Chapter: 4 Automation Model 41 - [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 [in] Indicates the Process Analyst object which 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_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 [in] Indicates the Process Analyst object which raised the event. (Cicode only) See Also ErrorNotifyCode [Enumeration] Chapter: 4 Automation Model 42 Calling Syntax Assumes you have a Process Analyst on a page with an event class defined as 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 errorMes- sage) 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 [in] Indicates the Process Analyst object that raised the event (Cicode only). 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 Assumes you have a Process Analyst on a page with an event class defined as AN35_E. [VBA] Sub AN35_E_HorizontalAxisChanged (pen As Object) End Sub Chapter: 4 Automation Model 43 [Cicode] FUNCTION AN35_E_HorizontalAxisChanged (OBJECT processAnalyst, OBJECT pen) 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 [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_MouseClick(pen As Object, button As Integer) End Sub [Cicode] FUNCTION myPage_AN35_MouseClick(OBJECT processAnalyst, OBJECT pen, INT button) 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) Chapter: 4 Automation Model 44 - [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 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 [in] Indicates the Process Analyst object which raised the event. (Cicode only) Calling Syntax Assumes you have a Process Analyst on a page with an event class defined as myPage_AN35. Chapter: 4 Automation Model 45 [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 [in] Indicates the Process Analyst object which 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_OVColumnRemoved(name As String) End Sub [Cicode] FUNCTION myPage_AN35_OVColumnRemoved(OBJECT processAnalyst, STRING name) END OVItemAdded [Event] This event is raised whenever an item is added to the ObjectView. Defined As - [VBA] OVItemAdded(item As Object) Chapter: 4 Automation Model 46 - [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 [in] Indicates the Process Analyst object which 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_OVItemAdded(item As Object) End Sub [Cicode] FUNCTION myPage_AN35_OVItemAdded(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 [in] Indicates the Process Analyst object which 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_OVItemChecked(item As Object) End Sub Chapter: 4 Automation Model 47 [Cicode] FUNCTION myPage_AN35_OVItemChecked(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 [in] Indicates the Process Analyst object which 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_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 Chapter: 4 Automation Model 48 item [in] A reference to the item that was selected in the ObjectView. processAnalyst [in] Indicates the Process Analyst object which 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_OVItemSelected(item As Object) End Sub [Cicode] FUNCTION myPage_AN35_OVItemSelected(OBJECT processAnalyst, OBJECT item) 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 Assumes you have a Process Analyst on a page with an event class defined as myPage_AN35. [VBA] Sub myPage_AN35_PenCreated(pen As Object) End Sub Chapter: 4 Automation Model 49 [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 [in] Indicates the Process Analyst object which 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_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 inter- face. Defined As - [VBA] PenRenamed(pen As Object) - [Cicode] PenRenamed(OBJECT processAnalyst, OBJECT pen) - [C++] PenRenamed(IPen* pen) Parameters pen Chapter: 4 Automation Model 50 [in] Refers to the pen that was renamed. processAnalyst [in] Indicates the Process Analyst object which 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_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 [in] Indicates the Process Analyst object which raised the event. (Cicode only) Remarks Selection can change via user interaction (such as clicking on pens, deleting/adding pens) and automation. Calling Syntax Assumes you have a Process Analyst on a page with an event class defined as myPage_AN35. [VBA] Sub myPage_AN35_PenSelectionChanged(pen As Object) End Sub Chapter: 4 Automation Model 51 [Cicode] FUNCTION myPage_AN35_PenSelectionChanged(OBJECT processAnalyst, OBJECT pen) 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 [in] Indicates the Process Analyst object which raised the event. (Cicode only) Remarks For this event to be raised you must subscribe to one or more properties. See Also IProcessAnalyst.SubscribeForPropertyChange [Method], IProcessAnalyst.Unsub- scribePropertyChange [Method] Calling Syntax Assumes you have a Process Analyst on a page with an event class defined as myPage_AN35. [VBA] Sub myPage_AN35_PropertyChanged(interfaceName As String, propertyName As String) End Sub [Cicode] FUNCTION myPage_AN35_PropertyChanged(OBJECT processAnalyst, STRING interfaceName, STRING propertyName) END Chapter: 4 Automation Model 52 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 [in] Indicates the Process Analyst object which raised the event. (Cicode only) Remarks This event is only raised for custom commands. You should use this event as an opportu- nity 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 re- sponse to this event. An Update will be triggered in at least the following scenarios: - Selection changes - Command execution Calling Syntax Assumes you have a Process Analyst on a page with an event class defined as myPage_AN35. [VBA] Sub myPage_AN35_UpdateCommand(commandId As Integer) End Sub [Cicode] FUNCTION myPage_AN35_UpdateCommand(OBJECT processAnalyst, INT commandId) 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) Chapter: 4 Automation Model 53 Parameters pen [in] Refers to the pen that has changed. processAnalyst [in] Indicates the Process Analyst object which raised the event. (Cicode only) See Also HorizontalAxisChanged [Event] Calling Syntax Assumes you have a Process Analyst on a page with an event class defined as myPage_AN35. [VBA] Sub myPage_AN35_VerticalAxisChanged (pen As Object) End Sub [Cicode] FUNCTION myPage_AN35_VerticalAxisChanged (OBJECT processAnalyst, OBJECT pen) END Interfaces IAlarmPen Interface IAnalogPen Interface ICommand Interface ICommandSystem Interface ICursors Interface IDigitalPen Interface IObjectView Interface IObjectViewColumn Interface IObjectViewColumns Interface IObjectViewItem Interface IObjectViewItems Interface IObjectViewPenItem Interface IPane Interface IPanes Interface IPen Interface IPens Interface IProcessAnalyst Interface IToolbar Interface IToolbars Interface IToolbarButton Interface IToolbarButtons Interface ITrendCursor Interface Chapter: 4 Automation Model 54 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.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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Remarks This AlarmType also dictates the number of alarm states, and their descriptions. See Also IAlarmPen.AlarmType [Property][Get/Set] Calling Syntax This example assumes there is a valid alarm pen object to be passed into the example meth- ods. [VBA] Sub Example(alarmPen As Object) Dim alarmType As Long ‘Getting Property value alarmType = alarmPen.AlarmType ‘Setting Property value to Analog alarmPen.AlarmType = 1 End Sub Chapter: 4 Automation Model 55 [Cicode] FUNCTION Example(OBJECT hAlarmPen) // Getting property value 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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Parameters state [in] The state for which fill color to retrieve (0 to 8). 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 AlarmPen object to be passed into the example meth- ods. [VBA] Sub Example(alarmPen As Object) Dim fillColor As Long fillColor = alarmPen.GetFillColor(0) End Sub [Cicode] FUNCTION Example(OBJECT hAlarmPen) INT nFillColor = _ObjectCallMethod(hAlarmPen, "GetFillColor" , 0); END Chapter: 4 Automation Model 56 IAlarmPen.GetHatchColor [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 range, the re- turn value will be InvalidArgument. If the pen is deleted, the return value will be General- Failure. Parameters state [in] The state for which hatch color to retrieve (0 to 8). 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 AlarmPen object to be passed into the example meth- ods. [VBA] Sub Example(alarmPen As Object) Dim hatchColor As Long hatchColor = alarmPen.GetHatchColor(0) End Sub [Cicode] FUNCTION Example(OBJECT hAlarmPen) INT nHatchColor = _ObjectCallMethod(hAlarmPen, "GetHatchColor" , 0); END IAlarmPen.GetHatchStyle [Method] Gets the hatch style used when drawing the boxes for the specified state. Chapter: 4 Automation Model 57 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 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 return value will be Gener- alFailure. 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. See Also IAlarmPen.GetHatchStyle [Method] Calling Syntax This example assumes there is a valid AlarmPen object to be passed into the example meth- ods. [VBA] Sub Example(alarmPen As Object) Dim hatchStyle As Long hatchStyle = alarmPen.GetHatchStyle(0) End Sub [Cicode] FUNCTION Example(OBJECT hAlarmPen) INT nHatchStyle = _ObjectCallMethod(hAlarmPen, "GetHatchStyle", 0); END IAlarmPen.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 Chapter: 4 Automation Model 58 If the property get/set succeeds the return value will be Success. If the return variable is bad then 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 alarm pen object to be passed into the example meth- ods. [VBA] Sub Example(alarmPen As Object) Dim lineColor As Long ‘Getting Property value lineColor = alarmPen.LineColor ‘Setting Property to red alarmPen.LineColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hAlarmPen) // Getting property value INT nLineColor = _ObjectGetProperty(hAlarmPen, "LineColor"); // Setting property to red _ObjectSetProperty(hAlarmPen, "LineColor", 255); END IAlarmPen.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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is deleted the return value will be GeneralFailure. Limits - Minimum = 0 - Maximum = 8 Chapter: 4 Automation Model 59 Calling Syntax This example assumes there is a valid alarm pen object to be passed into the example meth- ods. [VBA] Sub Example(alarmPen As Object) Dim lineWidth As Long ‘Getting Property value lineWidth = alarmPen.LineWidth ‘Setting Property value alarmPen.LineWidth = 5 End Sub [Cicode] FUNCTION Example(OBJECT hAlarmPen) // Getting property value INT nLineWidth = _ObjectGetProperty(hAlarmPen, "LineWidth"); // Setting property value _ObjectSetProperty(hAlarmPen, "LineWidth", 5); 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 re- turn value will be InvalidArgument. If the pen is deleted, the return value will be General- Failure. 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. Chapter: 4 Automation Model 60 Calling Syntax This example assumes there is a valid AlarmPen object to be passed into the example meth- ods. [VBA] Sub Example(alarmPen As Object) Dim fillColor As Long ‘Setting FillColor to Red alarmPen.SetFillColor(0, 255) End Sub [Cicode] FUNCTION Example(OBJECT hAlarmPen) // Setting FillColor to Red _ObjectCallMethod(hAlarmPen, "SetFillColor" ,0, 255); END IAlarmPen.SetHatchColor [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 return value will be Gener- alFailure. 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 AlarmPen object to be passed into the example meth- ods. Chapter: 4 Automation Model 61 [VBA] Sub Example(alarmPen As Object) Dim hatchColor As Long ‘Setting HatchColor to Red alarmPen.SetHatchColor(0, 255) End Sub [Cicode] FUNCTION Example(OBJECT hAlarmPen) // Setting HatchColor to Red _ObjectCallMethod(hAlarmPen, "SetHatchColor",0, 255); END IAlarmPen.SetHatchStyle [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 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 return value will be Gener- alFailure. 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. See Also IAlarmPen.GetHatchStyle [Method] Calling Syntax This example assumes there is a valid AlarmPen object to be passed into the example meth- ods. Chapter: 4 Automation Model 62 [VBA] Sub Example(alarmPen As Object) ‘Setting HatchStyle alarmPen.SetHatchStyle(0, 1) End Sub [Cicode] FUNCTION Example(OBJECT hAlarmPen) // Setting HatchStyle _ObjectCallMethod(hAlarmPen, "SetHatchStyle" ,0, 1); END 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 If the property get/set succeeds, the return value will be Success. If the return 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. Chapter: 4 Automation Model 63 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 ‘Getting Property value 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.LineInterpolation [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 If the property get/set succeeds the return value will be Success. If the return 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. Chapter: 4 Automation Model 64 [VBA] Sub Example(analogPen As Object) Dim lineInterpolation As Long ‘Getting Property value lineInterpolation = analogPen.LineInterpolation ‘Setting Property value analogPen.LineInterpolation = 1 End Sub [Cicode] FUNCTION Example(OBJECT hAnalogPen) // Getting property value 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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. 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] Sub Example(analogPen As Object) Dim lineWidth As Long ‘Getting Property value lineWidth = analogPen.LineWidth ‘Setting Property value analogPen.LineWidth = 5 End Sub Chapter: 4 Automation Model 65 [Cicode] FUNCTION Example(OBJECT hAnalogPen) // Getting property value INT nLineWidth = _ObjectGetProperty(hAnalogPen, "LineWidth"); // Setting property value _ObjectSetProperty(hAnalogPen, "LineWidth", 5); 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.Tooltip [Property][Get] Gets this commands Tooltip text. Defined As - [VBA] String Tooltip - [Cicode] STRING Tooltip - [C++] VARIANT_BOOL Tooltip Execution Result If the property get succeeds, the return value will be Success. If the return variable is in- valid, the return value will be InvalidArgument. If the command has been deleted, the re- turn value will be GeneralFailure. Remarks This returns the text that is displayed in a tooltip window when the mouse pointer hovers over the command’s button. Calling Syntax This example assumes there is a valid Command object as retrieved from a Process Ana- lyst’s CommandSystem. (for example, VBA: ProcessAnalyst.CommandSystem.Item(1)) Chapter: 4 Automation Model 66 [VBA] Sub Example(Command As Object) Dim tooltip As String ‘Getting Property value tooltip = Command.Tooltip End Sub [Cicode] FUNCTION Example(OBJECT hCommand) // Getting property value STRING sTooltip = _ObjectGetProperty(hCommand, "Tooltip"); 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 deleted, the return val- ue will be GeneralFailure. Remarks The return value meaning is as follows: - ToolbarButtonType_Push = 0 - ToolbarButtonType_Toggle = 1 - ToolbarButtonType_Separator = 2 Calling Syntax This example assumes there is a valid Command object as retrieved from a Process Ana- lyst’s CommandSystem. (for example, VBA: ProcessAnalyst.CommandSystem.Item(1)) [VBA] Sub Example(Command As Object) Dim buttonType As Long ‘Getting Property value buttonType = Command.ButtonType End Sub Chapter: 4 Automation Model 67 [Cicode] FUNCTION Example(OBJECT hCommand) // Getting property value INT nButtonType = _ObjectGetProperty(hCommand, "ButtonType"); END 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 Ana- lyst’s CommandSystem (for example, VBA: ProcessAnalyst.CommandSystem.Item(1)). [VBA] Sub Example(Command As Object) Dim commandId As String ‘Getting Property value commandId = Command.CommandId End Sub [Cicode] FUNCTION Example(OBJECT hCommand) // Getting property value STRING nCommandId = _ObjectGetProperty(hCommand,"CommandID"); 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 Chapter: 4 Automation Model 68 - True (-1): Enabled - Falso (0): Disabled Remarks The setting of this property is only valid for custom commands. Calling Syntax This example assumes there is a valid Command object as retrieved from a Process Ana- lyst’s CommandSystem. (for example, VBA: ProcessAnalyst.CommandSystem.Item(1)) [VBA] Sub Example(Command As Object) Dim enabled As Boolean ‘Getting Property value enabled = Command.Enabled ‘Setting Property value Command.Enabled = True End Sub [Cicode] FUNCTION Example(OBJECT hCommand) // Getting property value INT nEnabled = _ObjectGetProperty(hCommand, "Enabled"); // Setting property value _ObjectSetProperty(hCommand, "Enabled", -1); END ICommand.Pressed [Property][Get/Set] Gets and Sets this command’s Pressed state. Defined As - [VBA] Boolean Pressed - [Cicode] INT Pressed - [C++] VARIANT_BOOL Pressed Execution Result If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. 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 Chapter: 4 Automation Model 69 This example assumes there is a valid Command object as retrieved from a Process Ana- lyst’s CommandSystem. (for example, VBA: ProcessAnalyst.CommandSystem.Item(1)) [VBA] Sub Example(Command As Object) Dim pressed As Boolean ‘Getting Property value pressed = Command.Pressed ‘Setting Property value Command.Pressed = True End Sub [Cicode] FUNCTION Example(OBJECT hCommand) // Getting property value INT nPressed = _ObjectGetProperty(hCommand, "Pressed"); // Setting property value _ObjectSetProperty(hCommand, "Pressed", -1); 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 If the property get succeeds, the return value will be Success. If the return variable is in- valid, the return value will be InvalidArgument. If the command has been deleted, the re- turn value will be GeneralFailure. Remarks This is the required privilege level of the currently logged in CitectSCADA user to enable the state of this command, and hence allow access through the user interface. If the current- ly logged in CitectSCADA user doesn’t have this privilege, any buttons tied to this com- mand will be disabled. Calling Syntax This example assumes there is a valid Command object as retrieved from a Process Ana- lyst’s CommandSystem. (for example, VBA: ProcessAnalyst.CommandSystem.Item(1)) [VBA] Sub Example(Command As Object) Dim privilege As Integer ‘Getting Property value Chapter: 4 Automation Model 70 privilege = Command.Privilege End Sub [Cicode] FUNCTION Example(OBJECT hCommand) // Getting property value INT nPrivilege = _ObjectGetProperty(hCommand, "Privilege"); 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._NewEnum [Property][Get] This allows "For... Each... Next" integration in VB. Calling Syntax This example assumes there is a valid CommandSystem object as retrieved from a Process Analyst. (for example, VBA: ProcessAnalyst.CommandSystem). This property is not appli- cable to Cicode. [VBA] Sub Example(CommandSystem As Object) Dim command As Object Dim count Object ‘Using Property For Each command In CommandSystem count = count + 1 Next command End Sub Chapter: 4 Automation Model 71 ICommandSystem.Count [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. (for example, VBA: ProcessAnalyst.CommandSystem). [VBA] Function Example(CommandSystem As Object) Dim count As Long ‘Getting Property value count = CommandSystem.Count End Function [Cicode] FUNCTION Example(OBJECT hCommandSystem) // Getting property value INT nCount = _ObjectGetProperty(hCommandSystem, "Count"); END ICommandSystem.Create [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 Chapter: 4 Automation Model 72 [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 command’s picture. privilege [in] A privilege value required by the CitectSCADA 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 This example assumes there is a valid CommandSystem object as retrieved from a Process Analyst. (for example, VBA: ProcessAnalyst.CommandSystem). [VBA] Sub Example(CommandSystem As Object) Dim command As Object Set command = CommandSystem.Create(CommandIO, "Some tooltip text", "c:\some- icon.ico", 5) End Sub [Cicode] FUNCTION Example(OBJECT hCommandSystem) OBJECT hCommand = _ObjectCallMethod(hCommandSystem, "Create", CommandIO, "Some tool- tip text", "c:\someicon.ico", 5); END ICommandSystem.Execute [Method] Executes the specified command’s action. Defined As - [VBA] Execute (commandId As String) - [Cicode] Execute (STRING commandId) - [C++] HRESULT Execute(BSTR commandId) Chapter: 4 Automation Model 73 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 re- turn value will be InvalidArgument. Remarks If the current Operator does not have the correct privilege, the command will not execute. Calling Syntax This example assumes there is a valid CommandSystem object as retrieved from a Process Analyst. (for example, VBA: ProcessAnalyst.CommandSystem). [VBA] Sub Example(CommandSystem As Object) CommandSystem.Execute(Citect_Command_AddPen) End Sub [Cicode] FUNCTION Example(OBJECT hCommandSystem) _ObjectCallMethod(hCommandSystem, "Execute", Citect_Command_AddPen); END ICommandSystem.Item [Property][Get] Gets the Command 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, ICommand* Item) Parameters index [in] Indicates the index location of the command 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, the return value will be InvalidArgument. Calling Syntax This example assumes there is a valid CommandSystem object as retrieved from a Process Analyst. (for example, VBA: ProcessAnalyst.CommandSystem). Chapter: 4 Automation Model 74 [VBA] Sub Example(CommandSystem As Object) Dim command As Object ‘Getting Property value Set command = CommandSystem.Item(1) End Sub [Cicode] FUNCTION Example(OBJECT hCommandSystem) // Getting property value OBJECT hCommand = _ObjectCallMethod(hCommandSystem, "get_Item", 1); END ICommandSystem.ItemById [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 This example assumes there is a valid CommandSystem object as retrieved from a Process Analyst. (for example, VBA: ProcessAnalyst.CommandSystem). [VBA] Sub Example(CommandSystem As Object) Dim command As Object ‘Getting Property value Set command = CommandSystem.ItemById(Citect_Command_AddPen) End Sub [Cicode] FUNCTION Example(OBJECT hCommandSystem) // Getting property value OBJECT hCommand = _ObjectCallMethod (hCommandSystem," get_ItemById", Citect_Command_AddPen); END Chapter: 4 Automation Model 75 ICommandSystem.Remove [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 This example assumes there is a valid CommandSystem object as retrieved from a Process Analyst. (for example, VBA: ProcessAnalyst.CommandSystem). [VBA] Sub Example(CommandSystem As Object) CommandSystem.Remove("MyCommand1") End Sub [Cicode] FUNCTION Example(OBJECT hCommandSystem) _ObjectCallMethod(hCommandSystem, "Remove", "MyCommand1"); 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] Chapter: 4 Automation Model 76 ICursors._NewEnum [Property][Get] Retrieves an enumerator for the cursors collection. Defined As - [VBA] Object _NewEnum() - [C++] HRESULT get__NewEnum(LPUNKNOWN *pVal) Execution Result If the property get succeeds, the return value will be Success. If the return 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 Syn- tax, 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] Sub Example(cursors As Object) 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 If the property get succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the collection is deleted the return value will be GeneralFailure. Remarks This property may be used in conjunction with the Item property to iterate through the col- lection in Cicode. Calling Syntax This example assumes you have a valid reference to the cursors collection. Chapter: 4 Automation Model 77 [VBA] Sub Example(cursors As Object) Dim cursorCount As Integer cursorCount = cursors.Count End Sub [Cicode] FUNCTION Example(OBJECT hCursors) INT cursorCount; cursorCount = _ObjectGetProperty(hCursors, "Count"); END 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 charac- ters. 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 Chapter: 4 Automation Model 78 [Cicode] FUNCTION Example(OBJECT hCursors) OBJECT hNewCursor = _ObjectCallMethod(hCursors, "Create", "Cursor1", 100); END 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 property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. 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 Chapter: 4 Automation Model 79 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 If the property get succeeds, the return value will be Success. If the return 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] Sub Example(cursors As Object) Dim cursor As Object Set cursor = cursors.ItemByName("MyCursor") End Sub [Cicode] FUNCTION Example(OBJECT hCursors) OBJECT hCursor = _ObjectCallMethod(hCursors, "get_ItemByName", "MyCursor"); END ICursors.RemoveAll [Method] Removes all cursors from the collection. Defined As - [VBA] RemoveAll() - [Cicode] RemoveAll() - [C++] HRESULT RemoveAll() Execution Result Chapter: 4 Automation Model 80 If the function succeeds the return value will be Success. If an unexpected error occurs, the return value will be GeneralFailure. Calling Syntax This example assumes there is a valid Cursors object to be passed into the example meth- ods. [VBA] Sub Example(cursors As Object) cursors.RemoveAll End Sub [Cicode] FUNCTION Example(OBJECT hCursors) _ObjectCallMethod(hCursors, "RemoveAll"); End Sub 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.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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is deleted the return value will be GeneralFailure. Remarks Chapter: 4 Automation Model 81 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 meth- ods. [VBA] Sub Example(digitalPen As Object) Dim fill As Boolean ‘Getting Property value fill = digitalPen.Fill ‘Setting Property value digitalPen.Fill = True End Sub [Cicode] FUNCTION Example(OBJECT hDigitalPen) // Getting property value INT nFill = _ObjectGetProperty(hDigitalPen, "Fill"); // Setting property value _ObjectSetProperty(hDigitalPen, "Fill", -1); END 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 If the property get/set succeeds, the return value will be Success. If the return 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) Chapter: 4 Automation Model 82 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 meth- ods. [VBA] Sub Example(digitalPen As Object) Dim fillColor As Long ‘Getting Property value fillColor = digitalPen.FillColor ‘Setting Property to red digitalPen.FillColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hDigitalPen) // Getting property value INT nFillColor = _ObjectGetProperty(hDigitalPen, "FillColor"); // Setting property to red _ObjectSetProperty(hDigitalPen, "FillColor", 255); END IDigitalPen.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 If the property get/set succeeds the return value will be Success. If the return variable is bad then 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 DigitalPen object to be passed into the example meth- ods. Chapter: 4 Automation Model 83 [VBA] Sub Example(digitalPen As Object) Dim lineColor As Long ‘Getting Property value lineColor = DigitalPen.LineColor ‘Setting Property to red digitalPen.LineColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hDigitalPen) // Getting property value INT nLineColor = _ObjectGetProperty(hDigitalPen, "LineColor"); // Setting property to red _ObjectSetProperty(hDigitalPen, "LineColor", 255); END IDigitalPen.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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is deleted the return value will be GeneralFailure. 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] Sub Example(digitalPen As Object) Dim lineWidth As Long ‘Getting Property value lineWidth = digitalPen.LineWidth ‘Setting Property value digitalPen.LineWidth = 5 End Sub Chapter: 4 Automation Model 84 [Cicode] FUNCTION Example(OBJECT hDigitalPen) // Getting property value INT nLineWidth = _ObjectGetProperty(hDigitalPen, "LineWidth"); // Setting property value _ObjectSetProperty(hDigitalPen, "LineWidth", 5); 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.BackgroundColor [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 - [VBA] Long BackgroundColor - [Cicode] INT BackgroundColor - [C++] OLE_COLOR BackgroundColor Execution Result If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. 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 that there is an IObjectView object being passed in as a parameter. Chapter: 4 Automation Model 85 [VBA] Sub Example(objectView As Object) Dim backgroundColor As Long ‘Getting Property value backgroundColor = objectView.BackgroundColor ‘Setting Property value to red objectView.BackgroundColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hObjectView) // Getting property value INT nBackgroundColor = _ObjectGetProperty(hObjectView,"BackgroundColor"); // Setting Property to Red _ObjectSetProperty(hObjectView, "BackgroundColor", 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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. Calling Syntax This example assumes that there is an IObjectView object being passed in as a parameter. [VBA] Sub Example(objectView As Object) Dim columns As Object ‘Getting Property value Set columns = objectView.Columns End Sub [Cicode] FUNCTION Example(OBJECT hObjectView) // Getting property value OBJECT hColumns = _ObjectGetProperty(hObjectView, "Columns"); END Chapter: 4 Automation Model 86 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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. 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 that there is an IObjectView object being passed in as a parameter. [VBA] Sub Example(objectView As Object) Dim foreColor As Long ‘Getting Property value foreColor = objectView.ForeColor ‘Setting Property value to red objectView.ForeColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hObjectView) INT nForeColor = 0; // Getting property value nForeColor = _ObjectGetProperty(hObjectView, "ForeColor"); // Setting Property to red _ObjectSetProperty(hObjectView, "ForeColor", 255); END IObjectView.Height [Property][Get/Set] Gets or Sets the height in pixels of the Object View window. Defined As - [VBA] Long Height Chapter: 4 Automation Model 87 - [Cicode] INT Height - [C++] int Height Execution Result If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. A height value less than 0 will be InvalidArgu- ment. 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] Sub Example(objectView As Object) Dim height As Long ‘Getting Property value height = objectView.Height ‘Setting Property value objectView.Height = 25 End Sub [Cicode] FUNCTION Example(OBJECT hObjectView) INT nHeight = 0; // Getting property value nHeight = _ObjectGetProperty(hObjectView, "Height"); // Setting Property to false _ObjectSetProperty(hObjectView, "Height", 25); 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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. Chapter: 4 Automation Model 88 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 This example assumes that there is an IObjectView object being passed in as a parameter. [VBA] Sub Example(objectView As Object) Dim items As Object ‘Getting Property value Set items = objectView.Items End Sub [Cicode] FUNCTION Example(OBJECT hObjectView) // Getting property value OBJECT hItems = _ObjectGetProperty(hObjectView, "Items"); END IObjectView.SelectedItem [Property][Get] Gets the current primary selection in the ObjectView. This is the pen item that was last se- lected. Defined As - [VBA] Object SelectedItem - [Cicode] OBJECT SelectedItem - [C++] IObjectViewItem* SelectedItem Execution Result If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. Calling Syntax This example assumes that there is an IObjectView object being passed in as a parameter. [VBA] Sub Example(objectView As Object) Dim selectedItem As Object ‘Getting Property value Set selectedItem = objectView.SelectedItem End Sub Chapter: 4 Automation Model 89 [Cicode] FUNCTION Example(OBJECT hObjectView) // Getting property value OBJECT hSelectedItem = _ObjectGetProperty(hObjectView, "SelectedItem"); END IObjectView.Visible [Property][Get/Set] Gets or Sets the visibility of the Object View window. Defined As - [VBA] Boolean Visible - [Cicode] INT Visible - [C++] VARIANT_BOOL Visible Execution Result If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. 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) Dim visible As Boolean ‘Getting Property value visible = objectView.Visible ‘Setting Property value objectView.Visible = False End Sub [Cicode] FUNCTION Example(OBJECT hObjectView) INT bVisible = 0 // Getting property value bVisible = _ObjectGetProperty(hObjectView, "Visible"); // Setting Property to false _ObjectSetProperty(hObjectView, "Visible", 0); END Chapter: 4 Automation Model 90 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.Name [Property][Get] Retrieves the unique identifier of this column. Defined As - [VBA] String Name - [Cicode] STRING Name - [C++] BSTR Name Execution Result If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. Calling Syntax This example assumes there is a valid column as retrieved from an ObjectView. (for exam- ple, VBA: objectView.Columns.Item(1)). [VBA] Sub Example(objectViewColumn As Object) Dim name As String ‘Getting Property value name = objectViewColumn.Name End Sub [Cicode] FUNCTION Example(OBJECT hObjectViewColumn) // Getting property value STRING name = _ObjectGetProperty(hObjectViewColumn, "Name"); END Chapter: 4 Automation Model 91 IObjectViewColumn.Text [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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. Calling Syntax This example assumes there is a valid column as retrieved from an ObjectView. (for exam- ple, VBA: objectView.Columns.Item(1)). [VBA] Sub Example(objectViewColumn As Object) Dim text As String ‘Getting Property value text = objectViewColumn.Text End Sub [Cicode] FUNCTION Example(OBJECT hObjectViewColumn) // Getting property value STRING text = _ObjectGetProperty(hObjectViewColumn, "Text"); END IObjectViewColumn.Width [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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the width is out of range, the result will be In- validArgument. Limits A valid width is 0-1000. Calling Syntax Chapter: 4 Automation Model 92 This example assumes there is a valid column as retrieved from an ObjectView. (for exam- ple, VBA: objectView.Columns.Item(1)). [VBA] Sub Example(objectViewColumn As Object) Dim width As Long ‘Getting Property value width = objectViewColumn.Width ‘Setting Property value objectViewColumn.Width = 150 End Sub [Cicode] FUNCTION Example(OBJECT hObjectViewColumn) // Getting property value INT width = _ObjectGetProperty(hObjectViewColumn, "Width"); _ObjectSetProperty(hObjectViewColumn, "Width", 150); 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._NewEnum [Property][Get] This allows "For... Each... Next" integration in VB. Calling Syntax This example assumes there is a valid Columns collection as retrieved from an ObjectView. (for example, VBA: objectView.Columns). This property is not applicable in Cicode. Chapter: 4 Automation Model 93 [VBA] Sub Example(Columns As Object) Dim column As Object Dim count Object ‘Using Property For Each column In Columns count = count + 1 Next column End Sub IObjectViewColumns.Add [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. (for example, VBA: objectView.Columns). [VBA] Sub Example(Columns As Object) Columns.Add "NameID", "New Column", 120; End Sub Chapter: 4 Automation Model 94 [Cicode] FUNCTION Example(OBJECT hColumns) _ObjectCallMethod(hColumns, "Add", "NameID", "New Column", 120); END IObjectViewColumns.Count [Property][Get] Gets the number of Columns in this columns 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 return variable is bad, the return value will be InvalidArgument. Calling Syntax This example assumes there is a valid Columns collection as retrieved from an ObjectView. (for example, VBA: ObjectView.Columns). [VBA] Function Example(Columns As Object) Dim count As Long ‘Getting Property value count = Columns.Count End Function [Cicode] FUNCTION Example(OBJECT hColumns) // Getting property value INT nCount = _ObjectGetProperty(hColumns, "Count"); END IObjectViewColumns.Hide [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 Chapter: 4 Automation Model 95 columnName [in] The string ID uniquely identifying the column you want to hide Execution Result If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the field cannot be set, GeneralFailure is re- turned. See Also IObjectViewColumns.Show [Method] Calling Syntax This example assumes there is a columns Collection from an ObjectView. (for example, VBA: objectView.Columns). [VBA] Sub Example(columns As Object) columns.Hide "Error" End Sub [Cicode] FUNCTION Example(OBJECT hColumns) _ObjectCallMethod(hColumns, "Hide", "Error"); END IObjectViewColumns.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, IObjectViewColumn* Item) Parameters index [in] Indicates the index location of the column to return from this collection. (One based) Calling Syntax This example assumes there is a valid Columns collection as retrieved from an ObjectView (for example, VBA: objectView.Columns). [VBA] Sub Example(Columns As Object) Dim column As Object ‘Getting Property value Set column = Columns.Item(1) End Sub Chapter: 4 Automation Model 96 [Cicode] FUNCTION Example(OBJECT hColumns) // Getting property value OBJECT hColumn = _ObjectCallMethod(hColumns, "get_Item", 1); END IObjectViewColumns.ItemByName [Property][Get] Returns a reference to the column object with the given name from this column’s 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 found, the return value will be InvalidArgument. Calling Syntax This example assumes there is a valid Columns collection object to be passed into the ex- ample methods. [VBA] Sub Example(columns As Object) Dim column As Object ‘Getting Property value Set column = columns.ItemByName("Duration") End Sub [Cicode] FUNCTION Example(OBJECT hColumns) // Getting property value OBJECT hColumn = _ObjectCallMethod(hColumns, "get_ItemByName", "Duration"); END IObjectViewColumns.Remove [Method] Removes the specified custom column from the Object View columns. Defined As Chapter: 4 Automation Model 97 - [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 found, the return value will be InvalidArgument. 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 ex- ample methods. [VBA] Sub Example(columns As Object) Dim column As Object ‘Getting Property value Set column = columns.Remove("MyCustomColumn") End Sub [Cicode] FUNCTION Example(OBJECT hColumns) // Getting property value OBJECT hColumn = _ObjectCallMethod(hColumns, "get_ItemByName", "MyCustomColumn"); END IObjectViewColumns.Show [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 Chapter: 4 Automation Model 98 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the field cannot be set, then GeneralFailure is returned. See Also IObjectViewColumns.Hide [Method] Calling Syntax This example assumes there is a columns Collection from an ObjectView. (for example, VBA: objectView.Columns). [VBA] Sub Example(columns As Object) columns.Show "Error" End Sub [Cicode] FUNCTION Example(OBJECT hColumns) _ObjectCallMethod(hColumns, "Show", "Error"); END 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.Expanded [Property][Get/Set] Gets or Sets the expanded state of an item in the ObjectView. This change is reflected im- mediately in the visualization of the ObjectView. Defined As - [VBA] Boolean Expanded - [Cicode] INT Expanded - [C++] VARIANT_BOOL Expanded Chapter: 4 Automation Model 99 Execution Result If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. Limits - True (-1): Expanded - False (0): Collapsed Calling Syntax This example assumes there is a valid Item as retrieved from an Items Collection from an ObjectView. (for example, VBA: objectView.Items.Item(1)). [VBA] Sub Example(objectViewItem As Object) Dim expanded As Boolean ‘Getting Property value expanded = objectViewItem.Expanded ‘Setting Property value objectViewItem.Expanded = False End Sub [Cicode] FUNCTION Example(OBJECT hObjectViewItem) // Getting property value INT nExpanded = _ObjectGetProperty(hObjectViewItem, "Expanded"); // Setting Property _ObjectSetProperty(hObjectViewItem, "Expanded", 0); END IObjectViewItem.GetField [Method] Returns the string value of a displayed field for a specified column on this item. The IObjectViewItem interface is hierarchical to two levels - pane and then pen. The result of the GetField method will depend on what type of item it is called on. To access the fields for a pen, for example, you have to first get the items collection for the pane item, then get the pen 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 Chapter: 4 Automation Model 100 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the ColumnName does not exist, InvalidAr- gument will be returned. Calling Syntax This example gets the Scale property of the first pen in the first pane. It assumes there is a valid Item as retrieved from an Items Collection from an ObjectView. (for example, VBA: objectView.Items.Item(1)) [VBA] Sub Example() Dim paneItem As Object Dim penItem As Object Dim fieldValue As String Set paneItem = Test_CPA.ObjectView.Items.Item(1) 'Get the first pane of the Ob- jectView Set penItem = paneItem.Items.Item(1) 'Get the first pen from the first pane penItem.GetField "Scale", fieldValue 'Get the value of the scale field End Sub [Cicode] FUNCTION Example(OBJECT hObjectView) OBJECT hPaneItems = _ObjectGetProperty(hObjectView, "Items"); OBJECT hPaneItem = _ObjectCallMethod(hPaneItems, "get_Item", 1); // Get the first pane of the ObjectView OBJECT hPenItems = _ObjectGetProperty(hPaneItem, "Items"); // Get the collection of pens from the first pane OBJECT hPenItem = _ObjectCallMethod(hPenItems, "get_Item", 1); // Get the first Pen item STRING sValue; _ObjectCallMethod(hPenItem, "GetField", "Scale", sValue); // Get the value of the scale field 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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. Remarks Pane nodes are currently the only nodes that can have children. Chapter: 4 Automation Model 101 Calling Syntax This example assumes there is a valid item as retrieved from an ObjectView. (for example, VBA: objectView.Items.Item(1). This will be a pane). [VBA] Sub Example(objectViewItem As Object) Dim items As Object ‘Getting Property value Set items = objectViewItem.Items End Sub [Cicode] FUNCTION Example(OBJECT hObjectViewItem) // Getting property value OBJECT hItems = _ObjectGetProperty(hObjectViewItem, "Items"); END IObjectViewItem.PutField [Method] Sets the display string in a field’s cell for a specified column on this item. The IObjectViewItem interface is hierarchical to two levels - pane and then pen. The scope of the PutField method will depend on what type of item it is called on. To set fields for a pen, for example, you have to first get the items collection for the pane item, then get the pen 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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the field cannot be set, then GeneralFailure is returned. Calling Syntax This example writes the value "someValue" to the CustomColumn field of the first pen in the first pane. It assumes there is a valid Item as retrieved from an Items Collection from an ObjectView. (for example, VBA: objectView.Items.Item(1)). Chapter: 4 Automation Model 102 [VBA] Sub Example() Dim paneItem As Object Dim penItem As Object Set paneItem = Test_CPA.ObjectView.Items.Item(1) 'Get the first pane of the Ob- jectView Set penItem = paneItem.Items.Item(1) 'Get the first pen from the first pane penItem.PutField "CustomColumn", "someValue" ’set the value of the CustomColumn field End Sub [Cicode] FUNCTION Example(OBJECT hObjectView) OBJECT hPaneItems = _ObjectGetProperty(hObjectView, "Items"); OBJECT hPaneItem = _ObjectCallMethod(hPaneItems, "get_Item", 1); // Get the first pane of the ObjectView OBJECT hPenItems = _ObjectGetProperty(hPaneItem, "Items"); // Get the collection of pens from the first pane OBJECT hPenItem = _ObjectCallMethod(hPenItems, "get_Item", 1); // Get the first Pen item _ObjectCallMethod(hPenItem, "PutField", "CustomColumn", "someValue"); // Set the value of the CustomColumn field END IObjectViewItem.Tag [Property][Get/Set] Gets or Sets a user specified piece of data to associate with this Item. Defined As - [VBA] Tag - [Cicode] 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 This example assumes there is a valid Item as retrieved from an Items Collection from an ObjectView. (for example, VBA: objectView.Items.Item(1)). [VBA] Sub Example(objectViewItem As Object) Dim tag As Variant ‘Getting Property value tag = objectViewItem.Tag ‘Setting Property value to red objectViewItem.Tag = tag End Sub Chapter: 4 Automation Model 103 [Cicode] FUNCTION Example(OBJECT hObjectViewItem) // Getting property value INT nTag = _ObjectGetProperty(hObjectViewItem, "Tag"); // Setting Property to red _ObjectSetProperty(hObjectView, "Tag", nTag); 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._NewEnum [Property][Get] This allows For.. Each.. Next integration in VB. Calling Syntax This example assumes there is a valid Items collection as retrieved from an ObjectView. (for example, VBA: objectView.Items). This property is not applicable to Cicode. [VBA] Sub Example(Items As Object) Dim item As Object Dim count Object ‘Using Property For Each item In Items count = count + 1 Next Item End Sub IObjectViewItems.Count [Property][Get] Gets the number of child items under this item. Chapter: 4 Automation Model 104 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 return variable is bad, the return value will be InvalidArgument. Calling Syntax This example assumes there is a valid Items collection as retrieved from an ObjectView. (for example, VBA: objectView.Items) [VBA] Sub Example(Items As Object) Dim count As Long ‘Getting Property value count = Items.Count End Sub [Cicode] FUNCTION Example(OBJECT hItems) // Getting property value 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 This example assumes there is a valid Items collection as retrieved from an ObjectView. (for example, VBA: objectView.Items). [VBA] Sub Example(Items As Object) Dim item As Object ‘Getting Property value Chapter: 4 Automation Model 105 Set item = Items.Item(1) End Sub [Cicode] FUNCTION Example(OBJECT hItems) // Getting property value OBJECT hItem = _ObjectCallMethod(hItems, "get_Item", 1); 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.BlockColor [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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. 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 pen item as retrieved from an ObjectView. (for ex- ample, VBA: ObjectView.Items.Item(1).Items.Item(1) This will be a pen). [VBA] Sub Example(objectViewPenItem As Object) Dim blockColor As Long Chapter: 4 Automation Model 106 ‘Getting Property value blockColor = objectViewPenItem.BlockColor End Sub [Cicode] FUNCTION Example(OBJECT hObjectViewPenItem) // Getting property value INT blockColor = _ObjectGetProperty(hObjectViewItem, "BlockColor"); END IObjectViewPenItem.Checked [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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. 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 This example assumes there is a valid pen item as retrieved from an ObjectView. (for ex- ample, VBA: objectView.Items.Item(1).Items.Item(1) This will be a pen). [VBA] Sub Example(objectViewPenItem As Object) Dim checked As Boolean ‘Getting Property value checked = objectViewPenItem.Checked ‘Setting Property value objectViewPenItem.Checked = False End Sub Chapter: 4 Automation Model 107 [Cicode] FUNCTION Example(OBJECT hObjectViewPenItem) // Getting property value INT checked = _ObjectGetProperty(hObjectViewItem, "Checked"); // Setting property value _ObjectSetProperty(hObjectViewItem, "Checked", 0); END IObjectViewPenItem.Selected [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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. 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 This example assumes there is a valid pen item as retrieved from an ObjectView. (for ex- ample, VBA: objectView.Items.Item(1).Items.Item(1) This will be a pen). [VBA] Sub Example(objectViewPenItem As Object) Dim selected As Boolean ‘Getting Property value selected = objectViewPenItem.Selected End Sub [Cicode] FUNCTION Example(OBJECT hObjectViewPenItem) // Getting property value INT selected = _ObjectGetProperty(hObjectViewItem, "Selected"); END Chapter: 4 Automation Model 108 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.BackgroundColor [Property][Get/Set] Gets or Sets the color of this Pane. Defined As - [VBA] Long BackgroundColor - [Cicode] INT BackgroundColor - [C++] OLE_COLOR BackgroundColor Execution Result If the property get/set succeeds, the return value will be Success. If the pane 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 Pane object to be passed into the example methods. [VBA] Sub Example(Pane As Object) Dim backgroundColor As Long ‘Getting Property value backgroundColor = Pane.BackgroundColor ‘Setting Property value to red Pane.BackgroundColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hPane) // Getting property value Chapter: 4 Automation Model 109 INT nColor = _ObjectGetProperty(hPane, "BackgroundColor"); // Setting property value _ObjectSetProperty(hPane, "Name", 255); END IPane.Collection [Property][Get] Returns a reference to the Panes collection that this Pane belongs to. Defined As - [VBA] Object Collection - [Cicode] OBJECT Collection - [C++] IPanes* Collection Execution Result If the property get succeeds the return value will be Success. If the pane is deleted the re- turn value will be GeneralFailure. See Also IPanes Interface Calling Syntax This example assumes there is a valid Pane object to be passed into the example methods. [VBA] Sub Example(pane As Object) Dim panes As Object ‘Getting Property value Set panes = pane.Collection End Sub [Cicode] FUNCTION Example(OBJECT hPane) // Getting property value OBJECT hPanes = _ObjectGetProperty(hPane, "Collection"); END IPane.Delete [Method] Removes this Pane from the collection and the display. Defined As - [VBA] Delete() - [Cicode] Delete() - [C++] HRESULT Delete() Chapter: 4 Automation Model 110 Execution Result If the method succeeds, the return value will be Success. If the pane is already deleted, the return value will be GeneralFailure. 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.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 deleted, the return value will be GeneralFailure. Limits - True (-1): Height is fixed - False (0): Height is variable Remarks When this property is true, the pane’s Height reflects the pixel value size as gotten from the Pane’s 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 Pro- cess 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 Chapter: 4 Automation Model 111 This example assumes there is a valid Pane object to be passed into the example methods. [VBA] Sub Example(pane As Object) Dim fixedHeight As Boolean ‘Getting Property value fixedHeight = pane.FixedHeight ‘Setting Property value pane.FixedHeight = True End Sub [Cicode] FUNCTION Example(OBJECT hPane) // Getting property value INT bFixedHeight = _ObjectGetProperty(hPane, "FixedHeight"); // Setting property value _ObjectSetProperty(hPane, "FixedHeight", -1); 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 deleted, the return value will be GeneralFailure. Remarks This property affects the visible height of the Pane in two different ways based on the Bool- ean 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 ad- justed to fit. If the FixedHeight property is False, the Height property value is used as a ra- tio 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 This example assumes there is a valid Pane object to be passed into the example methods. Chapter: 4 Automation Model 112 [VBA] Sub Example(Pane As Object) Dim height As Long ‘Getting Property value height = Pane.Height ‘Setting Property value Pane.Height = 250 End Sub [Cicode] FUNCTION Example(OBJECT hPane) // Getting property value INT nHeight = _ObjectGetProperty(hPane, "Height"); // Setting property value _ObjectSetProperty(hPane, "Height", 250); END IPane.Name [Property][Get/Set] Gets or Sets the name of this pane. Defined As - [VBA] String Name - [Cicode] 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 collection is deleted, the re- turn value will be GeneralFailure. Limits Name must be between 1-250 characters. Remarks Pane names must be unique. Calling Syntax This example assumes there is a valid Pane object to be passed into the example methods. [VBA] Sub Example(pane As Object) Dim name As String ‘Getting Property value name = pane.Name ‘Setting Property value pane.Name = "Alarms" End Sub Chapter: 4 Automation Model 113 [Cicode] FUNCTION Example(OBJECT hPane) // Getting property value STRING sName = _ObjectGetProperty(hPane, "Name"); // Setting property value _ObjectSetProperty(hPane, "Name", "Alarms"); 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 deleted the re- turn value will be GeneralFailure. See Also IPens Interface Calling Syntax This example assumes there is a valid Pane object to be passed into the example methods. [VBA] Sub Example(pane As Object) Dim pens As Object ‘Getting Property value Set pens = pane.Pens End Sub [Cicode] FUNCTION Example(OBJECT hPane) // Getting property value OBJECT hPens = _ObjectGetProperty(hPane, "Pens"); END Chapter: 4 Automation Model 114 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._NewEnum [Property][Get] This allows For.. Each.. Next integration in VB. Calling Syntax This example assumes there is a valid Panes collection object to be passed into the example methods. This property is not applicable to Cicode. [VBA] Sub Example(Panes As Object) Dim pane As Object Dim count As Long ‘Using Property For Each pane In Panes count = count + 1 Next pane End Sub 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 collection is de- leted, the return value will be GeneralFailure. Calling Syntax Chapter: 4 Automation Model 115 This example assumes there is a valid Panes collection object to be passed into the example methods. [VBA] Sub Example(Panes As Object) Dim count As Long ‘Getting Property value count = Panes.Count End Sub [Cicode] FUNCTION Example(OBJECT hPanes) // Getting property value INT nCount = _ObjectGetProperty(hPanes, "Count"); END 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 deleted, the return val- ue will be GeneralFailure. 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 the example methods. [VBA] Sub Example(Panes As Object) Dim pane As Object Chapter: 4 Automation Model 116 Set pane = Panes.Create("Alarm Pane") End Sub [Cicode] FUNCTION Example(OBJECT hPanes) OBJECT hPane = _ObjectCallMethod(hPanes, "Create", "Alarm Pane"); END IPanes.Item [Property][Get] Gets the Pane at the given index in this Pane collection. Defined As - [VBA] Item(index As Long) as Object - [Cicode] OBJECT Item(INT index) - [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 deleted the return value will be GeneralFailure. See Also IPane Interface Calling Syntax This example assumes there is a valid Panes collection object to be passed into the example methods. [VBA] Sub Example(Panes As Object) Dim pane As Object ‘Getting Property value Set pane = Panes.Item(1) End Sub [Cicode] FUNCTION Example(OBJECT hPanes) // Getting property value OBJECT hPane = _ObjectCallMethod(hPanes, "get_Item", 1); END Chapter: 4 Automation Model 117 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 deleted, the return val- ue will be GeneralFailure. Calling Syntax This example assumes there is a valid Panes collection object to be passed into the example methods. [VBA] Sub Example(Panes As Object) Dim pane As Object ‘Getting Property value Set pane = Panes.ItemByName("Alarm Pane") End Sub [Cicode] FUNCTION Example(OBJECT hPanes) // Getting property value OBJECT hPane = _ObjectCallMethod(hPanes, "get_ItemByName", "Alarm Pane"); END IPanes.RemoveAll [Method] Removes all Panes from this Pane collection. Defined As - [VBA] RemoveAll() - [Cicode] RemoveAll() - [C++] HRESULT RemoveAll() Chapter: 4 Automation Model 118 Execution Result If the method succeeds, the return value will be Success. If the panes collection is deleted, the return value will be GeneralFailure. Calling Syntax This example assumes there is a valid Panes collection object to be passed into the example methods. [VBA] Sub Panes(Buttons As Object) Panes.RemoveAll() End Sub [Cicode] FUNCTION Example(OBJECT hPanes) _ObjectCallMethod(hPanes, "RemoveAll"); 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 Chapter: 4 Automation Model 119 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 Chapter: 4 Automation Model 120 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 In- validArgument. 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) INT iCitectTime; REAL rOleTime; iCitectTime = TimeCurrent(); // Returns seconds since 1970 rOleTime = TimeToOleDate(iCitectTime, 1); // Convert to OLE UTC time _ObjectCallMethod(hPen, "AddSample", 75.0, timeStamp, 100, 0, 0); END Chapter: 4 Automation Model 121 IPen.AxisBackgroundColor [Property][Get/Set] Gets or sets the background color of the axis of this pen. Defined As - [VBA] Long BackgroundColor - [Cicode] INT BackgroundColor - [C++] OLE_COLOR BackgroundColor Execution Result If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is 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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim backgroundColor As Long ‘Getting Property value backgroundColor = pen.AxisBackgroundColor ‘Setting Property value to Red pen.AxisBackgroundColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT backgroundColor; // Getting current property value backgroundColor = _ObjectGetProperty(hPen, "AxisBackgroundColor"); // Setting Property to Red _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 Chapter: 4 Automation Model 122 Execution Result If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. 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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim blockRepaint As Boolean ‘Getting Property value blockRepaint = pen.BlockRepaint ‘Setting Property value pen.BlockRepaint = True End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT bBlockRepaint; // Getting current property value bBlockRepaint = _ObjectGetProperty(hPen, "BlockRepaint"); // Setting Property _ObjectSetProperty(hPen, "BlockRepaint", -1); END IPen.Clear [Method] Clears all samples belonging to this pen from the internal cache. (Note: This does not re- move 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 Assumes you have passed a valid pen object into the function. Chapter: 4 Automation Model 123 [VBA] Sub Example(pen As Object) pen.Clear End Sub [Cicode] FUNCTION Example(OBJECT hPen) _ObjectCallMethod(hPen, "Clear"); END IPen.Collection [Property][Get] Returns a reference to the Pens collection object that this pen belongs to. Defined As - [VBA] Object Collection - [Cicode] OBJECT Collection - [C++] IPen* Collection Execution Result If the property get succeeds the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim pens As Object ‘Getting Property value Set pens = pen.Collection End Sub [Cicode] FUNCTION Example(OBJECT hPen) OBJECT pens; // Getting current property value pens = _ObjectGetProperty(hPen, "Collection"); END IPen.DataPoint [Property][Get/Set] Get or Set the trend/alarm tag which this pen is bound to. Chapter: 4 Automation Model 124 Defined As - [VBA] String DataPoint - [Cicode] STRING DataPoint - [C++] BSTR DataPoint 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. If the tag is greater than 79 characters, the return value will be InvalidArgument. If the pen is deleted, the return value will be Gener- alFailure. 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 tag’s information will also be issued. See Also IPen.DataServer [Property][Get/Set] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim tag As String ‘Getting Property value tag = pen.DataPoint ‘Setting Property value pen.DataPoint = "LOOP_1_PV" End Sub [Cicode] FUNCTION Example(OBJECT hPen) STRING tag; // Getting current property value 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 Chapter: 4 Automation Model 125 - [C++] BSTR DataServer 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. 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 Trends/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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim server As String ‘Getting Property value server = pen.DataServer ‘Setting Property value pen.DataPoint = "localhost" End Sub [Cicode] FUNCTION Example(OBJECT hPen) STRING server; // Getting current property value server = _ObjectGetProperty(hPen, "DataServer"); // Setting Property _ObjectSetProperty(hPen, "DataServer", "localhost"); END IPen.Delete [Method] Deletes the pen from the Process Analyst. Defined As - [VBA] Delete() - [Cicode] Delete() - [C++] HRESULT Delete() Chapter: 4 Automation Model 126 Execution Result If the function succeeds, the return value will be Success. If the pen is already deleted, the return value will be GeneralFailure. 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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) pen.Delete End Sub [Cicode] FUNCTION Example(OBJECT hPen) _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 sec- onds, INT milliseconds) - [C++] HRESULT GetDefaultSpan (short* weeks, short* days, short* hours, short* min- utes, 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. Chapter: 4 Automation Model 127 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 If the function succeeds, the return value will be Success. If an argument is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFail- ure. If any other unexpected error occurs, the return value will be GeneralFailure. See Also IPen.SetDefaultSpan [Method], IPen.ResetToDefaultSpan [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) 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] FUNCTION Example(OBJECT hPen) INT weeks; INT days; INT hours; INT minutes; INT seconds; INT milliseconds; _ObjectCallMethod(hPen, "GetDefaultSpan", weeks, days, hours, minutes, seconds, mil- liseconds); END IPen.GetHorizontalAxisTimeSpan [Method] Returns the start and end time of this pen in local or UTC time format. Defined As Chapter: 4 Automation Model 128 - [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 If the function succeeds, the return value will be Success. If an argument is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFail- ure. If any other unexpected error occurs, the return value will be GeneralFailure. See Also IPen.PutHorizontalAxisTimeSpan [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) 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] FUNCTION Example(OBJECT hPen) REAL startDate; REAL endDate; INT startMs; INT endMs; _ObjectCallMethod(hPen, "GetHorizontalAxisTimeSpan", startDate, startMs, endDate, Chapter: 4 Automation Model 129 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 If the function succeeds, the return value will be Success. If an argument is bad, the return value will be InvalidArgument. If the attribute does not exist, the return value will be In- validArgument. If the pen is deleted, the return value will be GeneralFailure. If any other unexpected error occurs, the return value will be GeneralFailure. Information Attributes At t r i but e Ret ur ns Appl i es t o Alarm Area Alarm t ag field Alarm Alarm Cat egory Alarm t ag field Alarm Alarm Desc Alarm t ag field Alarm Alarm Name Alarm t ag field Alarm Alarm Type Alarm t ag field Alarm Comment Alarm/ Trend t ag comment field All Durat ion Process Analyst t ime span All End Time Process Analyst axis end t ime All Engineering Full Scale Trend t ag field Analog, Digit al Engineering Unit s Trend t ag field Analog, Digit al Engineering Zero Scale Trend t ag field Analog, Digit al Error Process Analyst error st at us All Full Scale Process Analyst vert ical axis max scale Analog, Name Process Analyst pen name All Raw Full Scale Trend t ag field Analog, Digit al Raw Zero Scale Trend t ag field Analog, Digit al Sample Period Trend t ag field Analog, Digit al St art Time Process Analyst axis st art t ime All Chapter: 4 Automation Model 130 Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim duration As String duration = pen.GetInformation "Duration" End Sub [Cicode] FUNCTION Example(OBJECT hPen) 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 sup- ported attributes. value [out] Indicates the value of the specified statistic attribute. Execution Result If the function succeeds, the return value will be Success. If an argument is bad, the return value will be InvalidArgument. If the attribute does not exist, the return value will be In- validArgument. If the pen is deleted, the return value will be GeneralFailure. If any other unexpected error occurs, the return value will be GeneralFailure. Tag Process Analyst source binding field All Trend Type Trend t ag field Analog, Digit al Zero Scale Process Analyst vert ical axis min scale Analog Scale Process Analyst vert ical axis scale range Analog, Digit al Engineering Scale Engineering scale range Analog, Digit a Chapter: 4 Automation Model 131 Information Attributes Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim average As String pen.GetStatistic "Average", average End Sub [Cicode] FUNCTION Example(OBJECT hPen) STRING average; _ObjectCallMethod(hPen, "GetStastic", "Average", average); END IPen.GetVerticalAxisSpan [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 If the function succeeds, the return value will be Success. If an argument is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFail- ure. If any other unexpected error occurs, the return value will be GeneralFailure. See Also IPen.PutVerticalAxisSpan [Method] Calling Syntax At t r i but e Ret ur ns Appl i es t o Average Process Analyst real- t ime average Analog, Digit al Maximum Process Analyst real- t ime maximum Analog Minimum Process Analyst real- t ime minimum Analog Chapter: 4 Automation Model 132 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim startValue As Double Dim endValue As Double pen.GetVerticalAxisSpan startValue, endValue End Sub [Cicode] FUNCTION Example(OBJECT hPen) REAL startValue; REAL endValue; _ObjectCallMethod(hPen, "GetVerticalAxisSpan", startValue, endValue); END IPen.GoToNow [Method] Synchronizes the end time of the pen’s span with your computer’s current local time. The start time will also be moved to maintain the pen’s 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, the return value will be GeneralFailure. Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) pen.GoToNow End Sub [Cicode] FUNCTION Example(OBJECT hPen) _ObjectCallMethod(hPen, "GoToNow"); END Chapter: 4 Automation Model 133 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 If the property get/set succeeds, the return value will be Success. If the return 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, the return value will be Gener- alFailure. Remarks This property is ignored when the pen is not in Stacked mode. See Also IPen.Stacked [Property][Get/Set] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim height As Boolean ‘Getting Property value height = pen.Height ‘Setting Property value pen.Height = 75 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT height; // Getting current property value height = _ObjectGetProperty(hPen, "Height"); // Setting Property _ObjectSetProperty(hPen, "Height", 75); END IPen.HorizontalAxisColor [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 Chapter: 4 Automation Model 134 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. If the pen is deleted, the return value will be GeneralFailure. Remarks 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. See Also IPen.VerticalAxisColor [Property][Get/Set] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim color As Long ‘Getting Property value color = pen.HorizontalAxisColor ‘Setting Property value to Red pen.HorizontalAxisColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT color; // Getting current property value color = _ObjectGetProperty(hPen, "HorizontalAxisColor"); // Setting Property to Red _ObjectSetProperty(hPen, "HorizontalAxisColor", PackedRGB(255, 0, 0)); END IPen.HorizontalAxisResize [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 Chapter: 4 Automation Model 135 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Limits - True (-1): Axis can be resized - False (0): Axis cannot be resized See Also IPen.VerticalAxisResize [Property][Get/Set] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim resize As Boolean ‘Getting Property value resize = pen.HorizontalAxisResize ‘Setting Property value pen.HorizontalAxisResize = False End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT bResize; // Getting current property value bResize = _ObjectGetProperty(hPen, "HorizontalAxisResize"); // Setting Property _ObjectSetProperty(hPen, "HorizontalAxisResize",0); END IPen.HorizontalAxisScroll [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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. Limits - True (-1): Axis can be scrolled Chapter: 4 Automation Model 136 - False (0): Axis cannot be scrolled See Also IPen.VerticalAxisScroll [Property][Get/Set] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim scroll As Boolean ‘Getting Property value scroll = pen.HorizontalAxisScroll ‘Setting Property value pen.HorizontalAxisScroll = False End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT bScroll; // Getting current property value bScroll = _ObjectGetProperty(hPen, "HorizontalAxisScroll"); // Setting Property _ObjectSetProperty(hPen, "HorizontalAxisScroll", 0); END IPen.HorizontalAxisWidth [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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Limits A valid width is 0-8 pixels. See Also IPen.VerticalAxisWidth [Property][Get/Set] Calling Syntax Assumes you have passed a valid pen object into the function. Chapter: 4 Automation Model 137 [VBA] Sub Example(pen As Object) Dim width As Integer ‘Getting Property value width = pen.HorizontalAxisWidth ‘Setting Property value pen.HorizontalAxisWidth = 3 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT width; // Getting current property value width = _ObjectGetProperty(hPen, "HorizontalAxisWidth"); // Setting Property _ObjectSetProperty(hPen, "HorizontalAxisWidth", 3); END IPen.HorizontalGridlinesColor [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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Limits A valid width is 0-8 pixels. Remarks 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 See Also IPen.HorizontalMinorGridlinesColor [Property][Get/Set] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim color As Long Chapter: 4 Automation Model 138 ‘Getting Property value color = pen.HorizontalGridlinesColor ‘Setting Property value to Red pen.HorizontalGridlinesColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT color; // Getting current property value color = _ObjectGetProperty(hPen, "HorizontalGridlinesColor"); // Setting Property to Red _ObjectSetProperty(hPen, "HorizontalGridlinesColor", PackedRGB(255, 0, 0)); END IPen.HorizontalGridlinesStyle [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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the style is out of range, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. See Also IPen.HorizontalMinorGridlinesColor [Property][Get/Set], LineStyle [Enumeration] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim style As Long ‘Getting Property value style = pen.HorizontalGridlinesStyle ‘Setting Property value to Dot pen.HorizontalGridlinesColor = 2 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT style; // Getting current property value Chapter: 4 Automation Model 139 style = _ObjectGetProperty(hPen, "HorizontalGridlinesStyle"); // Setting Property to Dot _ObjectSetProperty(hPen, "HorizontalGridlinesStyle", 2); END IPen.HorizontalGridlinesWidth [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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the width is out of range, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim width As Integer ‘Getting Property value width = pen.HorizontalGridlinesWidth ‘Setting Property value pen.HorizontalGridlinesWidth = 3 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT width; // Getting current property value width = _ObjectGetProperty(hPen, "HorizontalGridlinesWidth"); // Setting Property t _ObjectSetProperty(hPen, "HorizontalGridlinesWidth", 3); END IPen.HorizontalMinorGridlinesColor [Property][Get/Set] Gets or sets the color used to draw the minor horizontal gridlines. Defined As - [VBA] Long HorizontalMinorGridlinesColor - [Cicode] INT HorizontalMinorGridlinesColor Chapter: 4 Automation Model 140 - [C++] OLE_COLOR HorizontalMinorGridlinesColor 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. If the pen is deleted, the return value will be GeneralFailure. Remarks 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. See Also IPen.HorizontalGridlinesColor [Property][Get/Set] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim color As Long ‘Getting Property value color = pen.HorizontalMinorGridlinesColor ‘Setting Property value to Red pen.HorizontalMinorGridlinesColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT color; // Getting current property value color = _ObjectGetProperty(hPen, "HorizontalMinorGridlinesColor"); // Setting Property to Red _ObjectSetProperty(hPen, "HorizontalMinorGridlinesColor", PackedRGB(255, 0, 0)); END IPen.HorizontalMinorGridlinesStyle [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 Chapter: 4 Automation Model 141 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the style is out of range, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. See Also IPen.HorizontalGridlinesStyle [Property][Get/Set], LineStyle [Enumeration] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim style As Long ‘Getting Property value style = pen.HorizontalMinorGridlinesStyle ‘Setting Property value to Dot pen.HorizontalMinorGridlinesColor = 2 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT style; // Getting current property value style = _ObjectGetProperty(hPen, "HorizontalMinorGridlinesStyle"); // Setting Property to Dot _ObjectSetProperty(hPen, "HorizontalMinorGridlinesStyle", 2); 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, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFail- ure. Chapter: 4 Automation Model 142 See Also IPen.VerticalScrollBy [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) ‘ Move the pen span back one complete span into history pen.HorizontalScrollBy -1.0 End Sub [Cicode] FUNCTION Example(OBJECT hPen) // 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 return value will be GeneralFailure. See Also IPen.VerticalZoom [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) ‘ Zoom out 50% pen.HorizontalZoom 0.5 Chapter: 4 Automation Model 143 ‘ Undo the Zoom pen.HorizontalZoom 1.5 End Sub [Cicode] FUNCTION Example(OBJECT hPen) // Zoom out 50% _ObjectCallMethod(hPen, "HorizontalZoom", 0.5); // Undo the Zoom _ObjectCallMethod(hPen, "HorizontalZoom", 2.0); 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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. See Also IPen.Delete [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim deleted As Boolean deleted = pen.IsDeleted End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT bDeleted; bDeleted = _ObjectGetProperty(hPen, "IsDeleted"); END Chapter: 4 Automation Model 144 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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. See Also IPen.Select [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim selected As Boolean selected = pen.IsSelected End Sub [Cicode] FUNCTION Example(OBJECT hPen) 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 If the property get/set succeeds the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Limits - True (-1): Local format - False (0): UTC format Chapter: 4 Automation Model 145 Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim localTime As Boolean ‘Getting Property value localTime = pen.LocalTime ‘Display time in UTC pen.LocalTime = False End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT bLocalTime; // Getting current property value 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 - [Cicode] STRING Name - [C++] BSTR Name 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. If the length of the name is wrong then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. Remarks The Process Analyst will use this name extensively throughout the user interface to refer- ence 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 Assumes you have passed a valid pen object into the function. Chapter: 4 Automation Model 146 [VBA] Sub Example(pen As Object) Dim name As String ‘Getting Property value name = pen.Name ‘Setting property value pen.Name = "NicePen" End Sub [Cicode] FUNCTION Example(OBJECT hPen) STRING name; // Getting current property value name = _ObjectGetProperty(hPen, "Name"); // Setting property value _ObjectSetProperty(hPen, "Name", "NicePen"); 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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. 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 Set- QualityCompactionPointType function will be hidden. See Also IPen.SetQualityCompactionPointType [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim visible As Boolean Chapter: 4 Automation Model 147 ‘Getting Property value visible = pen.PointsVisible ‘Setting Property value pen.PointsVisible = True End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT visible; // Getting current property value visible = _ObjectGetProperty(hPen, "PointsVisible"); // Setting Property value _ObjectSetProperty(hPen, "PointsVisible", -1); END IPen.PutHorizontalAxisTimeSpan [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 re- turn value will be InvalidArgument. If an argument is out of range then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. If any other unexpected error occurs the return value will be GeneralFailure. Remarks Chapter: 4 Automation Model 148 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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) 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] FUNCTION Example(OBJECT hPen) 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.PutVerticalAxisSpan [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 Chapter: 4 Automation Model 149 [in] Indicates the new lower bound of the vertical axis. endValue [in] Indicates the new upper bound of the vertical axis. 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, or the span is out of range, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Limits The vertical axis has a upper limit of 1+e10 and a lower limit of 1-e10. However, the maxi- mum span supported is 1+e10. The minimum span is 0.00001. See Also IPen.GetVerticalAxisSpan [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) pen.PutVerticalAxisSpan 200.5, 300.34 End Sub [Cicode] FUNCTION Example(OBJECT hPen) _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 re- quest 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 Assumes you have passed a valid pen object into the function. Chapter: 4 Automation Model 150 [VBA] Sub Example(pen As Object) pen.RefreshData End Sub [Cicode] FUNCTION Example(OBJECT hPen) _ObjectCallMethod(hPen, "RefreshData"); 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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the mode is out of range, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. 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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim requestMode As Integer ‘Getting Property value requestMode = pen.RequestMode ‘Setting mode to minimum pen.RequestMode = 1 End Sub Chapter: 4 Automation Model 151 [Cicode] FUNCTION Example(OBJECT hPen) INT requestMode; // Getting current property value requestMode = _ObjectGetProperty(hPen, "RequestMode"); // Setting mode to minimum _ObjectSetProperty(hPen, "RequestMode", 1); END IPen.ResetToDefaultSpan [Method] Resets the span of this pen to its default span. Defined As - [VBA] ResetToDefaultSpan() - [Cicode] ResetToDefaultSpan() - [C++] HRESULT ResetToDefaultSpan() Execution Result If the function succeeds, the return value will be Success. If the pen is deleted, the return value will be GeneralFailure. Remarks The default span of all pens is 10 minutes. This can be modified by using IPen.SetDefault- Span. See Also IPen.GetDefaultSpan [Method], IPen.SetDefaultSpan [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) pen.ResetToDefaultSpan End Sub [Cicode] FUNCTION Example(OBJECT hPen) _ObjectCallMethod(hPen, "ResetToDefaultSpan"); END IPen.Select [Method] Makes this pen the primary selected pen. Chapter: 4 Automation Model 152 Defined As - [VBA] Select() - [Cicode] Select() - [C++] HRESULT Select() Execution Result If the function succeeds, the return value will be Success. If the pen is deleted, the return value will be GeneralFailure. Remarks Calling this method will also trigger PenSelectionChanged [Event]. Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) pen.Select End Sub [Cicode] FUNCTION Example(OBJECT hPen) _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 sec- onds, 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 Chapter: 4 Automation Model 153 [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 If the function succeeds the return value will be Success. If an argument is bad then the re- turn value will be InvalidArgument. If the pen is deleted then the return value will be Gen- eralFailure. See Also IPen.GetDefaultSpan [Method], IPen.ResetToDefaultSpan [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) ‘ Set span to 2 hours and 30 minutes pen.GetDefaultSpan 0, 0, 2, 30, 0, 0 End Sub [Cicode] FUNCTION Example(OBJECT hPen) // Set span to 2 hours and 30 minutes _ObjectCallMethod(hPen, "SetDefaultSpan", 0, 0, 2, 30, 0, 0); END IPen.SetQualityCompactionPointType [Method] Use this function to indicate what visual cue to display for single and multiple samples. Defined As - [VBA] SetQualityCompactionPointType(compactionType As Integer, pointType As In- teger) - [Cicode] SetQualityCompactionPointType(INT compactionType, INT pointType) - [C++] HRESULT SetQualityCompactionPointType(QualityCompactionType compac- tionType, 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. Chapter: 4 Automation Model 154 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 In- validArgument. If the pen is deleted, the return value will be GeneralFailure. See Also QualityCompactionType [Enumeration], PointType [Enumeration] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) ‘ Set single samples to lsook like triangles pen.SetQualityCompactionPointType 0, 5 End Sub [Cicode] FUNCTION Example(OBJECT hPen) // Set single samples to look like triangles _ObjectCallMethod(hPen, "SetQualityCompactionPointType", 0, 5); END IPen.SetQualityLineStyle [Method] This function can be used to change the type of line drawn for each of the quality states de- fined 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 If the function succeeds the return value will be Success. If an argument is bad then the re- turn value will be InvalidArgument. If an argument is out of range then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. Remarks Chapter: 4 Automation Model 155 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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) ‘ Set all lines drawn after NA samples to be drawn as dash_dot pen.SetQualityLineStyle 1, 3 End Sub [Cicode] FUNCTION Example(OBJECT hPen) // Set all lines drawn after NA samples to be drawn as dash_dot _ObjectCallMethod(hPen, "SetQualityLineStyle", 1, 3); END IPen.SetVerticalAxisLabelValue [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 If the function succeeds the return value will be Success. If an argument is bad then the re- turn value will be InvalidArgument. If the pen is deleted then the return value will be Gen- eralFailure. Calling Syntax Assumes you have passed a valid pen object into the function. Chapter: 4 Automation Model 156 [VBA] Sub Example(pen As Object) ‘ Change the vertical axis to display High High instead of 95 pen.SetVerticalAxisLabelValue 95, "High High" End Sub [Cicode] FUNCTION Example(OBJECT hPen) // Change the vertical axis to display High High instead of 95 _ObjectCallMethod(hPen, "SetVerticalAxisLabelValue", 95, "High High"); 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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. 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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim stacked As Boolean ‘Getting Property value stacked = pen.Stacked ‘Setting Property value pen.Stacked = True End Sub Chapter: 4 Automation Model 157 [Cicode] FUNCTION Example(OBJECT hPen) INT bStacked; // Getting current property value bStacked = _ObjectGetProperty(hPen, "Stacked"); // Setting property value _ObjectSetProperty(hPen, "Stacked", -1); END IPen.TrendCursorLabelFillColor [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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. Remarks 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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim color As Long ‘Getting Property value color = pen.TrendCursorLabelFillColor ‘Setting Property value to Red pen.TrendCursorLabelFillColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT color; // Getting current property value color = _ObjectGetProperty(hPen, "TrendCursorLabelFillColor"); // Setting Property to Red _ObjectSetProperty(hPen, "TrendCursorLabelFillColor", PackedRGB(255, 0, 0)); END Chapter: 4 Automation Model 158 IPen.TrendCursorLabelLineColor [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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. Remarks 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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim color As Long ‘Getting Property value color = pen.TrendCursorLabelLineColor ‘Setting Property value to Red pen.TrendCursorLabelLineColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT color; // Getting current property value color = _ObjectGetProperty(hPen, "TrendCursorLabelLineColor"); // Setting Property to Red _ObjectSetProperty(hPen, "TrendCursorLabelLineColor", PackedRGB(255, 0, 0)); END IPen.TrendCursorLabelTextColor [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 Chapter: 4 Automation Model 159 Execution Result If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. Remarks 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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim color As Long ‘Getting Property value color = pen.TrendCursorLabelTextColor ‘Setting Property value to Red pen.TrendCursorLabelTextColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT color; // Getting current property value color = _ObjectGetProperty(hPen, "TrendCursorLabelTextColor"); // Setting Property to Red _ObjectSetProperty(hPen, "TrendCursorLabelTextColor", PackedRGB(255, 0, 0)); END IPen.VerticalAxisAutoscale [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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. Remarks Setting this property will turn off interactive Scrolling (IPen.HorizontalAxisScroll) and Scaling (IPen.HorizontalAxisResize). Chapter: 4 Automation Model 160 Limits - True (-1): Autoscale enabled - False (0): Autoscale disabled Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim autoScale As Long ‘Getting Property value autoScale = pen.VerticalAxisAutoscale ‘Setting Property value pen.VerticalAxisAutoscale = True End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT autoScale; // Getting current property value 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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. Remarks 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. See Also IPen.HorizontalAxisColor [Property][Get/Set] Calling Syntax Chapter: 4 Automation Model 161 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim color As Long ‘Getting Property value color = pen.VerticalAxisColor ‘Setting Property value to Red pen.VerticalAxisColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT color; // Getting current property value color = _ObjectGetProperty(hPen, "VerticalAxisColor"); // Setting Property to Red _ObjectSetProperty(hPen, "VerticalAxisColor", PackedRGB(255, 0, 0)); END IPen.VerticalAxisLabelType [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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. Remarks Label Types are fixed and cannot be added to. See Also AxisLabelType [Enumeration] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim labelType As Integer Chapter: 4 Automation Model 162 ‘Getting Property value labelType = pen.VerticalAxisLabelType ‘Setting Property value to Percent pen.VerticalAxisLabelType= 3 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT labelType; // Getting current property value 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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. 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 Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim resize As Boolean ‘Getting Property value resize = pen.VerticalAxisResize ‘Setting Property value pen.VerticalAxisResize = False Chapter: 4 Automation Model 163 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT bResize; // Getting current property value 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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Limits - True (-1): Enable scrolling - False (0): Disable scrolling Remarks This only applies to analog pens. See Also IPen.HorizontalAxisScroll [Property][Get/Set] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim scroll As Boolean ‘Getting Property value scroll = pen.VerticalAxisScroll ‘Setting Property value pen.VerticalAxisScroll = False End Sub Chapter: 4 Automation Model 164 [Cicode] FUNCTION Example(OBJECT hPen) INT bScroll; // Getting current property value 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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Limits A valid width is 0-8 pixels. Remarks This only applies to analog pens. See Also IPen.HorizontalAxisWidth [Property][Get/Set] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim width As Integer ‘Getting Property value width = pen.VerticalAxisWidth ‘Setting Property value pen.VerticalAxisWidth = 3 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT width; // Getting current property value Chapter: 4 Automation Model 165 width = _ObjectGetProperty(hPen, "VerticalAxisWidth"); // Setting Property _ObjectSetProperty(hPen, "VerticalAxisWidth", 3); END IPen.VerticalGridlinesColor [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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Remarks 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. See Also IPen.VerticalMinorGridlinesColor [Property][Get/Set] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim color As Long ‘Getting Property value color = pen.VerticalGridlinesColor ‘Setting Property value to Red pen.VerticalGridlinesColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT color; // Getting current property value color = _ObjectGetProperty(hPen, "VerticalGridlinesColor"); // Setting Property to Red _ObjectSetProperty(hPen, "VerticalGridlinesColor", PackedRGB(255, 0, 0)); END Chapter: 4 Automation Model 166 IPen.VerticalGridlinesStyle [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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the style is out of range, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. See Also IPen.VerticalMinorGridlinesStyle [Property][Get/Set], LineStyle [Enumeration] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim style As Long ‘Getting Property value style = pen.VerticalGridlinesColor ‘Setting Property value to Dot pen.VerticalGridlinesColor = 2 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT style; // Getting current property value style = _ObjectGetProperty(hPen, "VerticalGridlinesStyle"); // Setting Property to Dot _ObjectSetProperty(hPen, "VerticalGridlinesStyle", 2); END IPen.VerticalGridlinesWidth [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 Chapter: 4 Automation Model 167 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the width is out of range, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Limits A valid width is 0-8 pixels. Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim width As Integer ‘Getting Property value width = pen.VerticalGridlinesWidth ‘Setting Property value pen.VerticalGridlinesWidth = 3 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT width; // Getting current property value width = _ObjectGetProperty(hPen, "VerticalGridlinesWidth"); // Setting Property t _ObjectSetProperty(hPen, "VerticalGridlinesWidth", 3); END IPen.VerticalMinorGridlinesColor [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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Remarks 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. See Also IPen.VerticalGridlinesColor [Property][Get/Set] Chapter: 4 Automation Model 168 Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim color As Long ‘Getting Property value color = pen.VerticalMinorGridlinesColor ‘Setting Property value to Red pen.VerticalMinorGridlinesColor = 255 End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT color; // Getting current property value color = _ObjectGetProperty(hPen, "VerticalMinorGridlinesColor"); // Setting Property to Red _ObjectSetProperty(hPen, "VerticalMinorGridlinesColor", PackedRGB(255, 0, 0)); END IPen.VerticalMinorGridlinesStyle [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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the style is out of range, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. See Also IPen.VerticalGridlinesStyle [Property][Get/Set], LineStyle [Enumeration] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim style As Long ‘Getting Property value style = pen.VerticalMinorGridlinesStyle ‘Setting Property value to Dot pen.VerticalMinorGridlinesColor = 2 End Sub Chapter: 4 Automation Model 169 [Cicode] FUNCTION Example(OBJECT hPen) INT style; // Getting current property value style = _ObjectGetProperty(hPen, "VerticalMinorGridlinesStyle"); // Setting Property to Dot _ObjectSetProperty(hPen, "VerticalMinorGridlinesStyle", 2); 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 If the function succeeds the return value will be Success. If the argument is bad then the return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure. See Also IPen.HorizontalScrollBy [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) ‘ Move the pen span forward one complete span pen.VerticalScrollBy 1.0 End Sub Chapter: 4 Automation Model 170 [Cicode] FUNCTION Example(OBJECT hPen) // 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 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 return value will be GeneralFailure. See Also IPen.HorizontalZoom [Method] Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) ‘ Zoom out 50% pen.VerticalZoom 0.5 ‘ Undo the Zoom pen.VerticalZoom 1.5 End Sub [Cicode] FUNCTION Example(OBJECT hPen) // Zoom out 50% _ObjectCallMethod(hPen, "VerticalZoom", 0.5); // Undo the Zoom _ObjectCallMethod(hPen, "VerticalZoom", 2.0); END Chapter: 4 Automation Model 171 IPen.Visible [Property][Get/Set] Get or set whether this pen will be visually shown (True) or hidden (False) to the operator. Defined As - [VBA] Boolean Visible - [Cicode] INT Visible - [C++] VARIANT_BOOL Visible Execution Result If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. Limits - True (-1): Visible - False (0): Hidden Calling Syntax Assumes you have passed a valid pen object into the function. [VBA] Sub Example(pen As Object) Dim visible As Boolean ‘Get the property value visible = pen.Visible ‘ Set the property value pen.Visible = False End Sub [Cicode] FUNCTION Example(OBJECT hPen) INT bVisible; // Get the property value bVisible = _ObjectGetProperty(hPen, "Visible", 0.5); // Set the property value _ObjectSetProperty(hPen, "Visible", 0); END IPens Interface Defined As - [VBA] Object - [Cicode] OBJECT - [C++] IPens Methods (2) Chapter: 4 Automation Model 172 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._NewEnum [Property][Get] This allows For.. Each.. Next integration in VB. Calling Syntax This example assumes there is a valid Pens collection object to be passed into the example methods. This property is not applicable to Cicode. [VBA] Sub Example(Pens As Object) Dim pen As Object Dim count As Long ‘Using Property For Each pen In Pens count = count + 1 Next pen End Sub 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 collection is delet- ed, 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 Example(Pens As Object) Dim count As Long ‘Getting Property value Chapter: 4 Automation Model 173 count = Pens.Count End Sub [Cicode] FUNCTION Example(OBJECT hPens) // Getting property value INT nCount = _ObjectGetProperty(hPens, "Count"); END 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 proper- ty. 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 IP- en.Name property. Execution Results If the method succeeds the return value will be Success. If the pens collection is deleted, the return value will be GeneralFailure. 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 Chapter: 4 Automation Model 174 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.Item [Property][Get] Gets the Pen at the given index from this pen’s collection. Defined As - [VBA] Item(index As Long) as Object - [Cicode] OBJECT Item(INT index) - [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 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 pen’s 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 Example(pens As Object) Dim pen As Object ‘Getting Property value Set pen = pens.Item(1) End Sub Chapter: 4 Automation Model 175 [Cicode] FUNCTION Example(OBJECT hPens) // Getting property value OBJECT hPen = _ObjectCallMethod(hPens, "get_Item", 1); END 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, 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 Example(Pens As Object) Dim pen As Object ‘Getting Property value Set pen = Pens.ItemByName("CPU Usage") End Sub [Cicode] FUNCTION Example(OBJECT hPens) // Getting property value OBJECT hPen = _ObjectCallMethod(hPens, "get_ItemByName", "CPU Usage"); END IPens.Pane[Property][Get] Gets the Pane that this Pens collection belongs to. Chapter: 4 Automation Model 176 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 This example assumes there is a valid Pens collection object to be passed into the example methods. [VBA] Sub Example(pens As Object) Dim pane As Object ‘Getting Property value Set pane = pens.Pane End Sub [Cicode] FUNCTION Example(OBJECT hPens) // Getting property value OBJECT hPane = _ObjectGetProperty(hPens, "Pane"); END IPens.RemoveAll [Method] Removes all Pens from the Pens collection. Defined As - [VBA] RemoveAll() - [Cicode] RemoveAll() - [C++] HRESULT RemoveAll() Execution Result If the property get/set succeeds the return value will be Success. If the pens collection is de- leted 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. Chapter: 4 Automation Model 177 [VBA] Sub Panes(pens As Object) pens.RemoveAll() End Sub [Cicode] FUNCTION Example(OBJECT hPens) _ObjectCallMethod(hPens, "RemoveAll"); END 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.NumberofSamples[Property][Get/Set] IProcessAnalyst.ObjectView [Property][Get] IProcessAnalyst.Panes [Property][Get] Chapter: 4 Automation Model 178 IProcessAnalyst.PrimaryPath [Property][Get/Set] IProcessAnalyst.SecondaryPath [Property][Get/Set] IProcessAnalyst.Toolbars [Property][Get] IProcessAnalyst.WritePrivilegeLevel [Property][Get] IProcessAnalyst.ZoomMode [Property][Get/Set] IProcessAnalyst.BlockUpdates [Method] Blocks certain aspects of the Process Analyst’s 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 un- block 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 val- ue 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.UnBlockUpdates [Method] Unblocks certain aspects of the Process Analyst’s redrawing and data updating. Defined As - [VBA] UnblockUpdates() - [Cicode] UnblockUpdates() Chapter: 4 Automation Model 179 - [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 un- block 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 val- ue 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 This example assumes there is a valid Process Analyst object to be passed into the example methods. [VBA] Sub Example(ProcessAnalyst As Object) ProcessAnalyst.UnblockUpdates() End Sub [Cicode] FUNCTION Example(OBJECT hProcessAnalyst) _ObjectCallMethod(hProcessAnalyst, "UnblockUpdates"); END IProcessAnalyst.CopyToClipboard [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 val- ue will be GeneralFailure. See Also IProcessAnalyst.CopyToFile [Method] Chapter: 4 Automation Model 180 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.CopyToFile [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 return val- ue will be GeneralFailure. 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 Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() myPage_AN35.CopyToFile "test.xls" End Sub Chapter: 4 Automation Model 181 [Cicode] Sub Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); _ObjectCallMethod(hProcessAnalyst, "CopyToFile", "test.xls"); End Sub IProcessAnalyst.FreezeEvent [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 val- ue 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 par- ticularly useful to prevent recursive behavior of functions that generate the same event that you are trying to handle. Calling Syntax This example assumes there is a valid Process Analyst object to be passed into the example methods. [VBA] Sub Example(analyst As Object) analyst.FreezeEvent "HorizontalAxisChanged" True End Sub [Cicode] FUNCTION Example(OBJECT hAnalyst) _ObjectCallMethod(hAnalyst, "FreezeEvent","HorizontalAxisChanged", -1); END Chapter: 4 Automation Model 182 IProcessAnalyst.LoadFromFile [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 verify 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], IProces- sAnalyst.SecondaryPath [Property][Get/Set] Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() ‘ Load the view from the server myPage_AN35.LoadFromFile "Analyst Views\Test1.pav", 1 End Sub Chapter: 4 Automation Model 183 [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); _ObjectCallMethod(hProcessAnalyst, "LoadFromFile","AnalystViews\Test1.pav", 1); END IProcessAnalyst.PrintAll [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 Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() myPage_AN35.PrintAll End Sub [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); _ObjectCallMethod(hProcessAnalyst, "PrintAll"); END IProcessAnalyst.SaveToFile [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 Chapter: 4 Automation Model 184 [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 Sec- ondaryPath 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], IProces- sAnalyst.SecondaryPath [Property][Get/Set], IProcessAnalyst.WritePrivilegeLevel [Prop- erty][Get] Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been 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() OBJECT hProcessAnalyst = ObjectByName("AN35"); ‘ Save the view to the server and project _ObjectCallMethod(hProcessAnalyst, "SaveToFile", "Analyst Views\Test1.pav", 1); END IProcessAnalyst.ShowProperties [Method] Displays the Process Analyst’s property configuration dialog. Chapter: 4 Automation Model 185 Define As - [VBA] ShowProperties - [Cicode] ShowProperties() - [C++] HRESULT ShowProperties () Execution Result If the function succeeds the return value will be Success. If an unexpected error occurs then the return value will be GeneralFailure. Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() myPage_AN35.ShowProperties End Sub [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); _ObjectCallMethod(hProcessAnalyst, "ShowProperties"); END IProcessAnalyst.SubscribeForPropertyChange [Method] Use this method to receive notifications of when a particular property changes. Notifica- tions will be sent via the PropertyChanged event. Defined As - [VBA] SubscribeForPropertyChange(interfaceName As String, propertyName As String) - [Cicode] SubscribeForPropertyChange(STRING interfaceName, STRING proper- tyName) - [C++] HRESULT SubscribeForPropertyChange(BSTR interfaceName, BSTR proper- tyName) Parameters interfaceName [in] Specify the name of the interface that the property you want notifications for is de- fined on. propertyName [in] This is the name of the property you want to receive notifications for. Execution Result Chapter: 4 Automation Model 186 If the function succeeds, the return value will be Success. If the interfaceName or proper- tyName is a bad string, the return value will be InvalidArgument. If any other problem oc- curs, the return value will be GeneralFailure. Remarks The following set of properties are supported: See Also IProcessAnalyst.UnsubscribePropertyChange [Method], PropertyChanged [Event] Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() myPage_AN35.SubscribeForPropertyChange "IProcessAnalyst", "ZoomMode" End Sub [Cicode] Sub Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); _ObjectCallMethod(hProcessAnalyst,"SubscribeForPropertyChange", "IProcessAnalyst", "ZoomMode"); End Sub IProcessAnalyst.SynchroniseToNow [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. I nt er f ace name Pr oper t y Name I ProcessAnalyst Aut oScroll I ProcessAnalyst BackgroundColor I ProcessAnalyst Cont ext Menu I ProcessAnalyst LockedPens I ProcessAnalyst DisplayRefreshRat e I ProcessAnalyst Dat aRequest Rat e I ProcessAnalyst ZoomMode Chapter: 4 Automation Model 187 Remarks The current span for each pen will be maintained. ‘Now' is defined as the current time on the client machine. Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() myPage_AN35.SynchroniseToNow End Sub [Cicode] Sub Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); _ObjectCallMethod(hProcessAnalyst, "SynchroniseToNow"); End Sub IProcessAnalyst.UnsubscribePropertyChange [Method] Use this method to cancel notifications of when the specified property changes. Notifica- tions will cease to be sent via the PropertyChanged event. Defined As - [VBA] UnsubscribePropertyChange(interfaceName As String, propertyName As String) - [Cicode] UnsubscribePropertyChange(STRING interfaceName, STRING proper- tyName) - [C++] HRESULT UnsubscribePropertyChange(BSTR interfaceName, BSTR proper- tyName) 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 proper- tyName is a bad string, the return value will be InvalidArgument. If any other problem oc- curs, the return value will be GeneralFailure. See Also IProcessAnalyst.SubscribeForPropertyChange [Method], PropertyChanged [Event] Chapter: 4 Automation Model 188 Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() myPage_AN35.UnsubscribePropertyChange "IProcessAnalyst","ZoomMode" End Sub [Cicode] Sub Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); _ObjectCallMethod(hProcessAnalyst, "UnsubscribePropertyChange","IProcessAnalyst", "ZoomMode"); End Sub IProcessAnalyst.AdminPrivilegeLevel [Property] [Get] Retrieves the privilege level currently set for controlling administration features of the Pro- cess 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 Da- taRequestRate and DisplayRefreshRate. Limits Privilege level defined in CitectSCADA 1 - 8. 0 = no security. Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". Chapter: 4 Automation Model 189 [VBA] Sub Example() Dim privilege As Boolean ‘Getting Property value privilege = myPage_AN35.AdminPrivilegeLevel End Sub [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); INT privilege; // Getting current property value privilege = _ObjectGetProperty(hProcessAnalyst,"AdminPrivilegeLevel"); END IProcessAnalyst.AutoScroll [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 Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() Dim autoScroll As Boolean ‘Getting Property value autoScroll = myPage_AN35.AutoScroll ‘Setting Property value myPage_AN35.AutoScroll = True End Sub Chapter: 4 Automation Model 190 [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); INT autoScroll; // Getting current property value autoScroll = _ObjectGetProperty(hProcessAnalyst, "AutoScroll"); // Setting Property to true _ObjectSetProperty(hProcessAnalyst, "AutoScroll", -1); END IProcessAnalyst.BackgroundColor [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 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 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 Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() Dim backgroundColor As Long ‘Getting Property value backgroundColor = myPage_AN35.BackgroundColor ‘Setting Property value to Red myPage_AN35.BackgroundColor = 255 End Sub Chapter: 4 Automation Model 191 [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); INT backgroundColor; // Getting current property value backgroundColor = _ObjectGetProperty(hProcessAnalyst,"BackgroundColor"); // Setting Property to Red _ObjectSetProperty(hProcessAnalyst, "BackgroundColor", 255); END IProcessAnalyst.CommandSystem [Property][Get] Gets a reference to the Process Analyst’s 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 If the property get succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() Dim commandSystem As Object ‘Retrieve command system Set commandSystem = myPage_AN35.CommandSystem End Sub [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); OBJECT hCommandSystem; // Retrieve command system hCommandSystem = _ObjectGetProperty(hProcessAnalyst, "CommandSystem"); END Chapter: 4 Automation Model 192 IProcessAnalyst.ContextMenu [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 variable is bad then the return value will be InvalidArgument. Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() Dim contextMenu As Boolean ‘Getting Property value contextMenu = myPage_AN35.ContextMenu ‘Disable the context menu myPage_AN35.ContextMenu = False End Sub [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); INT contextMenu; // Getting current property value contextMenu =_ObjectGetProperty(hProcessAnalyst,"ContextMenu"); // Disable the context menu _ObjectSetProperty(hProcessAnalyst, "ContextMenu", 0); END IProcessAnalyst.Cursors [Property][Get] Gets a reference to the Process Analyst’s 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 Chapter: 4 Automation Model 193 If the property get succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() Dim cursors As Object ‘Retrieve cursors collection Set cursors = myPage_AN35.Cursors End Sub [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); OBJECT hCursors; // Retrieve cursor collection hCursors = _ObjectGetProperty(hProcessAnalyst, "Cursors"); END IProcessAnalyst.DataRequestRate [Property][Get/Set] Indicates how often (in milliseconds) the Process Analyst Control will request data from the Trends 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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. Remarks This property is useful for controlling the load on a Trends Server. The higher the figure the less load will be put on the Trends Server(s). Limits - Minimum = 10 milliseconds - Maximum = 60000 milliseconds (1 minute) - Default = 1000 milliseconds (1 second) Calling Syntax Chapter: 4 Automation Model 194 Assumes you have a page called "myPage" and the Process Analyst has been 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() OBJECT hProcessAnalyst = ObjectByName("AN35"); INT requestRate; // Retrieve property value requestRate = _ObjectGetProperty(hProcessAnalyst, "DataRequestRate"); // Set property value to 2 seconds _ObjectSetProperty(hProcessAnalyst, "DataRequestRate", 2000); END IProcessAnalyst.DisplayRefreshRate [Property][Get/Set] Indicates how fast the Process Analyst Control display is updated in milliseconds. The de- fault 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 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 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 Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". Chapter: 4 Automation Model 195 [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() OBJECT hProcessAnalyst = ObjectByName("AN35"); INT requestRate; // Retrieve request rate requestRate = _ObjectGetProperty(hProcessAnalyst, "DisplayRefreshRate"); // Set request rate _ObjectSetProperty(hProcessAnalyst, "DisplayRefreshRate", 2000); END IProcessAnalyst.Language [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 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 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) us- ing the format "Resources_.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 Lan- guage 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 CitectSCADA’s multilan- guage feature to make the Process Analyst switch languages. For details, see Multi-lan- guage Support. Calling Syntax Chapter: 4 Automation Model 196 Assumes you have a page called "myPage" and the Process Analyst has been 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() OBJECT hProcessAnalyst = ObjectByName("AN35"); STRING language; // Retrieve current language language = _ObjectGetProperty(hProcessAnalyst, "Language"); // Set language to Japanese _ObjectSetProperty(hProcessAnalyst, "Language", "ja-JP"); END IProcessAnalyst.LastSelectedPen [Property][Get] Retrieves the last selected pen on the Process Analyst. Defined As - [VBA] Object LastSelectedPen - [Cicode] OBJECT LastSelectedPen - [C++] IPen* LastSelectedPen 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 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 Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". Chapter: 4 Automation Model 197 [VBA] Sub Example() Dim selectedPen As Object ‘Retrieve primary selection Set selectedPen = myPage_AN35.LastSelectedPen End Sub [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); OBJECT selectedPen; // Retrieve primary selection selectedPen = _ObjectGetProperty(hProcessAnalyst, "LastSelectedPen"); END IProcessAnalyst.LockedPens [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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. 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 Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() Dim locked As Boolean ‘Get current locked status Chapter: 4 Automation Model 198 locked = myPage_AN35.LockedPens ‘Turn off locked Pens myPage_AN35.LockedPens = False End Sub [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); OBJECT lockedPens; // Get current locked status lockedPens = _ObjectGetProperty(hProcessAnalyst, "LockedPens"); // Turn off locked Pens _ObjectSetProperty(hProcessAnalyst, "LockedPens", 0); END IProcessAnalyst.NumberofSamples[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 respective- ly. Note: The value entered into the Number of Samples box in the Process Analyst Properties dialog box is closely tied to the display resolution. The default setting is ideal for screen res- olutions from 1024x768 to 1280x1024. The association between Number of Samples and the display resolution occurs because for each sample shown on screen the Process Analyst at- tempts to leave a small gap to allow for sample markers. Because the Process Analyst shows samples when they occur, it requires less data than a traditional trend client. Retriev- ing data is expensive and the more data you retrieve the more time the request takes. It is recommended that this parameter not exceed 500. Defined As - [VBA] Integer NumberofSamples - [Cicode] INT NumberofSamples - [C++] short NumberofSamples 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 property is useful for controlling the performance of a client. (CPU usage). By dividing a pen’s 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 Chapter: 4 Automation Model 199 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.ObjectView [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 If the property get succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() Dim objectView As Object ‘Retrieve the objectview Set objectView = myPage_AN35.ObjectView End Sub Chapter: 4 Automation Model 200 [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); OBJECT objectView; // Retrieve the objectview objectView = _ObjectGetProperty(hProcessAnalyst, "ObjectView"); 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 If the property get succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() Dim panes As Object ‘Retrieve the panes collection Set panes = myPage_AN35.Panes End Sub [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); OBJECT panes; // Retrieve the panes collection panes = _ObjectGetProperty(hProcessAnalyst, "Panes"); END IProcessAnalyst.PrimaryPath [Property][Get/Set] Specifies the primary location for saving and loading Process Analyst views. Defined As Chapter: 4 Automation Model 201 - [VBA] String PrimaryPath - [Cicode] STRING PrimaryPath - [C++] BSTR PrimaryPath 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 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 Assumes you have a page called "myPage" and the Process Analyst has been 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() OBJECT hProcessAnalyst = ObjectByName("AN35"); STRING path; // Retrieve the path path = _ObjectGetProperty(hProcessAnalyst, "PrimaryPath"); // Set the path _ObjectSetProperty(hProcessAnalyst, "PrimaryPath", "\\computer1\PA Views"); END IProcessAnalyst.SecondaryPath [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 Chapter: 4 Automation Model 202 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 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 Assumes you have a page called "myPage" and the Process Analyst has been 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() OBJECT hProcessAnalyst = ObjectByName("AN35"); STRING path; // Retrieve the path path = _ObjectGetProperty(hProcessAnalyst, "SecondaryPath"); // Set the path _ObjectSetProperty(hProcessAnalyst, "SecondaryPath", "\\computer1\PA Views"); END IProcessAnalyst.Toolbars [Property][Get] Gets a reference to the Toolbars collection. With this object you can browse and modify ex- isting toolbars. Defined As - [VBA] Object Toolbars - [Cicode] OBJECT Toolbars - [C++] IToolbars* Toolbars Execution Result Chapter: 4 Automation Model 203 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. Calling Syntax Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". [VBA] Sub Example() Dim toolbars As Object ‘Retrieve the toolbars collection Set toolbars = myPage_AN35.Toolbars End Sub [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); OBJECT toolbars; // Retrieve the toolbars collection toolbars = _ObjectGetProperty(hProcessAnalyst, "Toolbars"); END IProcessAnalyst.WritePrivilegeLevel [Property][Get] Returns the privilege level required to save Process Analyst views to the Primary and Sec- ondary paths. Defined As - [VBA] Integer WritePrivilegeLevel - [Cicode] INT WritePrivilegeLevel - [C++] short WritePrivilegeLevel 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 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 Assumes you have a page called "myPage" and the Process Analyst has been named "AN35". Chapter: 4 Automation Model 204 [VBA] Sub Example() Dim privilege As Integer ‘Retrieve the privilege privilege = myPage_AN35.WritePrivilegeLevel End Sub [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); INTEGER privilege; // Retrieve the privilege privilege = _ObjectGetProperty(hProcessAnalyst, "WritePrivilegeLevel"); END IProcessAnalyst.ZoomMode [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 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 Setting this mode will verify 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 Assumes you have a page called "myPage" and the Process Analyst has been 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 Chapter: 4 Automation Model 205 [Cicode] FUNCTION Example() OBJECT hProcessAnalyst = ObjectByName("AN35"); INT zoomMode; // Retrieve the zoomMode zoomMode = _ObjectGetProperty(hProcessAnalyst, "ZoomMode"); // Set the zoomMode _ObjectSetProperty(hProcessAnalyst, "ZoomMode", -1); END IToolbar Interface Defined As - [VBA] Object - [Cicode] OBJECT - [C++] IToolbar Methods (0) Properties (2) IToolbar.Visible [Property][Get/Set] IToolbar.Buttons [Property][Get] IToolbar.Buttons [Property][Get] Gets this Toolbars collection of Buttons. Defined As - [VBA] Object Buttons - [Cicode] OBJECT Buttons - [C++] IToolbarButtons* Buttons Execution Result If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. Calling Syntax This example assumes there is a valid Toolbar object as retrieved from a Process Analyst’s Toolbars collection. (for example, VBA: ProcessAnalyst.Toolbars.Item(1)) [VBA] Sub Example(Toolbar As Object) Dim buttons As Object ‘Getting Property value Set buttons = Command.Buttons End Sub Chapter: 4 Automation Model 206 [Cicode] FUNCTION Example(OBJECT hToolbar) // Getting property value OBJECT hButtons = _ObjectGetProperty(hToolbar, "Buttons"); END IToolbar.Visible [Property][Get/Set] Gets and Sets this Toolbars Visible state. Defined As - [VBA] Boolean Visible - [Cicode] INT Visible - [C++] VARIANT_BOOL Visible Execution Result If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. 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 Analyst’s Toolbars collection. (for example, VBA: ProcessAnalyst.Toolbars.Item(1)) [VBA] Sub Example(Toolbar As Object) Dim visible As Boolean ‘Getting Property value visible = Command.Visible ‘Setting Property value Command.Visible = False End Sub [Cicode] FUNCTION Example(OBJECT hToolbar) // Getting property value INT nVisible = _ObjectGetProperty(hToolbar, "Visible"); // Setting property value _ObjectSetProperty(hToolbar, "Visible", 0); Chapter: 4 Automation Model 207 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.Item [Property][Get] Gets the Toolbar 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, 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 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 This example assumes there is a valid Toolbars collection as retrieved from an ObjectView. (for example, VBA: objectView.Toolbars) [VBA] Sub Example(Toolbars As Object) Dim toolbar As Object ‘Getting Property value Set toolbar = Toolbars.Item(1) End Sub Chapter: 4 Automation Model 208 [Cicode] FUNCTION Example(OBJECT hToolbars) // Getting property value OBJECT hToolbar = _ObjectCallMethod(hToolbars, "get_Item", 1); END IToolbars._NewEnum [Property][Get] This allows For.. Each.. Next integration in VB. Calling Syntax This example assumes there is a valid Toolbars collection as retrieved from an ObjectView (for example, VBA: objectView.Toolbars). This property is not applicable to Cicode. [VBA] Sub Example(Toolbars As Object) Dim toolbar As Object Dim count Object ‘Using Property For Each toolbar In Toolbars count = count + 1 Next toolbar End Sub 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 If the property get succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. Calling Syntax This example assumes there is a valid Toolbars collection as retrieved from an ObjectView. (for example, VBA: objectView.Toolbars). [VBA] Sub Example(Toolbars As Object) Dim count As Long ‘Getting Property value count = Toolbars.Count End Sub Chapter: 4 Automation Model 209 [Cicode] FUNCTION Example(OBJECT hToolbars) // Getting property value INT nCount = _ObjectGetProperty(hToolbars, "Count"); END IToolbarButton Interface Defined As - [VBA] Object - [Cicode] OBJECT - [C++] IToolbar Methods (0) Properties (1) IToolbarButton.CommandId [Property][Get] IToolbarButton.CommandId [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 This example assumes there is a valid ToolbarButtons collection as retrieved from an Ob- jectView (for example, VBA: objectView.Toolbars.Item(1).Buttons). [VBA] Sub Example(Buttons As Object) Dim commandId As String ‘Getting Property value commandId = Buttons.CommandId End Sub [Cicode] FUNCTION Example(OBJECT hButtons) // Getting property value STRING nCommandId = _ObjectGetProperty(hButtons, "CommandId"); END Chapter: 4 Automation Model 210 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._NewEnum [Property][Get] This allows For.. Each.. Next integration in VB. Calling Syntax This example assumes there is a valid ToolbarButtons collection as retrieved from an Ob- jectView (for example, VBA: objectView.Toolbars.Item(1).Buttons). This property is not ap- plicable to Cicode. [VBA] Sub Example(Buttons As Object) Dim button As Object Dim count Object ‘Using Property For Each button In Buttons count = count + 1 Next button End Sub 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 Chapter: 4 Automation Model 211 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 but- ton 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 Ob- jectView (for example, 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.Count [Property][Get] Gets the number of Buttons in this collection. Defined As - [VBA] Long Count - [Cicode] INT Count - [C++] int Count Calling Syntax This example assumes there is a valid ToolbarButtons collection as retrieved from an Ob- jectView. (for example, VBA: objectView.Toolbars.Item(1).Buttons). [VBA] Sub Example(Buttons As Object) Dim count As Long ‘Getting Property value count = Buttons.Count End Sub Chapter: 4 Automation Model 212 [Cicode] FUNCTION Example(OBJECT hButtons) // Getting property value INT nCount = _ObjectGetProperty(hButtons, "Count"); END IToolbarButtons.Item [Property][Get] Gets the button 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, 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 return value will be Gen- eralFailure. Calling Syntax This example assumes there is a valid ToolbarButtons collection as retrieved from an Ob- jectView (for example, VBA: objectView.Toolbars.Item(1).Buttons). [VBA] Sub Example(Buttons As Object) Dim toolbar As Object ‘Getting Property value Set toolbar = Buttons.Item(1) End Sub [Cicode] FUNCTION Example(OBJECT hButtons) // Getting property value OBJECT hToolbar = _ObjectCallMethod(hButtons, "get_Item", 1); END IToolbarButtons.Remove [Method] Removes a button from this toolbar at the supplied index. Chapter: 4 Automation Model 213 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 re- turn value will be InvalidRange. If the method fails, the return value will be GeneralFailure. Calling Syntax This example assumes there is a valid ToolbarButtons collection as retrieved from an Ob- jectView. (for example, VBA: objectView.Toolbars.Item(1).Buttons). [VBA] Sub Example(Buttons As Object) Buttons.Remove(1) End Sub [Cicode] FUNCTION Example(OBJECT hButtons) _ObjectCallMethod(hButtons, "Remove", 1); END IToolbarButtons.RemoveAll [Method] Removes all buttons from this Toolbar. Defined As - [VBA] RemoveAll() - [Cicode] RemoveAll() - [C++] HRESULT RemoveAll() Execution Results If this method succeeds, the return value will be Success. If this method fails, the return val- ue will be GeneralFailure. Calling Syntax This example assumes there is a valid ToolbarButtons collection as retrieved from an Ob- jectView. (for example, VBA: objectView.Toolbars.Item(1).Buttons) Chapter: 4 Automation Model 214 [VBA] Sub Example(Buttons As Object) Buttons.RemoveAll() End Sub [Cicode] FUNCTION Example(OBJECT hButtons) _ObjectCallMethod(hButtons, "RemoveAll"); 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.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 Chapter: 4 Automation Model 215 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the cursor is deleted, the return value will be GeneralFailure. Calling Syntax This example assumes you have a valid reference to a cursor. [VBA] Sub Example(cursor As Object) Dim cursors As Object ‘Getting Property collection Set cursors = cursor.Collection End Sub [Cicode] FUNCTION Example(OBJECT hCursor) OBJECT hCursors; // Getting collection hCursors = _ObjectGetProperty(hCursor, "Collection"); 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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the cursor is deleted the return value will be GeneralFailure. 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 This example assumes you have a valid reference to a cursor. [VBA] Sub Example(cursor As Object) Dim trendCursorColor As Long ‘Getting Property value trendCursorColor = cursor.Color ‘Setting Property value (to red) Chapter: 4 Automation Model 216 cursor.Color = 255 End Sub [Cicode] FUNCTION Example(OBJECT hCursor) INT trendCursorColor; // Getting current property value trendCursorColor = _ObjectGetProperty(hCursor, "Color"); // Setting Property to blue _ObjectSetProperty(hCursor, "Color", PackedRGB(0, 0, 255)); 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, the return value will be GeneralFailure. 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 Chapter: 4 Automation Model 217 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, val- ue 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 deleted, the return val- ue will be GeneralFailure. 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; Chapter: 4 Automation Model 218 _ObjectCallMethod(hCursor , "GetValue", hPen, asLocal, time, milli, value); END ITrendCursor.LabelsLocked [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 This example assumes you have a valid reference to a cursor. [VBA] Sub Example(cursor As Object) Dim labelsLocked As Boolean ‘Getting Property value labelsLocked = cursor.LabelsLocked ‘Setting Property value (False) cursor.LabelsLocked = False End Sub [Cicode] FUNCTION Example(OBJECT hCursor) INT labelsLocked; // Getting current property value labelsLocked = _ObjectGetProperty(hCursor, "LabelsLocked"); // Setting Property to False (0) _ObjectSetProperty(hCursor, "LabelsLocked", 0); END ITrendCursor.Name [Property][Get/Set] Get or Set the Name of the cursor. Defined As - [VBA] String Name - [Cicode] STRING Name Chapter: 4 Automation Model 219 - [C++] BSTR Name 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. 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 This example assumes you have a valid reference to a cursor. [VBA] Sub Example(cursor As Object) Dim name As String ‘Getting Property value name = cursor.Name ‘Setting Property value cursor.Name = "NewCursor" End Sub [Cicode] FUNCTION Example(OBJECT hCursor) STRING name; // Getting current property value name = _ObjectGetProperty(hCursor, "Name"); // Setting Property _ObjectSetProperty(hCursor, "Name", "NewCursor"); END ITrendCursor.PenLabelHeight [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 [in] The pen for which cursor label is to be referenced. Execution Result Chapter: 4 Automation Model 220 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the cursor is deleted the return value will be GeneralFailure. Remarks The value of height is represented in pixels. See Also ITrendCursor.PenLabelWidth [Property][Get/Set], ITrendCursor.PenLabelX [Proper- ty][Get/Set], ITrendCursor.PenLabelY [Property][Get/Set] 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 labelHeight As Double ‘Getting Property value labelHeight = cursor.PenLabelHeight(pen) ‘Setting Property value (100) cursor.PenLabelHeight (pen) = 100 End Sub [Cicode] FUNCTION Example(OBJECT hCursor, OBJECT hPen) REAL labelHeight; // Getting current property value labelHeight = _ObjectCallMethod(hCursor , "get_PenLabelHeight", hPen); // Setting Property to 100 _ObjectCallMethod(hCursor , "put_PenLabelHeight", hPen, 100); END ITrendCursor.PenLabelVisible [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 Chapter: 4 Automation Model 221 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the cursor is deleted, the return value will be GeneralFailure. 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 vis- ibility. 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 This example assumes you have a valid reference to a cursor and a pen. [VBA] Sub Example(cursor As Object, pen As Object) Dim labelVisible As Boolean ‘Getting Property value labelVisible = cursor.PenLabelVisible(pen) ‘Setting Property value (False) cursor.PenLabelVisible(pen) = False End Sub [Cicode] FUNCTION Example(OBJECT hCursor, OBJECT hPen) INT labelVisible; // Getting current property value labelVisible = _ObjectCallMethod(hCursor, "get_PenLabelVisible", hPen); // Setting Property to FALSE _ObjectCallMethod(hCursor , "put_PenLabelVisible", hPen, 0); END ITrendCursor.PenLabelWidth [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 [in] The pen for which cursor label is to be referenced. Chapter: 4 Automation Model 222 Execution Result If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the cursor is deleted the return value will be GeneralFailure. Remarks The value of width is represented in pixels. See Also ITrendCursor.PenLabelHeight [Property][Get/Set], ITrendCursor.PenLabelX [Proper- ty][Get/Set], ITrendCursor.PenLabelY [Property][Get/Set] 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 labelWidth As Double ‘Getting Property value labelWidth = cursor.PenLabelWidth(pen) ‘Setting Property value (100) cursor.PenLabelWidth(pen) = 100 End Sub [Cicode] FUNCTION Example(OBJECT hCursor, OBJECT hPen) REAL labelWidth; // Getting current property value labelWidth = _ObjectCallMethod(hCursor , "get_PenLabelWidth", hPen); // Setting Property to 100 _ObjectCallMethod(hCursor , "put_PenLabelWidth", hPen, 100); END ITrendCursor.PenLabelX [Property][Get/Set] Get or Set the label’s 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 [in] The pen for which cursor label is to be referenced. Execution Result Chapter: 4 Automation Model 223 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the cursor is deleted the return value will be GeneralFailure. Remarks The label position is represented in pixels. See Also ITrendCursor.PenLabelWidth [Property][Get/Set], ITrendCursor.PenLabelHeight [Proper- ty][Get/Set], ITrendCursor.PenLabelY [Property][Get/Set] 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 labelX As Double ‘Getting Property value labelX = cursor.PenLabelX(pen) ‘Setting Property value (100) cursor.PenLabelX(pen) = 100 End Sub [Cicode] FUNCTION Example(OBJECT hCursor, OBJECT hPen) REAL labelX; // Getting current property value labelX = _ObjectCallMethod(hCursor , "get_PenLabelX", hPen); // Setting Property to 100 _ObjectCallMethod(hCursor , "put_PenLabelX", hPen, 100); END ITrendCursor.PenLabelY [Property][Get/Set] Get or Set the label’s 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 [Proper- ty][Get/Set], ITrendCursor.PenLabelX [Property][Get/Set] Calling Syntax Chapter: 4 Automation Model 224 This example assumes you have a valid reference to a cursor and a pen. [VBA] Sub Example(cursor As Object, pen As Object) Dim labelY As Double ‘Getting Property value labelY = cursor.PenLabelY(pen) ‘Setting Property value (100) cursor.PenLabelY(pen) = 100 End Sub [Cicode] FUNCTION Example(OBJECT hCursor, OBJECT hPen) REAL labelY; // Getting current property value labelY = _ObjectCallMethod(hCursor , "get_PenLabelY", hPen); // Setting Property to 100 _ObjectCallMethod(hCursor , "put_PenLabelY", hPen, 100); END ITrendCursor.Position [Property][Get/Set] Get or Set the cursor’s physical position in the Process Analyst. Defined As - [VBA] Long Position - [Cicode] INT Position - [C++] int Position 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. If the cursor is deleted, the return value will be GeneralFailure. Remarks The cursor position is measured as the number of pixels from the left of the Process Analyst graph. Calling Syntax This example assumes you have a valid reference to a cursor. [VBA] Sub Example(cursor As Object) Dim position As Integer ‘Getting Property value position = cursor.Position ‘Setting Property value cursor.Position = 300 End Sub Chapter: 4 Automation Model 225 [Cicode] FUNCTION Example(OBJECT hCursor) INT position; // Getting current property value 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 If the property get/set succeeds, the return value will be Success. If the return variable is bad, the return value will be InvalidArgument. If the cursor is deleted, the return value will be GeneralFailure. 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 This example assumes you have a valid reference to a cursor. [VBA] Sub Example(cursor As Object) Dim visibility As Boolean ‘Getting Property value visibility = cursor.Visible ‘Setting Property value (False) cursor.Visible = False End Sub [Cicode] FUNCTION Example(OBJECT hCursor) INT visibility; // Getting current property value Chapter: 4 Automation Model 226 visibility = _ObjectGetProperty(hCursor, "Visible"); // Setting Property to False (0) _ObjectSetProperty(hCursor, "Visible", 0); 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 If the property get/set succeeds the return value will be Success. If the return variable is bad then the return value will be InvalidArgument. If the cursor is deleted the return value will be GeneralFailure. Limits - Minimum (0) - Maximum (8) Calling Syntax This example assumes you have a valid reference to a cursor. [VBA] Sub Example(cursor As Object) Dim lineWidth As Long ‘Getting Property value lineWidth = cursor.Width ‘Setting Property value cursor.Width = 5 End Sub [Cicode] FUNCTION Example(OBJECT hCursor) INT lineWidth; // Getting current property value lineWidth = _ObjectGetProperty(hCursor, "Width"); // Setting Property to 5 _ObjectSetProperty(hCursor, "Width", 5); END 227 Chapter: 5 Automation Examples The best way of understanding how to use the Process Analyst’s automation model is to see some example code. The following examples cover the most important concepts of ex- tensibility 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 object’s 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 Analyst’s event class name with the event name you want to handle and an underscore. 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 [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". Chapter: 5 Automation Examples 228 [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 naviga- tion 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; Chapter: 5 Automation Examples 229 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: 3. ID ="SelectedPen" 4. Tooltip = "Show the name of the selected pen" 5. Button style = 6. Enabled = Once you’ve 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 comman- dId 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 Chapter: 5 Automation Examples 230 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 command’s 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 command 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 Chapter: 5 Automation Examples 231 [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 informa- tion 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 verify 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 isn't too difficult because the Object View tree always re- flects 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 us- ing 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 Chapter: 5 Automation Examples 232 will be executed. Note also that, for efficiency, the BlockUpdates and UnblockUpdates func- tions 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 han- dlers for particular Process Analyst events. The example below uses the PenCreated event and the HorizontalAxisChanged event. These events will verify 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], IProces- sAnalyst.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 Chapter: 5 Automation Examples 233 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() OBJECT hPA = ObjectByName("CPA"); OBJECT hPanes = _ObjectGetProperty(hPA, "Panes"); OBJECT hPane; OBJECT hPens; OBJECT hPen; OBJECT hObjectView = _ObjectGetProperty(hPA, "ObjectView"); OBJECT hPaneItems = _OBJECTGetProperty(hObjectView, "Items"); OBJECT hPaneItem; OBJECT hPenItems; OBJECT hPenItem; 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; STRING sText; FOR iPane = 1 TO nPanes DO Chapter: 5 Automation Examples 234 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 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 236 237 Chapter: 6 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 exist- ing 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 An- alyst, 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 An- alyst 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. 3. Panes: Panes are used to group pens visually in the Process Analyst and are stacked ver- tically on the Process Analyst display. Every pen belongs to a single pane. You can con- figure chart panes. 4. Chart background (not shown): The panes are drawn over the chart background. De- pending 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 indi- cate data values. You can configure this axis. 7. Cursor: A cursor allows an Operator to determine value at a given point in time by drag- ging 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. Chapter: 6 The Process Analyst: An Overview 238 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. 239 Chapter: 7 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 | Operator Command Reference I t em Descr i pt i on Load Vi ew . Loads a saved view from file. For det ails, see Loading a view. Sav e Vi ew . Saves a view t o file. For det ails, see Saving a view. Pr i nt . Displays t he st andard Windows Print dialog box for print ing t rend re- port s. For det ails, see Print ing and Export ing. Copy t o Cl i pboar d. Copies visible pens t o t he Windows Clipboard. For de- t ails, see Copying dat a t o t he Clipboard. Ex por t t o Fi l e. Export s visible pens t o an Excel- compat ible file. For det ails, see Copying dat a t o file. Add Pen. Displays t he Add New Pen( s) dialog box for adding a pen. For de- t ails, see Adding Pens. Remov e Pen. Delet es t he current ly select ed pen from t he t rend display. For det ails, see Delet ing Pens. Lock / Unl ock Pens. Toggles t he locking of pens. For det ails, see Locking/ Unlocking Pens. Show / Hi de Poi nt s. Toggles t he display of point s represent ing where sam- ple dat a was recorded in t he archive. For det ails, see Pens: An Overview. Show / Hi de Cur sor s. Toggles t he display of cursors. For det ails, see Using Cursors. Show / Hi de Cur sor Label s. Toggles t he display of cursor labels. For det ails, see Using Cursor Labels. Toggl e Obj ect Vi ew . Toggles t he display of t he Obj ect View. For det ails, see Using t he Obj ect View. Pr oper t i es. Displays t he Propert ies dialog box for configuring t he Process Analyst cont rol. For det ails, see Configuring t he Process Analyst . Hel p. Displays t he Process Analyst online Help. Chapter: 7 Using the Main Toolbar 240 241 Chapter: 8 Understanding Process Analyst Pens The Process Analyst pens allow you to analyze and compare both real-time and historical data from Trends and Alarm Servers. 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 in- dicate 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. See Also Pen Types 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 dis- play 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: 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 Sampl e compact i on Poi nt t y pe Single Ellipse Mult iple Rect angle I nt erpolat ed Triangle ( see I nt erpolat ed samples) . Chapter: 8 Understanding Process Analyst Pens 242 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 pe- riod, 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 op- tions 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 with- in 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 samples with- in the multiple sample. The timestamp will be that of the 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 samples within the multiple sample. The timestamp will be that of the individual sample that was the newest. The timestamp will be the average of all the individual samples within the mul- tiple sample. 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 CitectSCADA is unable to obtain a sample or the data retrieved was invalid, an N/A sample will be recorded in the trend archive. - Gated/Disabled - For trends, when the trigger of a trend is off, a value of "Gated" is re- corded 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: Qual i t y Li ne st y l e Good Solid NA None Gat ed Dot Chapter: 8 Understanding Process Analyst Pens 243 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. 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 "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 cur- rent time is 10.00 p.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 dynami- cally 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 milli- seconds 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 repre- sent 5 minutes, and the minor intervals 30 seconds. Dat a sampl e Descr i pt i on This example shows several single samples. The t hird sam- ple has a qualit y of N/ A, indicat ed by t he break in t he t rend line. Here t he qualit y of t he t hird sample is gat ed, indicat ed by t he broken line connect ing t hese samples. Wit h mult iple samples, t he qualit y of t he last sample in t he group det ermines how t he line is drawn. Consider t he following examples: This example shows t hat t he t hird sample is act ually a mul- t iple sample. The qualit y of t he t hird ( mult iple) sample and t he next sample is N/ A, again indicat ed by t he break in t he t rend line. Here t he qualit y of t he t hird mult iple sample is gat ed, again indicat ed by t he broken line connect ing t he samples. Chapter: 8 Understanding Process Analyst Pens 244 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 computer’s time settings. The position of the Now indicator is refreshed according to the value specified in the Dis- play 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 Cit- ectSCADA 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 rep- resent 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 in- dividual pen. Chapter: 8 Understanding Process Analyst Pens 245 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 Configur- ing 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 grid- lines. 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 hori- zontal 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 ap- plies 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 Chapter: 8 Understanding Process Analyst Pens 246 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 associ- ated 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 sam- ple with a different value arrives, in which case a vertical line is drawn: Chapter: 8 Understanding Process Analyst Pens 247 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 alarm’s 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 ele- ments: 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. Chapter: 8 Understanding Process Analyst Pens 248 Like other types of pen, alarm pens can represent variations in data quality and data com- paction. 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 dic- tated by the type of CitectSCADA alarm tag. The Process Analyst supports all CitectSCA- DA standard alarm types. Note: For multi-digital alarms 1 , 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 unacknowl- edged 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 Pro- cess 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 sam- ple marker, as shown here: 1.Use combinations of values from three digital variables to define eight states. For each state, you specify a description (e.g., healthy or stopped), and whether or not the state triggers an alarm. Chapter: 8 Understanding Process Analyst Pens 249 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. Al ar m t y pe Al ar m pen r epr esent at i on Digit al Analog Advanced Argyle Analog Mult i- digit al Timest amped Timest amped analog Timest amped digit al Chapter: 8 Understanding Process Analyst Pens 250 251 Chapter: 9 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 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 in- dicate 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. 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 pen’s 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: 9 Interacting with the Process Analyst 252 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 (horizon- tal 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 month’s 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 re- quired. 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. Chapter: 9 Interacting with the Process Analyst 253 2. Drag the mouse in the direction you want to scroll: 7. Horizontal axis: drag right to move backward in time, drag left to move forward. 8. 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: 9. Horizontal axis: spin up to move backward, spin down to move forward. 10. 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 Us- ing the Right-click Menu for details. The Process Analyst indicates whether scrolling is enabled or disabled by displaying a dif- ferent-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: 11. Horizontal axis: drag left to expand the scale, drag right to shrink. 12. 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: 13. Horizontal axis: spin up to shrink the axis, spin down to expand. 14. 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 Us- ing the Right-click Menu for details. The Process Analyst indicates whether scaling is enabled or disabled by displaying a dif- ferent-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. Chapter: 9 Interacting with the Process Analyst 254 - 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 com- puter for the currently logged in user. The date/time picker displays time in 24-hour format (dd/mm/yyyyhhmm:ssnnn) 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: 15. Type in a time explicitly. 16. Press the Up arrow key or Down arrow key to increment or decrement the value re- spectively. 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 picker’s value is within the local Daylight Savings period: This icon appears when the time picker’s 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. Chapter: 9 Interacting with the Process Analyst 255 Note: In order for the Process Analyst to be able to indicate that Daylight Savings is in ef- fect, 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 incre- ments 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 Chapter: 9 Interacting with the Process Analyst 256 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 com- monly 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 cur- rent 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 SpanLock 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 pen’s history. The following navigation controls are available: Navi gat i on cont r ol Descr i pt i on Back One Span - moves back one t ime span. Back Hal f a Span - moves back half a t ime span. For w ar d Hal f a Span - moves forward half a t ime span. Chapter: 9 Interacting with the Process Analyst 257 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 Au- toscrolling 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. Undo Last Zoom Undo Last Zoom allows you to undo the last zoom operation, returning the display to the previous state. For w ar d One Span - moves forward one t ime span. Command I con Descr i pt i on Zoom I n 50% Zooms in on t he displayed dat a, halving t he span of bot h axes. Zoom Out 50% Zooms out of t he displayed dat a, doubling t he span of bot h axes. Chapter: 9 Interacting with the Process Analyst 258 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 ToggleBox 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 dig- ital 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: Chapter: 9 Interacting with the Process Analyst 259 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 ei- ther 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 cur- rent 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. Chapter: 9 Interacting with the Process Analyst 260 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: To show/hide a cursor: St at e St y l e Ex ampl e I nt ersect ion wit hin pen dat a Line I nt ersect ion before or aft er pen dat a Line wit h indicat or No int ersect ion and no dat a I nvisible line Chapter: 9 Interacting with the Process Analyst 261 - Click Show/Hide Cursor on the main toolbar. You can display additional cursors by us- ing 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 " km/h". The label displays the following values when the quality of the data is not good: Task Descr i pt i on Move a cursor label Click t he cursor label and drag t he label t o a new locat ion. Change t he size of cursor labels Click t he cursor label you want t o resize. Place t he mouse cursor on one of t he sizing boxes, and drag t he label t o t he new size. I f you drag t he corner of t he label, t he label t ext resizes t o an opt imal size for t he label. Lock or unlock t he cursor la- bels Click t he Lock / Unl ock Cur sor Label s. When on, t his command causes cursor labels t o be "frozen" in t he posit ion. Cur sor f i el d Appl i es t o Descr i pt i on Pen Name All Pen t ypes Displays t he non- unique Process Analyst pen name Value/ Qualit y All Pen t ypes Displays t he value of t he pen at t he point t he cursor int ersect s wit h t he pen dat a Dat e- Time St amp All Pen t ypes Displays t he dat e/ t ime st amp at t he point t he cursor int ersect s wit h t he dat e/ t ime axis. Alarm Sample Com- ment Alarms Comment bound t o an alarm sample. Cur sor val ue Descr i pt i on NA At t he point of int ersect ion t he pen has no available dat a for display. Gat ed At t he point of int ersect ion t he pen’s dat a has been gat ed. Disabled At t he point of int ersect ion t he alarm t ag of t he pen was disabled. Chapter: 9 Interacting with the Process Analyst 262 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 ac- knowledgement 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 dis- plays the Properties dialog box. For details, see Using the Process Analyst Properties Dia- log Box. Understanding Mouse Pointers When using the Process Analyst, the mouse pointer changes shape to indicate the opera- tions you can perform at that time. Cur sor val ue Descr i pt i on < value> - > The cursor is t o t he left of t he first available sample for t his pen. < - < value> The cursor is t o t he right of t he last available sample for t his pen. Mouse poi nt er Regi on Descr i pt i on Pen line The mouse point er looks like t his when t he point er is on a pen. Clicking t he mouse at t his point select s t he pen. Pen line/ pen background The mouse point er looks like t his when t he mouse is over a pen’s background and bot h horizont al and vert ical scrolling are enabled. Clicking and dragging at t his point result s in t he free movement of t he pen. Scrolling t he mouse wheel result s in horizont al- only movement . Horizont al axis The mouse point er looks like t his when t he point er is on t he horizont al axis and horizont al scaling is enabled. Clicking and dragging ( or scrolling t he mouse wheel) will result in t he axis being scaled. Chapter: 9 Interacting with the Process Analyst 263 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 Trends and Alarms Servers and add pens that represent these tags to the current trend display. 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 TagFilter and/or Cluster Filter to apply to the search (optional). If you leave either of the Filter text boxes blank, all tags or clusters of the selected server type will be retrieved. The filters have 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*' in the Tag Filter returns all tags beginning with the letter "L" in all clusters. 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 Searchlist. The results are not sorted: the tags appear in the order they were configured in CitectSCADA. The cluster associated with each tag is also displayed. The Process Analyst displays only the tags in clusters that this client has access to. In a system with more than one cluster, if a tag is not configured with a cluster, it is listed once for each cluster. The Search Result 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. Pen line/ pen background The mouse point er looks like t his when t he point er is on t he horizont al axis and only horizont al scrolling is enabled. Clicking and dragging ( or scrolling t he mouse wheel) will re- sult in t he axis being scrolled. Vert ical axis The mouse point er looks like t his when t he point er is on t he vert ical axis and vert ical scaling is enabled. Clicking and dragging ( or scrolling t he mouse wheel) will result in t he axis being scaled. Vert ical axis The mouse point er looks like t his when t he point er is on t he vert ical axis and only vert ical scrolling is enabled. Clicking and dragging ( or scrolling t he mouse wheel) will result in t he axis being scrolled. Box Zoom mode The mouse point er looks like t his when Box Zoom mode is enabled. See Toggle Box Zoom. Chapter: 9 Interacting with the Process Analyst 264 7. Select how to resolve the pen name: 17. 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. 18. Tag- applies the tag name as the pen name. 19. Auto-applies an automatically generated name to the pen using the format Pen 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 RemovePen 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 Add- ing Pens. 3. Select the tag in the Selected Items list, and then click Show Detail. The Pen Details di- alog box appears, showing the system information for the selected tag. Chapter: 9 Interacting with the Process Analyst 265 Chapter: 9 Interacting with the Process Analyst 266 267 Chapter: 10 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 infor- mation 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 dis- played, 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 oth- er selected pens are highlighted in gray. See Also Pen Selection The Object View displays the following items: 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 pen’s 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, I con Obj ect Analog pen Digit al pen Alarm pen Pane Chapter: 10 Using the Object View 268 if a new pen is added to or deleted from a pane, or if a pen’s 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. See Also Configuring the Object View Col umn Descr i pt i on Zero Scale Vert ical axis st art posit ion of t he pen. Full Scale Vert ical axis end posit ion of t he pen. Engineering Unit s Engineering unit s associat ed wit h t he pen. Task Descr i pt i on Toggle t he display of Obj ect View on or off Click Toggl e Obj ect Vi ew on t he main t oolbar. Change t he size of Obj ect View Drag t he split t er bar t hat is locat ed bet ween t he chart area and t he Obj ect View up or down. Expand or collapse a t ree node in t he Obj ect Tr ee col- umn Eit her click t he ( + ) box t o expand t he node or t he ( - ) box t o collapse t he node; or double- click t he it em t o t oggle be- t ween expanded and collapsed st at es. This does not affect t he display of panes in t he chart . Select a pen Click t he pen in t he Obj ect View t able. Select ing a pen in t he Obj ect View gives t he focus in t he chart t o t he select ed pen, and vice versa. You can only select one pen per pane at a t ime ( you cannot select a pane) . Display or hide a pen Click t o clear t he check box t o hide t he pen; click t he check box again t o display t he pen. Dynamically change t he widt h of a column during display Drag t he column divider left or right . Not e: You can quickly resize a column t o fit t he size of t he widest it em in a column by double- clicking a column sepa- rat or. To resize t he column back t o it s original size, double- click t he separat or again. You can also configure t he widt h of a column via t he Process Analyst Propert ies dialog; for det ails, see Configuring t he Obj ect View. 269 Chapter: 11 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 docu- mentation. 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. 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 highlight- ed, indicating that this pen is selected; consequently, the axes shown in the report are asso- ciated with this pen. You can see that this pen is selected in the chart by the "halo" effect Chapter: 11 Printing and Exporting 270 surrounding the pen. The color boxes on the left-hand side of the legend help you to dis- tinguish 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 re- port 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 di- alog 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 leg- end 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 isn't 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. Chapter: 11 Printing and Exporting 271 2. The panel shows, by default, the Pen Options, Statistical Analysis Options, and Cur- sors 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. 20. Minimum - causes the minimum value from cache to be returned. Note that this val- ue might not be a real logged sample if the sample found is a multiple calculated sample. 21. Maximum - causes the maximum value from cache to be returned. Note that this val- ue might not be a real logged sample if the sample found is a multiple calculated sample. 22. 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 se- lected. 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. Chapter: 11 Printing and Exporting 272 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 Com- ment. 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 select- ed. 5. Click Apply. Exporting Pen Data You can export Process Analyst data for pens that are visible to either the Windows Clip- board (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: Ti me Mi l l i seconds 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] Chapter: 11 Printing and Exporting 273 Export functionality doesn't 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.NumberofSamples[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 - 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 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. Notes - 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 cor- rectly. Because the OLEDATE data type excludes milliseconds, a separate column is provided, which exports the millisecond component for each timestamp. - The results exported are in Unicode format. You should use Excel 2000 and later, which support this format. 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: 11 Printing and Exporting 274 275 Chapter: 12 Configuring the Process Analyst Many of the Process Analyst control’s properties can be configured at run time to allow an Operator to customize the control to suit their working preferences. To configure the Pro- cess 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 Configuring the Object View 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, andObject View. Main page You use the Main page of the Properties dialog box to configure general properties and ac- cess 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 Ana- lyst interface components. Selecting an item displays the property controls for that compo- Chapter: 12 Configuring the Process Analyst 276 nent 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 don't 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 don't 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 Chart-wide Properties - Configuring Chart Panes - Configuring Pens - Configuring Cursors - Configuring Defaults 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. Ri ght - cl i ck t hi s i t em. . . Act i ons Chart Add Pane - add a new pane. Add Cur sor - add a new cursor. Pane Add Di gi t al - adds a new digit al pen. Add Anal og - adds a new analog pen. Add Al ar m - adds a new alarm pen. Not e: Aft er adding a pen from t his menu, configure t he dat a con- nect ion by clicking t he Connect i on t ab and t yping t he name of t he t ag int o t he Tag t ext box. Del et e - delet es t he pane. Pen Del et e - delet es t he pen. Cursor Del et e - delet es t he cursor. Chapter: 12 Configuring the Process Analyst 277 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 col- umn width and display order. Users can define new columns and edit existing columns at design time. Use the Object View page for the following: - Configuring the Object View - Creating or Editing Object View Columns Configuring Chart-wide Properties 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 An- alyst properties page. This page contains two tabs, General and Server Paths, used to mod- ify the following configurations: - Configuring general properties - 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 and whether security settings are inherited from the graphics page containing the PA. 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 millisec- onds. 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. Chapter: 12 Configuring the Process Analyst 278 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 Analyst’s 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 Trends 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 per- mitted range is between 10-5000. Also see Exporting Pen Data. Note: This value is closely tied to your display resolution. The default setting is ideal for screen resolutions from 1024x768 to 1280x1024. The association between Number of Samples and the display resolution occurs because for each sample shown on screen the Process Analyst attempts to leave a small gap to allow for sample markers. Because the Process Analyst shows samples when they occur, it requires less data than a traditional trend client. Retrieving data is expensive and the more data you retrieve the more time the request takes. It is recommended that this parameter not exceed 500. 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. Set the Administration Privilege Level required for an operator to use this object/ group. Select the Inherit Security Settings checkbox if you want security settings to be inherited from the page containing the PA, or clear the check box to overwrite security settings when a new .pav file is loaded. 8. 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 CitectSCADA run path if the Process An- alyst 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 machine’s logged-in user’s 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. Chapter: 12 Configuring the Process Analyst 279 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. Configuring Chart Panes 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 prop- erties 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: 23. 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. 24. Fixed -Sets the pane height to the value specified in the Size control. 4. Specify a Size for the pane. Chapter: 12 Configuring the Process Analyst 280 5. Click Apply. Configuring Pens The Process Analyst allows you to configure your pens to suit your preferences. Pen con- figuration 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 (dig- ital pens). To configure pen appearance: 1. Select the pen you want to configure. 2. Click the Appearance tab to display the appearance property controls. Chapter: 12 Configuring the Process Analyst 281 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: 25. 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. 26. 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: 1. Select the pen you want to configure. 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. Chapter: 12 Configuring the Process Analyst 282 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 design time by Users. 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 us- ing local or UTC format. For more information about pen axes, see Date/Time (Horizontal) Axis and Vertical (Value) Axis. Chapter: 12 Configuring the Process Analyst 283 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: 1. Click the Main Page tab. 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): 27. Select the Autoscale option to autoscale the vertical axis. 28. 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 you're 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 ma- chine settings. If this option is not selected, the time is displayed in UTC format. For de- tails 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. Chapter: 12 Configuring the Process Analyst 284 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 design time by Users. 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: 1. Click the Main Page tab. 2. Select the pen you want to configure. 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. This 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 appro- priate privileges. To configure pen data connection: 1. Select the pen you want to configure. 2. Click the Connection tab to display the connection property controls. Chapter: 12 Configuring the Process Analyst 285 3. For the Server data connection, a connection is selected by default, indicat- ing 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. In the Trend tag field, enter the trend tag for the pen. In a system with more than one cluster, you should specify both the cluster and tag using the format . Omitting the cluster name will cause an error. If the system has only one cluster configured, you can just enter the tag name. The configured cluster will be assumed. 5. Select a Request mode. The default is Average. The request mode defines how multiple samples are treated by the Process Analyst. Re- gardless 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. Con- figuring 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 cursor labels: 1. Select the pen you want to configure. 2. Click the Cursor Label tab to display the connection property controls. Chapter: 12 Configuring the Process Analyst 286 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 Cur- sors. To configure the cursor: 1. In the property tree of the 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. Configuring Defaults 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 life- time 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: Chapter: 12 Configuring the Process Analyst 287 - 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 (MainToolbar or Navigation Toolbar). 2. To add a command to the toolbar: In the Available toolbar buttons list, select the com- mand you want to add to the toolbar, and then click Add. The selected command moves to the Current toolbar buttons list. Chapter: 12 Configuring the Process Analyst 288 The Available toolbar buttons list contains all the command buttons available in your sys- tem, 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. Configuring the Object View Operators can configure the Object View to display additional pen information to the col- umns 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 col- umns and the column display order. Users can define new columns, or edit or delete exist- ing columns; for details, see Creating or Editing Object View Columns. You can configure the Object View to display these predefined columns: Col umn Descr i pt i on Scale Vert ical axis st art and end posit ion of t he pen. Engineering Unit s Engineering unit s associat ed wit h t he pen. Comment The t rend/ alarm comment defined for t he pen. St art Time Dat e/ t ime axis st art posit ion of t he pen. End Time Dat e/ t ime axis end posit ion of t he pen. Durat ion Difference bet ween t he st art t ime and t he end t ime. Tag Pen’s associat ed t rend or alarm t ag. Trend Type Trend t ype of associat ed t ag. Sample Period Sampling period of t he associat ed t rend t ag. Engineering Scale Engineering scale for associat ed t rend t ag. Raw Scale Raw scale for associat ed t rend t ag. Alarm Cat egory Cat egory of associat ed alarm t ag. Alarm Descript ion Descript ion of associat ed alarm t ag. Alarm Area Area of associat ed alarm t ag. Alarm Name Name of associat ed alarm t ag. Alarm Type Alarm t ype of associat ed alarm t ag. Error Displays t he error of t he last dat a request . Blank if last dat a request succeeded. Minimum Lowest displayed value ( t rend t ags only) . Maximum Highest displayed value ( t rend t ags only) . Average Average of all displayed values ( t rend t ags only) . Chapter: 12 Configuring the Process Analyst 289 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 cus- tom columns, edit existing columns, and re-order columns. The Properties page displays all the available columns for the Object View and their prop- erties: - 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 column’s visibility: a column is vis- ible only if the associated checkbox is selected. The Move Up and Move Down buttons to the right of the Available Columns list box al- low you to reorder columns. The order of the columns from top to 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 cre- ated 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, re- spectively, on the main toolbar. Chapter: 12 Configuring the Process Analyst 290 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 ap- pears, showing the location where you can save views. 2. Choose a location to save your view to. Note: It is your administrator’s 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 at- tempts 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. Chapter: 12 Configuring the Process Analyst 291 2. Select a view to load, and then click OK. The view is loaded. Chapter: 12 Configuring the Process Analyst 292 293 Chapter: 13 Operator Command Reference You use the toolbar commands on the main toolbar and navigation toolbar to perform com- monly used functions for viewing and interacting with Process Analyst data, such as add- ing 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 implemen- tation, so not all these commands might appear on your toolbars. Additionally your tool- bars 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 Zoom Commands The Process Analyst has the following zoom commands by default: I con Tool t i p Descr i pt i on Save View Displays t he Save File dialog box allowing an Operat or t o save a Process Analyst view t o a specified locat ion. For det ails, see Saving a view. Load View Displays t he Load View dialog box allowing t he operat or t o specify a view t o load. For det ails, see Loading a view. I con Tool t i p Descr i pt i on Toggle Box Zoom Toggles t he Process Analyst int o box zoom mode. The mouse cursor changes t o a crosshair used t o define an area t o zoom in on. Zoom may be cancelled by right - clicking or t oggling t he Zoom command off. For det ails, see Toggle Box Zoom. Zoom in 50% Execut es a horizont al and vert ical zoom in of 50% of t he current span( s) of t he pen( s) . For det ails, see Zoom I n/ Zoom Out . Zoom out 50% Execut es a horizont al and vert ical zoom out of 50% of t he current span( s) of t he pen( s) . For det ails, see Zoom I n/ Zoom Out . Chapter: 13 Operator Command Reference 294 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. See Also View Commands | Zoom Commands | Export Commands | Interface Commands | Gen- eral Commands Undo Last Zoom Undoes t he last zoom operat ion. For det ails, see Undo Last Zoom. Reset t o De- fault Span Rest ores t he pen( s) spans t o t heir original default set - t ings. For det ails, see Reset t o Default Span. Edit Span Displays t he Edit Span dialog box allowing an operat or t o explicit ly ent er a t ime span t o apply t o t he display. For det ails, see Edit Span. Edit Vert ical Scale Enabled when an analog pen is select ed. For det ails, see Edit Vert ical Scale. I con Tool t i p Descr i pt i on Toggle Span Lock Toggles t he locking of t he t ime span. A t ime span is t he " dist ance" in t ime bet ween t he st art t ime and end t ime of t he chart . For det ails, see Span Lock. Back One Span Moves t he pen( s) back in t ime exact ly one t ime span. For det ails, see Navigat ing t ime. Back Half a Span Moves t he pen( s) back half a span. For det ails, see Navigat ing t ime. Forward One Span Moves t he pen( s) forward in t ime exact ly one span. For det ails, see Navigat ing t ime. Forward Half a Span Moves t he pen( s) forward half a span. For det ails, see Navigat ing t ime. Synchronize t o Now Synchronizes pen( s) such t hat t he end dat e t ime reflect s "now" which is posit ioned on t he right - hand edge of t he screen. "Now" is calculat ed using t he current syst em t ime. For det ails, see Synchro- nize t o Now. Toggle Aut o- Scrolling Toggles t he aut omat ic scrolling off and on for all pens. For det ails, see Toggle Aut oscrolling. I con Tool t i p Descr i pt i on Chapter: 13 Operator Command Reference 295 Export Commands The Process Analyst has the following export commands by default: See Also View Commands | Zoom Commands | Navigation Commands | Interface Commands | General Commands Interface Commands The Process Analyst has the following interface commands by default: See Also View Commands | Zoom Commands | Navigation Commands | Export Commands | General Commands I con Tool t i p Descr i pt i on Export t o File Copies visible pens t o an Excel compat ible file. For det ails, see Copying dat a t o file. Copy t o Clip- board Copies visible pens t o t he clipboard. I nt erface Com- mands. For det ails, see Copying dat a t o t he Clip- board. I con Tool t i p Descr i pt i on Show/ Hide Cursor Toggles t he display of cursors. For det ails, see Using Cursors. Show/ Hide Cursor Labels Toggles t he display of cursor labels. Enabled only when a cursor is visible and when a pen exist s. For det ails, see Using Cursor Labels. Show/ Hide Point s Toggles t he display of point s represent ing where sample dat a was recorded in t he archive. For de- t ails, see Underst anding Pens. Lock/ Unlock Cursor Labels Toggles t he locking/ unlocking of cursor labels. Enabled only when a cursor is visible and when a pen exist s. For det ails, see Using Cursor Labels. Lock/ Unlock Pens Toggles t he locking/ unlocking of pens. For de- t ails, see Locking/ Unlocking Pens. Add Pane Adds a new pane t o t he view. For det ails, see Configuring Chart Panes. Remove Pane Removes t he pane of t he primary select ed pen. A dialog confirms t he delet e. For det ails, see Con- figuring Chart Panes. Aut oscale Vert ical Axis for Analog Pens Toggles aut oscaling for t he select ed pen on a per- pen basis. For det ails, see Scaling t he Chart . Lock/ Unlock Vert i- cal Axis Scrolling Toggles int eract ive scrolling of t he vert ical axis and disables aut oscaling. For det ails, see Scroll- ing t he Chart . Chapter: 13 Operator Command Reference 296 General Commands The Process Analyst has the following general commands by default: See Also View Commands | Zoom Commands | Navigation Commands | Export Commands | In- terface Commands I con Tool t i p Descr i pt i on Add Pen Displays t he add pen dialog. For det ails, see Adding Pens. Remove Pen Removes t he select ed pen from t he display. For de- t ails, see Delet ing Pens. Toggle Obj ect View Toggles t he display of t he Obj ect View. For det ails, see Using t he Obj ect View. Print Displays t he print dialog, allowing t he user t o print t he current st at e of t he Process Analyst . For det ails, see Print ing and Export ing. Refresh Dat a Refreshes t he dat a for t he select ed pen, or all pens ( if locked) . Show Propert ies Displays t he Process Analyst Propert ies dialog box. For det ails, see Using t he Process Analyst Propert ies Dialog Box. Help Displays t he Process Analyst Help. 297 Glossary 1 10base2 Ethernet implementation on thin coaxial cable. Typically uses a BNC connection. 10base5 Ethernet implementation on thick coaxial cable. 10baseT Ethernet implementation on unshielded twisted pair. Typically uses as RJ45 connection. A Accredited - Level 1 Drivers developed under the CiTDriversQA96 Driver Quality and Accreditation System, which ensures the driver was designed, coded, and tested to the highest possible standards. Accredited - Level 2 Drivers developed using the CiTDriversQA92 Driver Quality and Accreditation System. accumulator A facility that allows you to track incremental runtime data such as motor run hours, power consumption, and downtime. active alarm An active alarm is an alarm in one of the following states: ON and unacknowledged; ON and acknowledged; OFF and unacknowledged. advanced alarm Triggered when the result of a Cicode expression changes to true. Use advanced alarms only when alarm func- tionality cannot be obtained with the other alarm types. If you configure too many advanced alarms, your sys- tem performance can be affected. alarm categories You can assign each alarm to a category, and then process each category as a group. For example, for each cat- egory, you can specify the display characteristics, the action to be taken when an alarm in the category is trig- gered, and how data about the alarm is logged. You can also assign a priority to the category, which can be used to order alarm displays, filter acknowledgments, and so on. alarm display page The alarm display page displays alarm information in the following format: Alarm Time, Tag Name, Alarm Name, Alarm Description. Glossary 298 alarm summary page Displays alarm summary information in the following format: alarm name, time on, time off, delta time, com- ment. Alarms Server Monitors all alarms and displays an alarm on the appropriate control client(s) when an alarm condition be- comes active. analog alarms Triggered when an analog variable reaches a specified value. supports four types of analog alarms: high and high high alarms; low and low low alarms; deviation alarms; and rate of change alarms. animation number files (.ANT) ASCII text files that contain a list of animation points (ANs) and the coordinate location (in pixels) of each point. animation point The points on a graphics page where an object displays. When you add an object to your page, automatically allocates a number (AN) to the animation point, (i.e., the location of the object). area A large application can be visualized as a series of discrete sections or areas. Areas can be defined geographi- cally (where parts of the plant are separated by vast distances) or logically (as discrete processes or individual tasks). arguments Values (or variables) passed in a key sequence to a keyboard command in runtime (as operator input). Argu- ments can also be the values (or variables) passed to a Cicode function when it executes. attachment unit interface (AUI) Typically used to interface to a transceiver through what is often known as a drop cable. automation component (ActiveX object) ActiveX objects typically consist of a visual component (which you see on your screen) and an automation component. The automation component allows the interaction between the container object and the ActiveX object. B baud rate The number of times per second a signal changes in a communication channel. While the baud rate directly affects the speed of data transmission, the term is often erroneously used to describe the data transfer rate. The correct measure for the data rate is bits per second (bps). BCD variable (I/O device) BCD (Binary Coded Decimal) is a two-byte (16-bit) data type, allowing values from 0 to 9,999. The two bytes are divided into four lots of four bits, with each lot of four bits representing a decimal number. For example the binary number 0010 represents decimal 2. Thus the BCD 0010 0010 0010 0010 represents 2,222. bottleneck A bottleneck occurs when too many requests are being sent to a PLC communication link/data highway. It can occur with all types of protocols, and is dependent on several factors, including the frequency of requests, the Glossary 299 number of duplicated (and hence wasteful) requests, whether the protocol supports multiple outstanding re- quests, as well as other network traffic. browse sequence A series of graphics pages linked by a browse sequence, which is a linear navigation sequence within your runtime system that uses Page Previous and Page Next commands. byte variable (I/O device) Byte is a one-byte data type, allowing values from 0 to 255. One byte consists of 8 bits. Each ASCII character is usually represented by one byte. C cache (I/O device data cache) When caching is enabled, all data read from a I/O device is stored temporarily in the memory of the I/O server. If another request is made (from the same or another control client) for the same data within the cache time, the I/O server returns the value in its memory, rather than read the I/O device a second time. callback function A function that is passed as an argument in another function. Callback functions must be user-written func- tions. Cicode Programming language designed for plant monitoring and control applications. Similar to languages such as Pascal. Cicode blocking function A Cicode function that blocks, or waits, for an asynchronous event to complete before returning. CiNet CiNet is no longer supported. CiNet was designed as a low speed wide area network (for remote monitoring applications). If you have a widely-distributed application where computers are separated by vast distances, using a LAN to connect your control clients can be expensive. To connect control clients in this instance, use Microsoft's remote access server (RAS) or a Microsoft-approved solution, such as Shiva LanRover. citect.ini file A text file that stores information about how each computer (servers and control clients) operates in the con- figuration and runtime environments. The Citect.INI file stores parameters specific to each computer and therefore cannot be configured as part of the project. client A computer that accesses shared network resources provided by another computer called a server. 's client- server based architecture is designed to distribute the processing tasks and optimize performance. cluster A discrete group of alarms servers, trends servers, reports servers, and I/O servers. It would usually also pos- sess local control clients. For a plant comprising several individual sections or systems, multiple clusters can be used, one cluster for each section. command A command performs a particular task or series of tasks in your runtime system. A command is built from Cicode and can consist of just a function or a statement. Glossary 300 communications link A connection between computers and peripheral devices, enabling data transfer. A communications link can be a network, a modem, or simply a cable. . communications port PC port used for sending and receiving serial data (also called serial or COM ports). computer A computer running . Other common industry terms for this computer could be node, machine or workstation. Control Client The interface between the runtime system and an operator. If you are using on a network, all computers (on the network) are control clients. custom alarm filter Custom alarm filters provide a way to filter and display active alarms. Up to eight custom filter strings can be assigned to a configured alarm. In conjunction with a user-defined query function, the custom filters enable operators to identify and display active alarms of interest. D data acquisition board Data acquisition boards communicate directly with field equipment (sensors, controllers, and so on). You can install a data acquisition board in your server to directly access your field equipment. data bits Group of binary digits (bits) used to represent a single character of data in asynchronous transmission. data communications equipment (DCE) Devices that establish, maintain, and terminate a data transmission connection. Normally referred to as a mo- dem. data terminal equipment (DTE) Devices acting as data source, data sink, or both. data transfer Transfer of information from one location to another. The speed of data transfer is measured in bits per second (bps). data type (I/O device) Type of I/O device variable. I/O devices may support several data types that are used to exchange data with . You must specify the correct data type whenever I/O device variables are defined or referenced in your system. DB-15 Often called a `D' type connector due to the vague D shape of the casing. Has 15 pins arranged in two rows of 8 and 7 pins. While not as common as DB-9 or DB-25 they may be found on some computers and data commu- nication equipment. Comes in both male (pins protruding) and female (pin sockets) configurations. DB-25 Often called a `D' type connector due to the vague D shape of the casing. Has 25 pins arranged in two rows of 13 and 12 pins. This kind of connection is a part of the standard for RS-232-D and is found on many computers, Glossary 301 modems and other data communication equipment. Comes in both male (pins protruding) and female (pin sockets) configurations. DB-9 Often called a `D' type connector due to the vague D shape of the casing. Has 9 pins arranged in two rows of 5 and 4 pins. This kind of connection is common and is often used as the serial (com) port in computers. Often used in modems and other data communication equipment. Comes in both male (pins protruding) and female (pin sockets) configurations. deviation alarm Triggered when the value of a variable deviates from a setpoint by a specified amount. The alarm remains ac- tive until the value of the variable falls (or rises) to the value of the deadband. . dial-back modem Only returns calls from remote I/O devices. dial-in modem Only receives calls from remote I/O devices, identifies the caller, then hangs up immediately so it can receive other calls. then returns the call using a dial-back modem. dial-out modem Makes calls to remote I/O devices in response to a request; e.g., scheduled, event-based, operator request, and so on. Also returns calls from remote I/O devices. Digiboard A high-speed serial board manufactured by the Digiboard Corporation. digital alarms Triggered by a state change in a digital variable. Use these alarms when a process has only one of two states. You can use either the on (1) state or off (0) state (of a digital variable) to trigger the alarm. digital variable (I/O device) Usually associated with discrete I/O in your I/O device, a digital variable can only exist in one of two states: on (1) or off (0). Allowed values for the digital data type are therefore 0 or 1. Discrete inputs (such as limit switch- es, photoelectric cells, and emergency stop buttons) and discrete outputs are stored as digital variables. disk I/O device A disk file that resides on the hard disk of a computer and emulates a real I/O device. The value of each variable in the disk I/O device is stored on the computer hard disk. The disk I/O device is not connected to any field equipment in the plant. display period Defines the rate at which trend data is displayed on the trend page. distributed processing For large applications with large amounts of data, you can distribute the data processing to reduce the load on individual computers. distributed servers If your plant consists several sections or systems, you can assign a cluster to each individual section, and then monitor all sections using one control client.Note: Don't use distributed servers to split up a single section or process into discrete areas. A single cluster system with distributed processing would be better used here since it would not be hampered by the maintenance overhead of a distributed server system (such as extra project compilations, and so on). Glossary 302 dither (imported bitmaps) A method of approximating colors in imported or pasted bitmaps that involves combining pixels of different or colors from a color palette. domain name server (DNS) Database server that translates URL names into IP addresses. dot notation Used for Internet addresses. Dot notation consists of four fields (called octets), each containing a decimal num- ber between 0 and 255 and separated by a full stop (.). driver Used by to communicate (with control and monitoring devices) in a device-independent way, allowing the run-time system to interact directly with different types of devices Communication with an I/O device requires a device driver which implements the communication protocol(s). duplex The ability to send and receive data over the same communication line. dynamic data exchange (DDE) A Microsoft Windows standard protocol set of messages and guidelines that enables communication between Windows applications on the same Windows computer. dynamic data exchange (DDE) Server A Windows standard communication protocol supported by . The I/O server communicates with the DDE server using the Windows standard DDE protocol. DDE servers are appropriate when data communication is not critical as DDE servers are not designed for high-speed data transfer. E empty value Indicates that the variant has not yet been initialized (assigned a value). Variants that are empty return a VarType of 0. Variables containing zero-length strings (" ") aren't empty, nor are numeric variables having a value of 0. Ethernet Widely used type of local area network based on the CSMA/CD bus access method (IEEE 802.3). Event data displayed by time As an alternative to viewing event trend data by event number, it is possible to see event trends across a time- line. When event trends are shown by time, the trend graph includes a start and end time and enables operators to see both the time of a triggered event, and the elapsed period between events. This data can also be dis- played on the same graph as a periodic trend. event trend/SPC To construct an event trend/SPC, takes a sample when a particular event is triggered (in the plant). This sample is displayed in the window. The event must then reset and trigger again, before the next sample is taken. Events are identified by the event number. . expression A statement (or group of statements) that returns a value. An expression can be a single variable, a mathemat- ical formula, or a function. Glossary 303 F file server A computer with a large data storage capacity dedicated to file storage and accessed by other client computers via a network. On larger networks, the file server runs a special network operating system. On smaller instal- lations, the file server may run a PC operating system supplemented by peer-to-peer networking software. full duplex Simultaneous two-way (in both directions) independent transmission (4 Wires). G generic protocol A pseudo-protocol supported by disk I/O devices that provides a convenient way to represent disk data. The generic protocol is not a real protocol (communicates with no physical I/O device). Genie If you have numerous devices of the same type (e.g., 100 centrifugal pumps), the display graphics for each will behave in much the same way. Using Genies, you only have to configure common behavior once. The graphics can then be saved as a Genie and pasted once for each device. Genie controller A Genie that references a Super Genie (using a Super Genie function). Using a Genie controller, the same Super Genie can be used over and over for different applications. global Cicode variable Can be shared across all Cicode files in the system (as well as across include projects). global client A control client used to monitor information from several systems or sections (using clusters). graphics bounding box A faint (grayed) dotted rectangular box outline defining the exterior boundary region of a graphic object. Only visible and active when the graphics object is selected and being resized. Contains sizing handles in each cor- ner and (if sized large enough to display) one in the centre of each side. graphics page A drawing (or image) that appears on a workstation to provide operators with control of a plant, and display a visual representation of conditions within the plant. group (of objects) allows you to group multiple objects together. Each group has a unique set of properties, which determine the runtime behavior of the group as a whole. Glossary 304 H half duplex Transmission in either direction, but not simultaneously. histogram A bar graph that shows frequency of occurrence versus value. Quite often the data is fitted to a distribution such as a normal distribution. . I I/O Device An item of equipment that communicates with plant-floor control or monitoring equipment (sensors, control- lers, and so on). The most common I/O devices are PLCs (programmable logic controllers); however, supports a wide range of I/O devices, including loop controllers, bar code readers, scientific analyzers, remote terminal units (RTUs), and distributed control systems (DCS). can communicate with any I/O device that has a standard communications channel or data highway. I/O device address The (logical) location of the I/O device in the system. Each I/O device must have a unique address in the system, unless the I/O device is defined in other servers (to provide redundancy). If redundancy is used, the I/O device must then have the same I/O device name, number, and address for each server. I/O device variable A unit of information used in . Variables are stored in memory registers in an I/O device. exchanges informa- tion with an I/O device by reading and writing variables. refers to I/O device variables by their register ad- dresses. I/O devices usually support several types of variables; however, the most common are digital variables and integer variables. I/O server A dedicated communications server that exchanges data between I/O devices and control clients. No data pro- cessing is performed by the I/O server (except for its local display). Data is collected and passed to the control clients for display, or to another server for further processing. All data sent to an I/O device from any computer is also channelled through the I/O server. If data traffic is heavy, you can use several I/O servers to balance the load. include file (.CII) There is a maximum number of characters that you can type in a Command or Expression field (usually 128). If you need to include many commands (or expressions) in a property field, you can define a separate include file that contains commands or expressions. An include file is a separate and individual ASCII text file contain- ing only one sequence of commands or expressions that would otherwise be too long or complicated to type into the command or expression field within . The include file name is entered instead, and the whole file is activated when called. integer variable (Cicode) A 4-byte (32-bit) data type allowing values from 2,147,483,648 to 2,147,483,647. Glossary 305 integer variable (I/O device) A 2-byte data type, allowing values from -32,768 to 32,767, that is used to store numbers (such as temperature or pressure). Some I/O devices also support other numeric variables, such as real (floating point) numbers, bytes, and binary-coded decimals. Internet Display Client Allows you to run projects over the Internet from a remote location. It is basically a "runtime-only" version of : you can run your project from that computer, just as you would from any normal client. interrupt An external event indicating that the CPU should suspend its current task to service a designated activity. IP address A unique logical address used by the Internet Protocol (IP). Contains a network and host ID. The format is called dotted decimal notation, and is written in the form: w.x.y.z. K keyboard command Consist of a key sequence that an operator enters on the keyboard, and an instruction (or series of instructions) that executes when the key sequence is entered. Keyboard commands can be assigned to an object or page, or they can be project-wide. knowledge base Provides high-level technical information beyond the scope of standard technical documentation that is up- dated regularly and available at http://www.citect.com. kurtosis An index indicating the degree of peakedness of a frequency distribution (usually in relation to a normal dis- tribution). Kurtosis < 3 indicates a thin distribution with a relatively high peak. Kurtosis > 3 indicates a distri- bution that is wide and flat topped. L language database When a project is compiled, creates a language database (dBASE III format) consisting of two fields: native and local. Any text marked with a language change indicator is automatically entered in the native field. You can then open the database and enter the translated text in the local field. link A copy of a library item, possessing the properties of the library original. Because it is linked, the copy is up- dated whenever the original is changed. local area network (LAN) A system that connects computers to allow them to share information and hardware resources. With real-time LAN communication, you can transfer data, messages, commands, status information, and files easily between computers. Glossary 306 local Cicode variable Only recognized by the function within which it is declared, and can only be used by that function. Local vari- ables must be declared before they can be used. Any variable defined within a function (i.e., after the function name) is a local variable, therefore no prefix is needed. Local variables are destroyed when the function exits and take precedence over global and module variables. local language The language of the end user. Runtime display items such as alarm descriptions, button text, keyboard/alarm logs, graphic text, Cicode strings and so on can be displayed in the local language, even though they may have been configured in the language of the developer (native language). long BCD variable (I/O device) A 4-byte (32-bit) data type, allowing values from 0 to 99,999,999. The four bytes are divided into eight lots of four bits, with each lot of four bits representing a decimal number. For example the binary number 0011 rep- resents decimal 3. Thus the BCD 0011 0011 0011 0011 0011 0011 0011 0011 represents 33,333,333. long variable (I/O device) A 4-byte (32-bit) data type allowing values from 2,147,483,648 to 2,147,483,647. low and low low alarms Defined by specifying the values of the variable that trigger each of these alarms. As a low alarm must precede a low low alarm, the low alarm no longer exists when the low low alarm is triggered. Note that the variable must rise above the deadband before the alarm becomes inactive. . M maximum request length The maximum number of data bits that can be read from the I/O device in a single request. For example, if the maximum request length is 2048 bits, the maximum number of integers that can be read is: 2048/16 = 128. millisecond trending Allows you to use a trends sample period of less than one second. mimic A visual representation of a production system using an organised set of graphical pages. . module Cicode variable Specific to the file in which the variable is declared. This means that it can be used by any function in that file, but not by functions in other files. By default, Cicode variables are defined as module, therefore prefixing is not required (though a prefix of MODULE could be added if desired). Module variables should be declared at the start of the file. multi-digital alarms Use combinations of values from three digital variables to define eight states. For each state, you specify a de- scription (e.g., healthy or stopped), and whether or not the state triggers an alarm. Glossary 307 N native language Generally the language of the project developer. Display items such as alarm descriptions, button text, key- board/alarm logs, graphic text, Cicode strings and so on can be configured in the native language, and dis- played, at runtime, in the language of the end-user (local language). network A group of computers and peripheral devices, connected through a communications link. Data and services (e.g., printers, file servers, and modems) can be shared by computers on the network. A local network of PCs is called a LAN. network computer A computer running that is connected to a LAN through a network adaptor card and network software. . Network Dynamic Data Exchange (NetDDE) Enables communication between Windows applications on separate computers connected across a common network. nodes A structural anchor point for a graphic object, usually visible as a small square box superimposed over a graph- ic. Nodes will be located separately at the start, at the end, and at every change in direction within a graphic object. . normal distribution Also known as a `bell' curve, the normal distribution is the best known and widely applicable distribution. The distribution is symmetrical and popularly represents the laws of chance. 68.27% of the area lies between -1 sig- ma and +1 sigma, 95.45% between -2 sigma and+2 sigma, and 99.73% between -3 sigma and +3 sigma. The val- ues of skewness and kurtosis are used to provide quantitative measures for normality. Assuming that at least 20 samples are used to construct a distribution, a good rule of thumb is to accept the data as a normal distri- bution when, -1.0 = skewness = 1.0 2 = kurtosis = 4. null value Indicates that a variant contains no valid data. Variants that are null return a VarType of 1. Null is not the same as empty, which indicates that a variant has not yet been initialized. It is also not the same as a zero-length string (" "), which is sometimes referred to as a null string. Null is not equivalent to zero or blank. A value of null is not considered to be greater than, less than, or equivalent to any other value, including another value of null. A boolean comparison using a null value will return false. O object Basic building blocks of a graphics page. Most objects possess properties that allow them to change dynami- cally under user-definable runtime conditions allowing them to provide animated display of conditions within the plant. Glossary 308 object ID (OID) An object ID associated with every tag in a project that uniquely identifies the tag for use by tag-based drivers, automatically generated at compile. It is used instead of the actual address of the register (which is what most other drivers use to read from and write to I/O devices). object variable (Cicode) An ActiveX control that can only be declared with local, module, or global scope. open database connectivity (ODBC) Allows applications to access data in database management systems using structured query language (SQL) to access data. P pack Packing a database re-indexes database records and deletes records marked for deletion. If you edit your da- tabases externally to , you should pack the database afterwards. page environment variable A read-only variable associated with a particular page When you make the association, you name the variable, and assign it a value. When the page is opened during runtime, creates the variable. Its value can then be read. When the page is closed, the environment variable memory is freed (discarded). parity A communications error-checking procedure. The number of 1's must be the same (even or odd) for each group of bits transmitted without error. periodic trend A trend that is sampled continuously at a specified period. You can also define a trigger (an event) to stop and start the trend (when a specified condition occurs in the plant). persistence cache Cache data saved to a computer hard disk that allows an I/O server to be shut down and restarted without having to re-dial each I/O device to get its current values. This cache consists of all the I/O device's tag values. PLC interface board You can sometimes install a PLC interface board in your server. A proprietary interface board is usually sup- plied by your PLC manufacturer, and you can connect it to a PLC or a PLC network. You can only use propri- etary interface boards with the same brand of PLC. point limit An individual digital (or analog) variable read from an I/O device. only counts physical points (and counts them only once, no matter how many times they are used). The point limit is the maximum number of I/O de- vice addresses that can be read and is specified by your license. When you run the point count of your project is checked against the point limit specified by your Hardware Key. port(s) Provide the communication gateway to your I/O device(s). primary Alarms Server The server that normally processes alarms. Glossary 309 primary Reports Server The server that normally processes reports. primary Trends Server The server that normally processes trends. project The elements of a monitoring and control system, such as graphics pages, objects, and so on. These elements are stored in files of various types; for example, graphics files for graphics pages, databases for configuration records, and so on. You use the compiler to compile the project into a runtime system. properties, object Describes the appearance of an object (size, location, color, and so on.) and its function (the command or ex- pression executed by the object, the privilege required to gain access to the object, and so on). protocol Messaging format consisting of a set of messages and guidelines used for communication between the server and an I/O device. The communication protocol determines how and the I/O device communicate; the type of data to exchange; rules governing communication initiation and termination; and error detection. proxi/proxy server Caches internet transactions to improve performance by reducing the average transaction times by storing query and retrieved information for re-use when the same request is made again. When an Internet display client (IDC) connects to a proxy server, that server provides the TCP/IP addresses necessary to access report server session information. PSTN A public switched telephone network is the network of all the world's public switched telephone networks. It is now primarily digital and includes mobile as well as fixed telephones. R rate of change alarms Triggered when the value of the variable changes faster than a specified rate. The alarm remains active until the rate of change falls below the specified rate. Deadband does not apply to a rate of change alarm. real variable (Cicode) Real (floating point) is a 4-byte (32-bit) data type allowing values from 3.4E38 to 3.4E38. Use a real variable to store numbers that contain a decimal place. real variable (I/O device) Real (floating point) is a 4-byte (32-bit) data type, allowing values from 3.4E38 to 3.4E38. Use a real variable to store numbers that contain a decimal place. record name Usually the primary property of a database record, referenced in system through its name. Database record names must be unique for each type of database record. Sometimes you can use identical names for different record types. However, to avoid confusion, you should use a unique name for each database record in your application.When you specify a name for a database record, the name must begin with an alphabetic character (A-Z, a-z) and cn only include alphanumeric characters (A-Z, a-z, 0-9) and the underscore character (_). For example, "Pressure," "Motor_10," and "SV122_Open" are all valid database record names. Each database record name can contain up to 16 characters.Database record names are not case-sensitive, so "MOTOR_1," "Motor_1" Glossary 310 and "motor_1" are all identical database record names. For this reason use a meaningful name for any database record as well as the necessary naming conventions. redundancy A method of using the hardware in a system such that if one component in the system becomes inoperative, control of the system is maintained, and no data is lost. remote communications Interaction between two computers through a modem and telephone line. remote terminal A terminal remote from the computer that controls it. The computer and remote terminal communicate via a modem and telephone line. report A statement or account of plant-floor conditions. reports can be requested when required, on a periodic basis, or when an event occurs. report format file Controls the layout and content of reports. The format file is edited using a text editor and can be in either ASCII or RTF format. Reports Server Controls report processing. You can request reports at any time or when specific events occur. reserved words Words that cannot be used as a name for any database record or Cicode function. RJ11 A type of IDC plug commonly used in data communications. Recognizable as the style of data plug used in phone line and handset connectors. RJ11 is a 6/4 plug with 6 contacts but only 4 loaded. RJ12 A type of IDC plug commonly used in data communications. Recognizable as the style of data plug used in phone line and handset connectors. RJ12 is a 6/6 plug with 6 contacts. RJ45 A type of IDC plug commonly used in data communications. Recognizable as the style of data plug used in phone line and handset connectors. RJ45 is often used with 10baseT and is an 6/8 plug with 8 contacts. RS-232 An industry standard for serial communication. The standard specifies the lines and signal characteristics that are used to control the serial transfer of data between devices. RS-422 An industry standard for serial communication. The standard specifies the lines and signal characteristics that are used to control the serial transfer of data between devices. RS-422 uses balanced voltage interface circuits. RS-485 An industry standard for serial communication. The standard specifies the lines and signal characteristics that are used to control the serial transfer of data between devices. RS-485 uses balanced voltage interface circuits in multi-point systems. runtime system The system that controls and monitors your application, process, or plant. The runtime system is sometimes called the Man-Machine Interface (MMI), and is compiled from a project. Glossary 311 S scalable architecture A system architecture that can be resized without having to modify existing system hardware or software. lets you re-allocate tasks as more computers are added, as well as distribute the processing load. schedule period Determines how often the I/O server contacts a scheduled I/O device to read data from it. . serial communication Uses the communication port on your computer or a high speed serial board (or boards) installed inside your computer. server A computer connected to an I/O device (or number of I/O devices). When is running, the server exchanges data with the I/O device(s) and distributes information to the other control clients as required. A local area network (LAN) computer that perform processing tasks or makes resources available to other client computers. In , cli- ent-server architecture distributes processing tasks to optimize performance. simplex transmission Data transmission in one direction only. skewness An index indicating the degree of asymmetry of a frequency distribution (usually in relation to a normal dis- tribution). When a distribution is skewed to the left (for example), then the tail is extended on that side, and there is more data on the left side of the graph than would be expected from a normal distribution. Positive skew indicates the distribution's mean (and tail) is skewed to the right. Negative skew indicates the distribu- tion's mean (and tail) is skewed to the left. slider control Allow an operator to change the value of an analog variable by dragging an object (or group) on the graphics page. Sliders also move automatically to reflect the value of the variable tag. soft PLC A pure software (virtual) PLC created by software and existing only within the computer memory. Usually provides a software interface for communication (READ and WRITE) operations to take place with the soft PLC. Also known as a `virtual field unit' or `virtual I/O device'. software protection uses a hardware key that plugs into the printer port of your computer to protect against license infringement. The hardware key contains the details of your user license. When you run , the point count in your project is checked against the point limit specified in the hardware key. standby Alarms Server The Server that processes alarms if the primary alarms server is unavailable. standby Reports Server The server that processes reports if the primary reports server is unavailable. standby Trends Server The server that processes trends if the primary trends server is unavailable. Glossary 312 stop bits The number of bits that signals the end of a character in asynchronous transmission. The number is usually 1 or 2. Stop bits are required in asynchronous transmissions because the irregular time gaps between transmitted characters makes it impossible for the server or I/O device to determine when the next character should arrive. symbol An object (or group of objects) stored in a library for later retrieval and use. By storing common objects in a library, you reduce the amount of disk space required to store your project, and reduce the amount of memory required by the run-time system. T task Includes operations such as I/O processing, alarm processing, display management, and Cicode execution. Any individual `instance' of Cicode is also a `task'. template A base drawing or time-saving pattern used to shape a graphics page. Each template contains base information for the page, such as borders and common control buttons. provides templates for all common page types. text box When text is added to a graphics page, it is placed in a text box. A text box has a number of handles, which can be used to manipulate the text object. thread Used to manage simultaneous execution of tasks in multitasking operating systems, enabling the operating system to determine priorities and schedule CPU access. timeout The period of time during which a task must be completed. If the timeout period is reached before a task com- pletes, the task is terminated. time-stamped alarms An alarm triggered by a state change in a digital variable. Time-stamped alarms have an associated register in the I/O device to record the exact time when the alarm changes to active. Use time-stamped alarms when you need to know the exact order in which alarms occur. time-stamped analog alarms Time stamped analog alarms work in the same way as analog alarms except that they are time stamped (with the Alarm On and Alarm Off times) using millisecond precision from the time kept by the field device (i.e. the RTU or PLC). The configuration details for time stamped analog alarms are exactly the same as for analog alarms. time-stamped digital alarms Time stamped digital alarms work in the same way as digital alarms except that they are time stamped (with the Alarm On and Alarm Off times) using millisecond precision from the time kept by the field device (i.e. the RTU or PLC). The configuration details for time stamped digital alarms are exactly the same as for digital alarms. tool tip A help message that displays in a pop-up window when an operator holds the mouse stationary over an object. Glossary 313 touch (object at runtime) An object is considered touched if an operator clicks it. Touch command Can be assigned to objects on graphics pages. Touch commands allow you to send commands to the runtime system by clicking an object. trend A graphical representation of the changing values of a plant-floor variable (or expression), or a number of vari- ables. . trend line The actual line on a trend that represents the changing values of a plant-floor variable (or expression). . trend plot Consists of a trend (or a number of trends), a title, a comment, scales, times and so on. Trends Server Controls the accumulation and logging of trend information. This information provides a current and histori- cal view of the plant, and can be processed for display on a graphics page or printed in a report. U UAC User Account Control. Security technology introduced in Windows Vista to enable users to run with standard user rights more easily. . unsigned integer variable (I/O device) A 2-byte (16 bit) data type, representing an integer range from 0 to 65,535. This is supported for all I/O devices that can use INT types. This means you can define any integer variable as an unsigned integer to increase the positive range. V variable type (Cicode) The type of the variable (INT (32 bits), REAL (32 bits), STRING (256 bytes), OBJECT (32 bits)). view-only client A computer configured with manager-only access to the runtime system. No control of the system is possible, but full access to data monitoring is permitted. virtual Behavioral identification rather than a physical one. For example, Windows 95 is a virtual desktop. Glossary 314 W wizard A facility that simplifies an otherwise complex procedure by presenting the procedure as a series of simple steps. 315 Index A acknowledgement, alarm 248 Add Cursor command 261 Add New Pens dialog box 263 Add Pane command 280, 295 Add Pen command 296 adding panes 280 pens 263 toolbar commands 26, 288 alarm acknowledgement 248 alarm label value 262 alarm pen types 249 alarm pens 248, 282 alarm states 248 alarm types 248 AlarmType enumeration 33 analog pens 246 automation model 31 Autoscale Vertical Axis command 295 autoscaling 295 Autoscroll command 257 autoscrolling 257 axis configuring 283 horizontal 243 vertical 245 AxisLabelType enumeration 34 B Back Half a Span command 294 Back One Span command 294 background color, configuring 278, 280 boolean terms during searches 263 C columns, configuring Object View 289 command system 29 CommandExecuted event 29, 40 commands Add Cursor 261 Add Pane 280, 295 Add Pen 296 adding new 26 Autoscale Vertical Axis 295 Autoscroll 257 Back Half a Span 294 Back One Span 294 Copy to Clipboard 273, 295 Copy to File 273 Edit Span 259, 294 Edit Vertical Scale 259, 294 editing 26 export 295 Forward Half a Span 294 Forward One Span 294 general 296 Help 296 interface 295 Load View 291, 293 Lock/Unlock Cursor Labels 262, 295 Lock/Unlock Pens 252, 295 Lock/Unlock Vertical Axis Scrolling 295 navigation 294 Print 296 Refresh Data 296 Remove Pane 295 Remove Pen 264, 296 Reset to Default Span 260, 294 Save View 290, 293 Show Properties 296 Show/Hide Cursor 261, 295 Show/Hide Cursor Labels 262, 295 Show/Hide Points 295 Synchronize to Now 257, 294 Toggle Auto-Scrolling 257, 294 Toggle Box Zoom 258, 294 Toggle Object View 268, 296 Toggle Span Lock 256, 294 Undo Last Zoom 258, 294 view 293 zoom 294 Zoom In 50% 257 Zoom in 50% 294 Zoom Out 50% 257 Zoom out 50% 294 compaction, data 241 comparison, trend 252 configuring appearance of pens 280 axes 283 chart panes 280 chart-wide properties 277 columns in Object View 289 cursor labels 286 Index 316 cursors 286 data connection 285 defaults 287 design time properties 25 general properties 278 gridlines 282 pen quality 284 refresh rate 278 report options 270, 272 server paths 279 toolbars 287 connection, data 285 context menu. See right-click menu 262 Copy to Clipboard command 273, 295 Copy to File command 273 copying data 273 Create method 29 creating custom commands 29 cursor labels 261, 286 CursorMoved event 41 cursors 261 configuring 286 custom commands 29 custom commands, adding 26 D data copying 273 exporting 273 data compaction 241 data connection, configuring 285 data request mode 285 data request rate, configuring 278 date/time axis 243 Daylight Savings 255 Daylight Savings time 244 defaults, configuring 287 deleting pens 264 design time properties, configuring 25 digital pens 247 display, time 243 E Edit Command dialog box 26 Edit Span command 259, 294 Edit Span dialog box 259 Edit Vertical Scale command 259, 294 Edit Vertical Scale dialog box 259 editing commands 26 effect, halo 252 end time, specifying 254 enumerations, automation model 32 Error event 42 ErrorNotifyCode enumeration 35 execution result 31 export commands 295 exporting data 273 F FileLocation enumeration 35 filtering pens 263 Fit to unit 256 fixed height for panes, specifying 280 Forward Half a Span command 294 Forward One Span command 294 G general commands 296 general properties, configuring 278 GetCommandSystem() property 29 graphics page, inserting onto 15 gridlines 245, 282 H halo effect 252 HatchStyle enumeration 35 Help command 296 HorizontalAxisChanged event 43 I IAlarmPen interface 54 IAlarmPen.AlarmType property 55 IAlarmPen.GetFillColor method 56 IAlarmPen.GetHatchColor method 56 IAlarmPen.GetHatchStyle method 57 IAlarmPen.LineColor property 58 IAlarmPen.LineWidth property 59 IAlarmPen.SetFillColor method 60 IAlarmPen.SetHatchColor method 61 IAlarmPen.SetHatchStyle method 62 IAnalogPen interface 62 IAnalogPen.LineColor property 63 IAnalogPen.LineInterpolation property 64 IAnalogPen.LineWidth property 65 ICommand interface 65 ICommand.ButtonType property 67 ICommand.CommandId property 67 ICommand.Enabled property 68 Index 317 ICommand.Pressed property 69 ICommand.Privilege property 70 ICommand.Tooltip property 66 ICommandSystem interface 70 ICommandSystem._NewEnum property 71 ICommandSystem.Count property 71 ICommandSystem.Create method 72 ICommandSystem.Execute method 73 ICommandSystem.Item property 74 ICommandSystem.ItemById property 74 ICommandSystem.Remove method 75 icons, custom 30 ICursors interface 75 ICursors._NewEnum property 76 ICursors.Count property 77 ICursors.Create method 78 ICursors.Item property 79 ICursors.ItemByName property 79 ICursors.RemoveAll method 80 IDigitalPen interface 80 IDigitalPen.Fill property 81 IDigitalPen.FillColor property 82 IDigitalPen.LineColor property 83 IDigitalPen.LineWidth property 84 inherit security settings 278 Insert ActiveX dialog box 15 interface commands 295 interfaces, automation model 53 interpolation 247, 281 IObjectView interface 84 IObjectView.BackgroundColor property 85 IObjectView.Columns property 86 IObjectView.ForeColor property 86 IObjectView.Height property 87 IObjectView.Items property 88 IObjectView.SelectedItem property 89 IObjectView.Visible property 90 IObjectViewColumn interface 90 IObjectViewColumn.Name property 90 IObjectViewColumn.Text property 91 IObjectViewColumn.Width property 92 IObjectViewColumns interface 92 IObjectViewColumns._NewEnum property 93 IObjectViewColumns.Add method 94 IObjectViewColumns.Count property 94 IObjectViewColumns.Hide method 95 IObjectViewColumns.Item property 96 IObjectViewColumns.ItemByName property 96 IObjectViewColumns.Remove method 97 IObjectViewColumns.Show method 98 IObjectViewItem interface 98 IObjectViewItem.Expanded property 99 IObjectViewItem.GetField method 100 IObjectViewItem.Items property 101 IObjectViewItem.PutField method 102 IObjectViewItem.Tag property 103 IObjectViewItems interface 103 IObjectViewItems._NewEnum property 103 IObjectViewItems.Count property 104 IObjectViewItems.Item property 105 IObjectViewPenItem interface 105 IObjectViewPenItem.BlockColor property 106 IObjectViewPenItem.Checked property 107 IObjectViewPenItem.Selected property 107 IPane interface 108 IPane.BackgroundColor property 109 IPane.Collection property 109 IPane.Delete method 110 IPane.FixedHeight property 111 IPane.Height property 112 IPane.Name property 113 IPane.Pens property 113 IPanes interface 114 IPanes._NewEnum property 114 IPanes.Count property 115 IPanes.Create method 116 IPanes.Item property 117 IPanes.ItemByName property 117 IPanes.RemoveAll method 118 IPen interface 119 IPen.AddSample method 120 IPen.AxisBackgroundColor property 121 IPen.BlockRepaint property 122 IPen.Clear method 123 IPen.Collection property 123 IPen.DataPoint property 124 IPen.DataServer property 125 IPen.Delete method 126 IPen.GetDefaultSpan method 127 IPen.GetHorizontalAxisTimeSpan method 129 IPen.GetInformation method 130 IPen.GetStatistic method 131 IPen.GetVerticalAxisSpan method 132 IPen.GoToNow method 132 IPen.Height property 133 IPen.HorizontalAxisColor property 134 IPen.HorizontalAxisResize property 135 IPen.HorizontalAxisScroll property 136 IPen.HorizontalAxisWidth property 137 IPen.HorizontalGridlinesColor property 138 IPen.HorizontalGridlinesStyle property 139 IPen.HorizontalGridlinesWidth property 139 Index 318 IPen.HorizontalMinorGridlinesColor property 140 IPen.HorizontalMinorGridlinesStyle property 141 IPen.HorizontalScrollBy method 142 IPen.HorizontalZoom method 143 IPen.IsDeleted property 143 IPen.IsSelected property 144 IPen.LocalTime property 145 IPen.Name property 146 IPen.PointsVisible property 147 IPen.PutHorizontalAxisTimeSpan method 148 IPen.PutVerticalAxisSpan method 149 IPen.RefreshData method 150 IPen.RequestMode property 151 IPen.ResetToDefaultSpan method 151 IPen.Select method 152 IPen.SetDefaultSpan method 153 IPen.SetQualityCompactionPointType method 154 IPen.SetQualityLineStyle method 155 IPen.SetVerticalAxisLabelValue method 156 IPen.Stacked property 157 IPen.TrendCursorLabelFillColor property 158 IPen.TrendCursorLabelLineColor property 158 IPen.TrendCursorLabelTextColor property 159 IPen.VerticalAxisAutoscale property 160 IPen.VerticalAxisColor property 161 IPen.VerticalAxisLabelType property 162 IPen.VerticalAxisResize property 163 IPen.VerticalAxisScroll property 164 IPen.VerticalAxisWidth property 165 IPen.VerticalGridlinesColor property 165 IPen.VerticalGridlinesStyle property 166 IPen.VerticalGridlinesWidth property 167 IPen.VerticalMinorGridlinesColor property 168 IPen.VerticalMinorGridlinesStyle property 169 IPen.VerticalScrollBy method 170 IPen.VerticalZoom method 171 IPen.Visible property 171 IPens interface 172 IPens._NewEnum property 172 IPens.Count property 173 IPens.Create method 174 IPens.Item property 175 IPens.ItemByName property 175 IPens.Pane property 176 IPens.RemoveAll method 177 IProcessAnalyst interface 29, 177 IProcessAnalyst.AdminPrivilegeLevel property 189 IProcessAnalyst.AutoScroll property 190 IProcessAnalyst.BackgroundColor property 191 IProcessAnalyst.BlockUpdates method 178 IProcessAnalyst.CommandSystem property 191 IProcessAnalyst.ContextMenu property 192 IProcessAnalyst.CopyToClipboard method 180 IProcessAnalyst.CopyToFile method 181 IProcessAnalyst.Cursors property 193 IProcessAnalyst.DataRequestRate property 194 IProcessAnalyst.DisplayRefreshRate property 195 IProcessAnalyst.Language property 196 IProcessAnalyst.LastSelectedPen property 197 IProcessAnalyst.LoadFromFile method 183 IProcessAnalyst.LockedPens property 198 IProcessAnalyst.ObjectView property 200 IProcessAnalyst.Panes property 200 IProcessAnalyst.PrimaryPath property 201 IProcessAnalyst.PrintAll method 183 IProcessAnalyst.SaveToFile method 184 IProcessAnalyst.SecondaryPath property 202 IProcessAnalyst.ShowProperties method 185 IProcessAnalyst.SubscribeForPropertyChange method 186 IProcessAnalyst.SynchroniseToNow method 187 IProcessAnalyst.Toolbars property 203 IProcessAnalyst.UnBlockUpdates method 179 IProcessAnalyst.UnsubscribePropertyChange method 188 IProcessAnalyst.WritePrivilegeLevel property 204 IProcessAnalyst.ZoomMode property 205 IToolbar interface 205 IToolbar.Buttons property 206 IToolbar.Visible property 207 IToolbarButton interface 209 IToolbarButton.CommandId property 210 IToolbarButtons interface 210 IToolbarButtons._NewEnum property 210 IToolbarButtons.Add method 211 IToolbarButtons.Count property 212 IToolbarButtons.Item property 212 IToolbarButtons.Remove method 213 IToolbarButtons.RemoveAll method 214 IToolbars interface 207 IToolbars._NewEnum property 208 IToolbars.Count property 209 IToolbars.Item property 208 ITrendCursor interface 214 ITrendCursor.Collection property 215 ITrendCursor.Color property 216 ITrendCursor.Delete method 216 ITrendCursor.GetValue method 218 ITrendCursor.LabelsLocked property 218 ITrendCursor.Name property 219 ITrendCursor.PenLabelHeight property 220 ITrendCursor.PenLabelVisible property 221 Index 319 ITrendCursor.PenLabelWidth property 222 ITrendCursor.PenLabelX property 223 ITrendCursor.PenLabelY property 224 ITrendCursor.Position property 225 ITrendCursor.Visible property 226 ITrendCursor.Width property 226 L label value, alarm 262 legends, report 270 line styles 243 LineStyle enumeration 36 LineType enumeration 36 Load dialog box 291 Load View command 291, 293 loading views 291 Lock pens check box 278 Lock/Unlock Cursor Labels 295 Lock/Unlock Cursor Labels command 262 Lock/Unlock Pens command 252, 295 Lock/Unlock Vertical Axis Scrolling command 295 locked pens 252 M main page (Properties dialog) 276 main toolbar 239 menu, right-click 262 mode, request 242 model, automation 31 mouse, using for interaction 263 MouseClick event 43 MouseDoubleClick event 44 multi-language support 17 multiple samples 241 N navigating time 257 navigation commands 294 navigation toolbar 254 New Command dialog box 26 Now indicator 244 number of samples 278 O Object View 268 basic functions 268 configuring columns 289 creating columns 27 default columns for 268 editing columns 27 Object View (Properties dialog) 277 OVColumnAdded event 45 OVColumnRemoved event 45 overlaying pens 246 OVItemAdded event 46 OVItemChecked event 47 OVItemRemoved event 47 OVItemSelected event 48 P panes adding 280 configuring 280 paths, server, configuring 279 Pen Details box 265 PenCreated event 49 PenDeleted event 49 PenNameMode enumeration 37 PenRenamed event 50 pens adding 263 alarm 248 analog 246 appearance 280 axes, configuring 283 deleting 264 digital 247 filtering 263 gridlines, configuring 282 locked 252 overlaying 246 quality, configuring 284 selecting 252 stacking 246 unlocked 252 viewing details 265 PenSelectionChanged event 51 PenType enumeration 37 permissions 16 persistence 30 point styles 241 pointer, mouse 263 PointType enumeration 37 primary file server 279 Print command 296 Print dialog box 270 printing reports 270 privilege level, configuring 278 Process Analyst button 15 Index 320 Properties dialog box 275 property tree 276 PropertyChanged event 51 Q quality configuring pen 284 QualityCompactionType enumeration 38 QualityType enumeration 38 R Refresh Data command 296 refresh rate, configuring 278 Remove Pane command 295 Remove Pen command 264, 296 removing chart panes 280 toolbar commands 288 report legends 270 report options, configuring 270, 272 reports 270 configuring 270 printing 270 request mode, data 242, 285 RequestMode enumeration 39 Reset to Default Span command 260, 294 result, execution 31 right-click menu 262, 276 S samples, number of 278 Save Process Analyst View dialog box 290 Save View command 290, 293 saving views 290 scaling 253 scrolling 252 security 16 selecting pens 252 time span 256 server paths, configuring 279 Shift by unit 256 Show Properties command 296 Show/Hide Cursor command 261, 295 Show/Hide Cursor Labels command 262, 295 Show/Hide Points command 295 Span Picker 256 stacked pens 246 standby file server 279 start time, specifying 254 states, alarm 248 statistical analysis options (reports) 270 stepped interpolation 247, 281 straight interpolation 247, 281 styles line 243 point 241 Synchronize to Now command 257, 294 system, command 29 T tag properties, viewing 265 time display 243 time format 254 time span editing 259 term defined 256 time, navigating 257 Toggle Auto-Scrolling command 294 Toggle Auto-scrolling command 257 Toggle Box Zoom command 258, 294 Toggle Object View command 268, 296 Toggle Span Lock command 256, 294 toolbar, navigation 254 ToolbarButtonType enumeration 39 toolbars adding commands to 288 changing order of commands 288 configuring 287 removing commands from 288 toolbars (Properties dialog) 276 Tooltip text 26 tree, property 276 types, alarm 248 types, alarm pen 249 U Undo Last Zoom command 258, 294 universal time coordinate (UTC) format 283 unlocked pens 252 unstacked pens 246 UpdateCommand event 30, 52 V value, alarm label 262 variable height for panes, specifying 280 vertical (value) axis 245 VerticalAxisChanged event 52 Index 321 view commands 293 viewing pen details 265 views 289 loading 291 saving 290 Z zoom commands 294 Zoom In 50% command 257 Zoom in 50% command 294 Zoom Out 50% command 257 Zoom out 50% command 294
Comments
Copyright © 2025 UPDOCS Inc.