100% found this document useful (1 vote)

927 views321 pages

CitectSCADA Process Analyst PDF

Hướng dẫn thiết kế mạng scada vijeo citect

Uploaded by

Quang Bách

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

100% found this document useful (1 vote)

927 views321 pages

CitectSCADA Process Analyst PDF

Hướng dẫn thiết kế mạng scada vijeo citect

Uploaded by

Quang Bách

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 321

v7.

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 replacement 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.

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 Microsoft 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 registered 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

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

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

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 applications. In these situations CitectSCADA is still required.
See Also
Configuring the Process Analyst Control from Graphics Builder | Security and Permissions
| Multi-language Support | Persistence | Backing up Projects

Configuring the Process Analyst Control from Graphics Builder

Being an ActiveX control, you can insert the Process Analyst onto a CitectSCADA graphics
page. To do this, do one of the following:
In Graphics Builder, choose Edit | Insert ActiveX Control. The Insert ActiveX dialog
box appears. Double-click the Citect Process Analyst Control item in the ActiveX Controls list box. The control is inserted onto the graphics page and the Properties dialog
box appears.
Click the Process Analyst button in the Graphics Builder toolbox.

After inserting the Process Analyst into a page, you can resize it into position. To view the
configuration pages for the Process Analyst, double-click the Process Analyst control. For
details on configuring the design time properties for the Process Analyst, see Configuring
Process Analyst Design Time Properties.
See Also
Persistence

Tag Association
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:
Double-click the ActiveX object. The Properties dialog box appears.
Click the Tag Association tab.
Select a property from the Properties list.
Click the Wizard | Insert Tag button.
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 allowing access to certain Process Analyst features based on the privilege level of the currently
logged in Operator.
15

Chapter: 1 Integration with CitectSCADA

The Process Analyst has nine privilege levels. Privilege level zero (0) indicates there is no
security and any user can perform the function. Levels 1-8 map directly to the eight (8) privilege levels of security provided by CitectSCADA. The Process Analyst, by default, assumes the area of the page that it is situated on; this can be changed in the Graphics Builder.
So if an operator has area access for the page and has privilege level 1, and the function they
want to use is level 2, the function will be unavailable. If the operator had level 2, the function would then become available. The Process Analyst also supports the CitectSCADA Hierarchical Privilege security option.
Security can be applied to the following features:
Administration; for details, see Administration privilege.
Commands; for details, see Command privilege.
Saving Process Analyst views (write privilege); for details, see Write privilege.

Administration privilege
The Process Analyst also uses an Administration privilege level to disable engineer-oriented features at run time. For example, the ability to add new custom commands and so on
are all disabled if the Operator does not meet the required privilege level. The Administration privilege level should never be zero on a running system as this would expose properties to an Operator, which could adversely affect the performance of the client and/or
server (for example, Number Of Samples property).
The features that are disabled when an operator does not meet the Administration privilege level include:
Add Pen context menu in Property dialog box.
New/Edit/Delete command (includes changing the privilege of commands).
New/Delete Column.
Data Refresh Rate property.
Display Refresh Rate property.
Number Of Samples property.
Server Paths tab.
Server field on Connection tab.
Tag field on Connection tab.
To modify the Administration privilege level, see Configuring Chart-wide Properties.

Command privilege
The Process Analyst allows a privilege level to be assigned to each command (standard or
custom command). If an Operator does not have the required privilege level to use that
command, the associated toolbar button is disabled and cannot be executed.
See Also
Editing Existing Custom Commands

Write privilege
The Process Analyst uses a concept of "write" privilege level to control whether an operator
can save Process Analyst views to a location other than "My documents". These views can
then be loaded into the Process Analyst later by any Operator. The write privilege is set at
design time on the Server Paths property page located on the root Process Analyst node in
the Property pages dialog box. If the write privilege level is set to zero (0), any operator can
16

Chapter: 1 Integration with CitectSCADA

save to any location. If the write privilege is any other level, the Operator must have that
privilege level to be able to save an Analyst view to a location other than "My Documents".
See Also
Configuring server paths | Working with Views | Process Analyst View Synchronization

Multi-language Support
The Process Analyst supports the CitectSCADA multilanguage ability of changing the user
interface language dynamically at run time. If the language is changed in CitectSCADA,
the Process Analyst will change its language to match.
The process of configuring the Process Analyst for multiple languages is different from that
of CitectSCADA. This section describes how to localize the Process Analyst user interface
and get it to work with CitectSCADA.

Understanding the Process Analyst resources

The Process Analyst uses a special file, called Resources.dll, to store all of its display strings
and dialog boxes. This file holds the native translations for your version of the Process Analyst; these native translations are considered the default language. For example, the Japanese version of the Process Analyst will contain Japanese resources inside the Resources.dll
file.
A separate Resources.dll file must be created for each individual language that you want
to support in your system. The file should be renamed using a special format to indicate the
language. The Process Analyst expects the file to be named Resources_<LanguageCode>.dll,
where <LanguageCode> is the unique identifier of your dll.
For example, if you are creating French resources, your dll should be named
Resources_fr.dll. CitectSCADA uses the RFC 1766 standard for specifying culture names.
See Also
Creating your own Process Analyst resource.dll
All language Resources*.dll files must be placed in the same directory as the Analyst.dll
file.
The example below shows a system that contains English as the default, and has alternative
languages of French, German and Chinese.
Resources.dll (default - any language, 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 allow 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:
17

Chapter: 1 Integration with CitectSCADA

LanguagePath.<dbf>=<ProcessAnalystLanguage>

where <dbf> is the name of a specific CitectSCADA language translation database, and
<ProcessAnalystLanguage> is the language code of the resources.dll file that has the equivalent translations.
For example,
[ProcessAnalyst]
LanguagePath.French=fr
LanguagePath.Chinese=zh-CN
LanguagePath.German=de

The last step is to verify each of your machines contains the necessary language fonts. Windows XP and Windows 2000 both provide facilities to add the necessary languages to your
machine via the Regional and Language Options dialog box, accessible from the Control
Panel. This step is essential if you want to use Asian languages on an English operating system. See Creating your own Process Analyst resource.dll for details on adding languages
to your system.
With the .ini file now configured, languages installed, and the Resource.dll files in place
when the SetLanguage Cicode function is called, CitectSCADA and the Process Analyst will
automatically change into the selected language.

Manually switching languages

The Process Analyst can also switch languages by itself using the IProcessAnalyst.Language property. You can call this property directly from Cicode, for example.
Note: Using this method will only switch the Process Analyst language and not the one
used by CitectSCADA. See IProcessAnalyst.Language [Property] [Get/Set].

Specifying languages for the Web Client

A Process Analyst running inside a CitectSCADA Web Client also supports run time language switching, but you must configure the languages that the Web Client will download
to the client machine.
To configure the languages to download:
Create a zip file in the CitectSCADA\bin folder called bin.zip.
Add to the zip file all the language resource DLL files that you want the client to download and use. (You can find these files in your \Program Files\Common Files\Citect folder.)
Note: The bin.zip file and its contents are not version-checked. This means you must
manually remove the bin.zip from the Web Client machines if your server contains a
more recent bin.zip file. To do this:
1. Find the installation directory of the Analyst.dll file on your Web Client machines
and look for a file called bin.zip in this directory.
2. Delete this file.
3. Reconnect to the Web server to download the latest bin.zip file.

Creating your own Process Analyst resource.dll

To create your own resources dll, you need to do the following:
Install the specific languages you are localizing on your Windows system.
Set your system to use that specific language.
18

Chapter: 1 Integration with CitectSCADA

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.
Open Control Panel and double-click Regional and Language Options.
Click the Languages tab.
If localizing for East Asian languages, select the Install files for East Asian languages
check box, then click OK.
Once the languages are installed, click the Languages tab in the Regional and Language
Options dialog box.
Click Details in the Text services and input languages section to display the Text Services and Input Languages dialog box.

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 system, return to the Regional and Language Options dialog box after logging back into
Windows. Be sure to login as an Administrator.
Click the Advanced tab in the Regional and Language Options dialog box.
Select the language you want from the menu in the Language for Non-Unicode Programs section.
Click Apply and then OK (you may need to restart your system).

Chapter: 1 Integration with CitectSCADA

Setup for localization on Windows 2000

You must have Administrator privileges to perform the following setup.
Open Control Panel and double-click Regional Options.
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.
Click the Input Locales tab.

Verify that your language is listed in the Installed input locals list.
Click back to the General tab.
Click Set default to display the Select System Locale dialog box.
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:
Click EN to display the input language option menu.
20

Chapter: 1 Integration with CitectSCADA

Select the language you want to use (to work correctly with Visual Studio, this should
match the language you selected in Step 8 of the Windows XP setup and Step 7 of the
Windows 2000 setup). This might display a language-specific IME editor, which allows
you to select characters to use in your translations.
Localizing the Process Analyst resource dll
Once you have set up your system to cope with multiple languages, you can begin localizing. Do the following:
Open Microsoft Visual Studio 6.
Choose File | Open.

Browse to the location of the Process Analysts Resources.dll file. By default it is located
at C:\Program Files\Common Files\Citect\.
Verify that the Files of type menu has Executable Files (.exe;.dll;*.ocx) selected.
Verify that the Open as menu has Resources selected.
Select Resources.dll and click Open.

Save the file under a new name. For example, if you are localizing for Japanese, use
Resources_ja-JP.dll. See Understanding the Process Analyst resources for naming conventions.

Chapter: 1 Integration with CitectSCADA

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:
Expand the Dialogs folder in the tree.
Double-click a dialog to edit.
Select an item of text and right-click to display the properties for that item.
Enter your replacement text into the Caption field.
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:
Expand the String Table folder in the tree.
Double-click the String Table entry. This will display a table showing you all the strings
of the Process Analyst.
Double-click an entry to display the Properties dialog box.
Type in the replacement text in the Caption box.
Click the Close button in the top-right corner of the dialog box.
Note: When translating strings, if a string contains "%s", "%x", "%d" and so on, do not remove or replace those symbols as they are important to the Process Analyst.

Persistence
Persistence refers to saving the state (properties, pens, and so on) of the Process Analyst to
disk. CitectSCADA and the Process Analyst provide the following methods of persistence:
Saving as part of a 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,
22

Chapter: 1 Integration with CitectSCADA

most importantly, the security of the Process Analyst since these will become the default
settings of the Process Analyst when your page is displayed at run time.
When a page containing the Process Analyst is saved in the Graphics Builder all the properties you configured on the Process Analyst will be stored within the Graphics Builder
page.
Note: When defining new custom toolbar buttons, any icon you assign will be copied and
also stored within the Graphics Builder page. This allows your custom toolbar buttons to
work on any machine.

Using the Save View toolbar button

This feature is valid only at run time and allows operators to save the current state of the
Process Analyst (called a view) to a standalone file. These files can be loaded during run
time, and are an efficient way to store commonly used pen configurations.

Using the SaveToFile automation method

This feature is valid only at run time and allows a user to write Cicode to save the current
state of the Process Analyst to a standalone file, referred to as an Analyst view. These files
can be loaded during run time using the LoadFromFile automation method (or the Load
View toolbar button). Views and are an efficient way to store commonly used pen configurations.

Saving between 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 ActiveX data between page transitions to save the state of an ActiveX control when you
switch between pages.
Enabling this option causes CitectSCADA to write a temporary file to the CitectSCADA
Data directory in the format of <Event class>.stg whenever you leave a page that contains
an ActiveX object (for example, the Process Analyst). When you reenter the page, CitectSCADA looks for that same file and, if found, will load the settings from it. These files
only exist while CitectSCADA run time is running. When you shut down CitectSCADA,
the temporary *.stg files are deleted.
To save between page transitions:
Double-click the Process Analyst ActiveX control you want to change. The Properties
dialog box appears.
Click the Access tab.
Click the Identification tab. The Identification panel appears.

Chapter: 1 Integration with CitectSCADA

In the Persistence area, select the Persist ActiveX data between page transitions check
box, and then click Apply.

Resetting back to the default state

You can reset the original configuration of the Process Analyst control by calling the Cicode
function ObjectResetState. This function takes the object handle of the Process Analyst
control, which you retrieve by using the Cicode function ObjectByName.

Backing up Projects
When you save views to the Local storage location, the Process Analyst will create a *.pav
file in an Analyst Views subfolder under your project directory. If your project contains Analyst views, you should verify that the Save sub-directories option is selected in Citect Explorer before backing up your project.

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, usually 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 Object 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:
On the Toolbars page of the Properties dialog box, click New. The New Command dialog box appears.

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.
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.
Click Browse and navigate to the icon to represent the new command. The icon image
appears on the toolbar command button.
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.
25

Chapter: 2 Configuring Design Time Properties

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
Open the Properties dialog box and click the Toolbars tab.
Select the command you want to edit in the Available toolbar buttons list box, and then
click Edit. The Edit Command dialog box appears.

If required. click Browse to navigate to a new icon to use for the command.
If required, edit the Tooltip text. The maximum length for Tooltip text is 64 characters.
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 existing columns (run time or design time). Object View columns display information about
your pens. All these configuration tasks are performed by using the Citect Process Analyst
Properties dialog box.
To create an Object View column:
Click the Object View tab. The Object View panel appears.
Click New. The New Column dialog box appears.

Chapter: 2 Configuring Design Time Properties

Enter a Name ID for the column. The value is used to reference the column in code.
Specify a Width.
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:
Select the column you want to edit, and then click Edit. The Edit Column dialog box appears.
Modify the information as required, and then click OK.
See Also
Configuring the Object View

Process Analyst View Synchronization

* 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

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 GetCommandSysfrom the IProcessAnalyst interface. For details, see IProcessAnalyst Interface.

tem()

Custom Commands
Custom commands are defined in the Process Analyst, but must be implemented in Cicode.
You define commands by using the ICommandSystem- > Create method, or by using the
New button on the Toolbar property page.
To implement the command, you must respond to the event CommandExecuted (and optionally UpdateCommand). Both of these events notify you of the ID of the command which needs
to be handled.

CommandExecuted
When an operator presses the toolbar button representing your command, it will trigger
this event. This is your opportunity to execute the desired functionality of the command.
This will not be triggered if the logged-in user fails to meet the required privilege level. Be
aware that this is an asynchronous operation.

UpdateCommand
When the Process Analyst requires the Enable state or pressed states of its toolbar buttons
to be refreshed, this event will be triggered. This will not be triggered if the logged-in user
fails to meet the required privilege level. Note that this is asynchronous operation.
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

Chapter: 4 Automation Model

The automation model allows applications or solutions to programmatically configure the
Process Analyst controls appearance, performance, and behavior. The automation model
also allows code, via automation events, to be attached to events fired from the Process Analyst Control and perform custom behavior.
The automation model allows almost every visual aspect of the control to be configured, as
well as performance. It is simple and follows a traditional object-oriented approach (see below).
To view information for an interface, click the name of the interface in the illustration below. For example, to view information for the IPens interface, click IPens.

Execution Results
Each property and method listed in the automation model will return one of the following
results upon execution. The exact meaning is described in the Execution Result section for
each property or method.
Execution Result

Cicode

VBA

C++

InvalidArgument

274

E_INVALIARG

GeneralFailure

356

2147500037

E_FAIL

PathNotFound

356

STG_E_PATHNOTFOUN
D

Success

S_OK

Errors are captured differently in Cicode and VBA. The following code examples show
how to trap and handle errors in VBA and Cicode.
[VBA]
Sub VBATest(myObject As Object)
On Error Goto errHandler
myObject.<function>
Exit Sub
errHandler:
Print Err.Number, Err.Description
Resume Next
End Sub

Chapter: 4 Automation Model

[Cicode]
FUNCTION Test1(OBJECT hObject)
ErrSet(1); // Enable User error checking (disabled HW alarm)
IF ObjectIsValid(hObject) THEN
_ObjectCallMethod(hObject, "<function>");
error = IsError();
errorMessage = IntToStr(error)
IF (error <> 0) THEN
Message("An error occured", errorMessage, 0);
END
END
ErrSet(0); // Enable hardware alarm reporting of errors
END

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

Description

Value

AlarmType_Digital

The tag is digital alarm

AlarmType_Analog

The tag is an analog alarm

AlarmType_Advanced

The tag is an advanced alarm

AlarmType_TimeStamped

The tag is a time-stamped alarm

AlarmType_MultiDigital

The tag is a multi-digital alarm

Chapter: 4 Automation Model

AlarmType_ArgyleAnalog

The tag is a legacy Argyle analog

alarm

AlarmType_TimeStampedDigita
l

The tag is a digital time-stamped

alarm

AlarmType_TimeStampedAnalo
g

The tag is a analog time-stamped

alarm

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
Member Name

Description

Value

AxisLabelType_NONE

No labels will be visible on axis

AxisLabelType_DOUBLE

Displays in decimal format

AxisLabelType_INTEGER

Displays in integer format

AxisLabelType_PERCENT

Displays as "%"

AxisLabelType_AMPS

Displays as "A"

AxisLabelType_DEGREES

Displays as "deg"

AxisLabelType_FEET

Displays as "ft"

AxisLabelType_FEETPERMIN

Displays as "ft/min"

AxisLabelType_FEETPERSEC

Displays as "ft/s"

AxisLabelType_GALLONS

Displays as "gal"

AxisLabelType_GALLONSPERHR

Displays as "gal/h"

AxisLabelType_GALLONSPERMIN

Displays as "gal/min"

AxisLabelType_GALLONSPERSEC

Displays as "gal/s"

AxisLabelType_HERTZ

Displays as "Hz"

AxisLabelType_KILOGRAMS

Displays as "kg"

AxisLabelType_KILOGRAMSPERH
R

Displays as "kg/h"

AxisLabelType_KILOGRAMSPERM
IN

Displays as "kg/min"

AxisLabelType_KILOGRAMSPERS
EC

Displays as "kg/s"

AxisLabelType_KILOMETRESPER
HR

Displays as "kg/h"

AxisLabelType_KILOPASCALS

Displays as "kPa"

AxisLabelType_KILOWATTS

Displays as "kW"

AxisLabelType_LITRES

Displays as "l"

AxisLabelType_LITRESPERHR

Displays as "l/h"

Chapter: 4 Automation Model

AxisLabelType_LITRESPERMIN

Displays as "l/min"

AxisLabelType_LITRESPERSEC

Displays as "l/s"

AxisLabelType_METRES

Displays as "m"

AxisLabelType_METRESPERMIN

Displays as "m/min"

AxisLabelType_METRESPERSEC

Displays as "m/s"

AxisLabelType_REVS

Displays as "Rev"

AxisLabelType_REVSPERHR

Displays as "Rev/h"

AxisLabelType_REVSPERMIN

Displays as "RPM"

AxisLabelType_TONNES

Displays as "t"

AxisLabelType_TONNESPERHR

Displays as "t/h"

AxisLabelType_VOLTS

Displays as "V"

AxisLabelType_WATTS

Displays as "W"

AxisLabelType_LOOKUP

Displays user-defined text for

label

ErrorNotifyCode [Enumeration]
Defines known errors that can occur during operation.
Defined As
[VBA] Integer
[Cicode] INT
[C++] ErrorNotifyCode
Members

Member Name

Description

Value

ErrorNotifyCode_None

No error.

ErrorNotifyCode_InvalidTag

Occurs when the tag specified for

the pen does not exist.

ErrorNotifyCode_CtapiConnecti
onOffline

Occurs when connections cannot

be made to the Trends and/or
Alarm Servers.

ErrorNotifyCode_Unknown

Occurs when an unknown CitectSCADA or Windows error occurs.

ErrorNotifyCode_NoServer

Occurs when CitectSCADA cannot

find a server to get the data from.

ErrorNotifyCode_InvalidArgume
nt

Occurs when an invalid argument

is specified.

ErrorNotifyCode_OutOfMemory

Occurs when a memory error is detected.

ErrorNotifyCode_BadVersion

Occurs when the Trends and/or

Alarm Servers do not match the
client version.

ErrorNotifyCode_NoPrivilege

Occurs when the current user does

not have the required privileges to
view the data.

Chapter: 4 Automation Model

Refers to the project folder

FileLocation_Server

Refers to the both the primary/standby server

paths

FileLocation_User

Refers to the My Documents folder

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
Member Name

Description

Value

HatchStyle_None

No pattern

HatchStyle_Horizontal

Horizontal line pattern

HatchStyle_Vertical

Vertical line pattern

HatchStyle_ForwardDiagonal

Forward diagonal line pattern

HatchStyle_BackwardDiagonal

Backward diagonal line pattern

HatchStyle_Cross

Cross pattern

HatchStyle_DiagonalCross

Diagonal cross pattern

See Also
IAlarmPen.SetHatchStyle [Method], IAlarmPen.GetHatchStyle [Method]

LineStyle [Enumeration]
Defines the drawing style for a line.
Defined As
35

Chapter: 4 Automation Model

[VBA] Integer
[Cicode] INT
[C++] LineStyle

Values
Member Name

Description

Value

LineStyle_SOLID

Draws a solid line (all line widths)

LineStyle_DASH

Draws a dashed line (line width 1 only)

LineStyle_DOT

Draws a dot line (line width 1 only)

LineStyle_DASHDOT

Draws a dash dot (line width 1 only)

LineStyle_DASHDOTDOT

Draws a dash dot dot (line width 1 only)

LineStyle_NONE

Draws no line

LineType [Enumeration]
Defines the visual representation of the lines between samples of an analog pen.
Defined As
[VBA] Integer
[Cicode] INT
[C++] LineType
Members
Member Name

Description

Value

LineType_STRA
IGHT

A single line is drawn from point A to point B.

LineType_STEP
PED

The line drawn will maintain the value of the previous sample. When the samples differ, a vertical
line will be drawn to the new sample value.

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

Description

Value

PenNameMode_Com
ment

The comment field obtained from the CitectSCADA trend/alarm tag will be used as
the pen name.

Chapter: 4 Automation Model

PenNameMode_Tag

The value of the IPen.DataPoint property will

be used as the pen name.

PenNameMode_Custo
m

Indicates that you will be setting the name

using the IPen.Name property.

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
Member Name

Description

Value

PenType_ANALOG

A pen with an analog range

4097

PenType_DIGITAL

A pen with a range of 0 and 1

4098

PenType_ALARM

A pen represented as states

4099

Chapter: 4 Automation Model

QualityCompactionType [Enumeration]
Specifies the different types of presentation used for a sample.
Defined As
[VBA] Integer
[Cicode] INT
[C++] QualityCompactionType
Members
Member Name

Description

Value

QualityCompactionType_Single

Representation when the marker represents a single sample

QualityCompactionType_Multiple

Representation when the marker represents a calculation of two or more

samples

QualityCompactionType_Interpolate
d

Representation when the marker represents interpolated samples

See Also
IPen.SetQualityCompactionPointType [Method]

QualityType [Enumeration]
Defines the known quality states of data.
Defined As
[VBA] Integer
[Cicode] INT
[C++] QualityType
Members
Member Name

Description

Value

QualityType_Good

The sample is good

QualityType_NA

Indicates a loss of connection

QualityType_Gated

Indicates the data was marked as unwanted

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
38

Chapter: 4 Automation Model

Members
Member Name

Description

Value

RequestMode_Aver
age

The value will be an average of all the individual samples

within the multiple sample, as will the timestamp

RequestMode_Mini
mum

The value will be the minimum value out of all the individual samples within the multiple sample. The timestamp
will be the average of all the individual samples.

RequestMode_Maxi
mum

The value will be the maximum value out of all the individual samples within the multiple sample. The timestamp
will be the average of all the individual samples.

RequestMode_Newe
st

The value will the latest arrived value out of all the individual samples within the multiple sample. The timestamp
will be the average of all the individual samples.

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
Member Name

Description

Value

ToolbarButtonType_Push

Standard push button behavior.

ToolbarButtonType_Toggle

The button has two states: On and Off.

ToolbarButtonType_Separator

A visual marker used to group buttons.

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]
39

Chapter: 4 Automation Model

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)
40

Chapter: 4 Automation Model

[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]
41

Chapter: 4 Automation Model

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 errorMessage)
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

[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

Indicates which pen the click occurred on. This object will be invalid if no pen was
clicked.

[in]

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)
43

Chapter: 4 Automation Model

[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

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
47

Chapter: 4 Automation Model

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

[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 interface.
Defined As
[VBA] PenRenamed(pen As Object)
[Cicode] PenRenamed(OBJECT processAnalyst, OBJECT pen)
[C++] PenRenamed(IPen* pen)
Parameters
pen

Chapter: 4 Automation Model

[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

Refers to the pen that now has primary selection. This maybe invalid if the last pen
was deleted from the view.

[in]

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

[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.UnsubscribePropertyChange [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

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 opportunity to update the enable and/or the pressed state of the toolbar button associated with the
command.
This event will be raised frequently so you should limit the amount of code executed in response to this event.
An Update will be triggered in at least the following scenarios:
Selection changes
Command execution
Calling Syntax
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

The state for which fill color to retrieve (0 to 8).

Chapter: 4 Automation Model

Calling Syntax
This example assumes there is a valid alarm pen object to be passed into the example methods.
[VBA]
Sub Example(alarmPen As Object)
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 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.
59

Chapter: 4 Automation Model

Calling Syntax
This example assumes there is a valid AlarmPen object to be passed into the example methods.
[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 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 AlarmPen object to be passed into the example methods.
60

Chapter: 4 Automation Model

[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.

Chapter: 4 Automation Model

[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.
62

Chapter: 4 Automation Model

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.
63

Chapter: 4 Automation Model

[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

[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 invalid, the return value will be InvalidArgument. If the command has been deleted, the return value will be GeneralFailure.
Remarks
This returns the text that is displayed in a tooltip window when the mouse pointer hovers
over the commands button.
Calling Syntax
This example assumes there is a valid Command object as retrieved from a Process Analysts CommandSystem. (for example, VBA: ProcessAnalyst.CommandSystem.Item(1))

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

A value representing a button type.

ToolbarButtonType_Push = 0
ToolbarButtonType_Toggle = 1
ToolbarButtonType_Separator = 2

[in]

tooltip
[in]

The text to be displayed as a tooltip for this command (1-64 characters).

iconPath
[in]

The path to an icon file that will be used as this commands picture.

privilege

A privilege value required by the CitectSCADA user to gain access to this command
(0-8).

[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

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 Syntax, below). This property cannot be used in Cicode.
Calling Syntax
This example assumes you have a valid reference to the cursors collection and that there
are cursors in the collection.
[VBA]
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 collection in Cicode.
Calling Syntax
This example assumes you have a valid reference to the cursors collection.
76

Chapter: 4 Automation Model

[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

[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
Dim
Set
End

If the pen is filled, the area under the pen line will be filled with the color specified by the
FillColor property.
See Also
IDigitalPen.FillColor [Property][Get/Set]
Limits
True (-1): = Fill is displayed
False (0): = Fill is hidden
Calling Syntax
This example assumes there is a valid digital pen object to be passed into the example methods.
[VBA]
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)
81

Chapter: 4 Automation Model

where red, green, and blue are 0-255. The area under the line is filled with this color if the
value of the Fill property is True (-1).
See Also
IDigitalPen.Fill [Property][Get/Set]
Calling Syntax
This example assumes there is a valid DigitalPen object to be passed into the example methods.
[VBA]
Sub Example(digitalPen As Object)
Dim fillColor As Long
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 methods.
82

Chapter: 4 Automation Model

[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

[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

[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

[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

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 example, 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

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 example, 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 InvalidArgument.
Limits
A valid width is 0-1000.
Calling Syntax
91

Chapter: 4 Automation Model

This example assumes there is a valid column as retrieved from an ObjectView. (for example, 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

[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

[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
94

Chapter: 4 Automation Model

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 returned.
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

[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 columns collection.
Defined As
[VBA] ItemByName(columnName As String) as Object
[Cicode] OBJECT ItemByName(STRING columnName)
[C++] ItemByName(STRING columnName, IObjectViewColumn* Item)
Parameters
columnName
[in]

Indicates the unique name of the column item to return from this collection.

Execution Results
If the method succeeds, the return value will be Success. If the column cannot be found, the
return value will be InvalidArgument.
Calling Syntax
This example assumes there is a valid Columns collection object to be passed into the example 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
96

Chapter: 4 Automation Model

[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 example 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

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 immediately in the visualization of the ObjectView.
Defined As
[VBA] Boolean Expanded
[Cicode] INT Expanded
[C++] VARIANT_BOOL Expanded
98

Chapter: 4 Automation Model

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
99

Chapter: 4 Automation Model

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, InvalidArgument 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 ObjectView
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.
100

Chapter: 4 Automation Model

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 fields 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)).
101

Chapter: 4 Automation Model

[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 ObjectView
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] <Any Type> Tag
[Cicode] <Any Type> Tag
[C++] VARIANT Tag
Remarks
The user can associate any variant of data with a pen. This is handy for associating some
custom data with a pen item, and then having direct access to it whenever any events with
a pen item target occur.
Calling Syntax
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

102

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 return 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()
109

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 deleted, the return value will be GeneralFailure.
Calling Syntax
114

Chapter: 4 Automation Model

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 value 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

115

Chapter: 4 Automation Model

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

116

Chapter: 4 Automation Model

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 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 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()
117

Chapter: 4 Automation Model

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
118

Chapter: 4 Automation Model

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
119

Chapter: 4 Automation Model

value
[in]

Indicates the value of the sample that will be added.

timeStamp
[in]

Indicates at what time the sample will occur in UTC time.

milli
[in]

Indicates the millisecond component of the time stamp (0 to 999).

qualityType
[in]

Indicates the quality of the sample that will be added.

compactionType
[in]

Indicates what display type the sample will be represented as.

Execution Result
If the function succeeds, the return value will be Success. If an argument is bad, the return
value will be InvalidArgument. If an argument is out of range, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure. If any other
unexpected error occurs, the return value will be GeneralFailure.
Remarks
This function has limited use as the samples added are stored in a temporary cache; they
can be cleared anytime by time span changes, data refresh calls, or automation.
You can only add samples to analog or digital pens.
See Also
QualityType [Enumeration], QualityCompactionType [Enumeration]
Calling Syntax
Assumes you have passed a valid pen object into the function.
[VBA]
Sub Example(pen As Object)
Dim timeStamp As Date
timestamp = Now
pen.AddSample 75.0, timeStamp, 100, 0, 0
End Sub

[Cicode]
FUNCTION Example(OBJECT hPen)
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

120

Chapter: 4 Automation Model

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
121

Chapter: 4 Automation Model

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 remove logged samples from the server)
Defined As
[VBA] Clear()
[Cicode] Clear()
[C++] HRESULT Clear()
Execution Result
If the function succeeds the return value will be Success. If the pen is deleted then the return
value will be GeneralFailure.
Calling Syntax
Assumes you have passed a valid pen object into the function.
122

Chapter: 4 Automation Model

[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.
123

Chapter: 4 Automation Model

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 GeneralFailure.
Remarks
This property works in conjunction with the DataServer property. This property can be
changed during the lifetime of the pen. Changing the DataPoint property will result in the
data cache being cleared and a new data request issued. A request for the tags information
will also be issued.
See Also
IPen.DataServer [Property][Get/Set]
Calling Syntax
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
124

Chapter: 4 Automation Model

[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()
125

Chapter: 4 Automation Model

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 seconds, INT milliseconds)
[C++] HRESULT GetDefaultSpan (short* weeks, short* days, short* hours, short* minutes, short* seconds, short* milliseconds)
Parameters
weeks
[out]

Indicates the number of weeks in the span.

days
[out]

Indicates the number of days in the span.

hours
[out]

126

Indicates the number of hours in the span.

Chapter: 4 Automation Model

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 GeneralFailure. 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, milliseconds);
END

IPen.GetHorizontalAxisTimeSpan [Method]
Returns the start and end time of this pen in local or UTC time format.
Defined As

127

Chapter: 4 Automation Model

[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

Indicates whether the times returned are in local time or UTC. True = -1, False (0) =
UTC.

[in]

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 GeneralFailure. 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,

128

Chapter: 4 Automation Model

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 InvalidArgument. 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
Attribute

Returns

All

129

Chapter: 4 Automation Model

Tag

Process Analyst source binding field

All

Trend Type

Trend tag field

Analog, Digital

Zero Scale

Process Analyst vertical axis min scale

Analog

Scale

Process Analyst vertical axis scale

range

Analog, Digital

Engineering Scale

Engineering scale range

Analog, Digita

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.

130

Chapter: 4 Automation Model

Information Attributes
Attribute

Returns

Applies to

Average

Process Analyst real-time average

Analog, Digital

Maximum

Process Analyst real-time maximum

Analog

Minimum

Process Analyst real-time minimum

Analog

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.

Chapter: 4 Automation Model

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 pens span with your computers current local time. The
start time will also be moved to maintain the pens current time span.
Defined As
[VBA] GoToNow()
[Cicode] GoToNow()
[C++] HRESULT GoToNow()
Execution Result
If the function succeeds, the return value will be Success. If the pen is deleted, 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

132

Chapter: 4 Automation Model

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 GeneralFailure.
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
133

Chapter: 4 Automation Model

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

134

Controls the direction and amount the axis will be zoomed. Acceptable zoom values
are 0 to 1 (Zoom out) and > 1 (zoom in).

[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

142

Chapter: 4 Automation Model

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

143

[in]

startMs
[in]

Indicates the milliseconds component of the start time.

endTime
[in] Indicates the end date and time without milliseconds of the time span in UTC format.
endMs
[in]

This will contain the milliseconds component of the end time.

Execution Result
If the function succeeds the return value will be Success. If an argument is bad then the return value will be InvalidArgument. If an argument is out of range 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

147

Chapter: 4 Automation Model

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

148

Chapter: 4 Automation Model

[in]

Indicates the new lower bound of the vertical axis.

endValue
[in]

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 seconds, INT milliseconds)
[C++] HRESULT SetDefaultSpan (short weeks, short days, short hours, short minutes,
short seconds, short milliseconds)
Parameters
weeks
[in]

Indicates the number of weeks in the span.

days
[in]

Indicates the number of days in the span.

hours
[in]

Indicates the number of hours in the span.

minutes

152

Chapter: 4 Automation Model

[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 return value will be InvalidArgument. If the pen is deleted then the return value will be GeneralFailure.
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 Integer)
[Cicode] SetQualityCompactionPointType(INT compactionType, INT pointType)
[C++] HRESULT SetQualityCompactionPointType(QualityCompactionType compactionType, PointType pointType)
Parameters
compactionType
[in]

Indicates which sample compaction type you want to set the visual cue for.

pointType
[in]

Indicates which visual cue to use for the selected compaction type.
153

Chapter: 4 Automation Model

Execution Result
If the function succeeds the return value will be Success. If an argument is bad, the return
value will be InvalidArgument. If an argument is out of range, the return value will be InvalidArgument. If the pen is deleted, the return value will be GeneralFailure.
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 defined by the Process Analyst for this Pen only.
Defined As
[VBA] SetQualityLineStyle(qualityType As Integer, lineStyle As Integer)
[Cicode] SetQualityLineStyle(INT qualityType, INT lineStyle)
[C++] HRESULT SetQualityLineStyle(QualityType qualityType, LineStyle lineStyle)
Parameters
qualityType
[in]

Indicates which quality type you want to set the visual cue for.

lineStyle
[in]

Indicates which line style visual cue to use for the selected quality type.

154

Chapter: 4 Automation Model

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]

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
158

Chapter: 4 Automation Model

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).
159

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

169

Chapter: 4 Automation Model

[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

Controls the direction and amount the axis will be zoomed. Acceptable zoom values
are 0 to 1 (Zoom out) and > 1 (zoom in).

[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

170

Chapter: 4 Automation Model

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)
171

Chapter: 4 Automation Model

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 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 count As Long
Getting Property value

172

Chapter: 4 Automation Model

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 property. Specifying PenNameMode_Tag will mean that the Process Analyst will name the pen
as the value of the IPen.DataPoint property. Specifying PenNameMode_Custom causes the
Process Analyst to provide a default name and leave setting the name to you via the IPen.Name property.

Execution Results
If the method succeeds the return value will be Success. If the pens collection is 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

173

Chapter: 4 Automation Model

This example assumes there is a valid Pens collection object to be passed in to the example
methods.
[VBA]
Sub
Dim
Set
End

Example(pens As Object)
pen As Object
pen = pens.Create(4097, 1)
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 pens 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 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.Item(1)
End Sub

174

Chapter: 4 Automation Model

[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.
175

Chapter: 4 Automation Model

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 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.

176

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 value 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

180

Chapter: 4 Automation Model

[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

Indicates whether to enable or disable the event. True(-1) enable the event. False(0)
disable the event.

[in]

Execution Result
If the method succeeds, the return value will be Success. If the method fails, the return value will be GeneralFailure. If eventName is bad or does not exist, the return value will be
InvalidArgument.
Remarks
All events exposed by the Process Analyst can be enabled or disabled. This method is particularly useful to prevent recursive behavior of functions that generate the same event that
you are trying to handle.
Calling Syntax
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

Indicates which known location to save the file to.

Execution Result
If the function succeeds the return value will be Success. If the filename is invalid the return
value will be InvalidArgument. If the path indicated by fileLocation is invalid or offline
then the return value will be PathNotFound. If any other problem occurs, the return value
will be GeneralFailure.
Remarks
On a client where the current user matches the WritePrivilegeLevel only the
FileLocation_Server and FileLocation_User options will succeed. Saving using the
FileLocation_Server option will save to the locations indicated by PrimaryPath and SecondaryPath properties and into the Project directory.
On a client where the current user does not match the WritePrivilegeLevel only the
FileLocation_User will succeed.
On a webclient the FileLocation_User is the only option which will succeed.
See Also
FileLocation [Enumeration], IProcessAnalyst.PrimaryPath [Property][Get/Set], IProcessAnalyst.SecondaryPath [Property][Get/Set], IProcessAnalyst.WritePrivilegeLevel [Property][Get]
Calling Syntax
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 Analysts property configuration dialog.
184

Chapter: 4 Automation Model

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. Notifications will be sent via the PropertyChanged event.
Defined As
[VBA] SubscribeForPropertyChange(interfaceName As String, propertyName As
String)
[Cicode] SubscribeForPropertyChange(STRING interfaceName, STRING propertyName)
[C++] HRESULT SubscribeForPropertyChange(BSTR interfaceName, BSTR propertyName)
Parameters
interfaceName

Specify the name of the interface that the property you want notifications for is defined on.

[in]

propertyName
[in]

This is the name of the property you want to receive notifications for.

Execution Result

185

Chapter: 4 Automation Model

If the function succeeds, the return value will be Success. If the interfaceName or propertyName is a bad string, the return value will be InvalidArgument. If any other problem occurs, the return value will be GeneralFailure.
Remarks
The following set of properties are supported:
Interface name

Property Name

IProcessAnalyst

AutoScroll

IProcessAnalyst

BackgroundColor

IProcessAnalyst

ContextMenu

IProcessAnalyst

LockedPens

IProcessAnalyst

DisplayRefreshRate

IProcessAnalyst

DataRequestRate

IProcessAnalyst

ZoomMode

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.
186

Chapter: 4 Automation Model

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. Notifications will cease to be sent via the PropertyChanged event.
Defined As
[VBA] UnsubscribePropertyChange(interfaceName As String, propertyName As
String)
[Cicode] UnsubscribePropertyChange(STRING interfaceName, STRING propertyName)
[C++] HRESULT UnsubscribePropertyChange(BSTR interfaceName, BSTR propertyName)
Parameters
interfaceName
[in] Name of the interface that the property you want to remove notifications for is defined

on.
propertyName
[in]

Name of the property you want to remove notifications for.

Execution Result
If the function succeeds, the return value will be Success. If the interfaceName or propertyName is a bad string, the return value will be InvalidArgument. If any other problem occurs, the return value will be GeneralFailure.
See Also
IProcessAnalyst.SubscribeForPropertyChange [Method], PropertyChanged [Event]
187

Chapter: 4 Automation Model

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 Process Analyst at Run-time.
Defined As
[VBA] Integer AdminPrivilegeLevel
[Cicode] INT AdminPrivilegeLevel
[C++] short AdminPrivilegeLevel
Execution Result
If the property get succeeds the return value will be Success. If the return variable is bad
then the return value will be InvalidArgument.
Remarks
By default the level is 0 (Zero), which allows access to all features at run time. Setting this
to any other level will require the operator viewing the Process Analyst to have a privilege
equal to that level.
This property can only be set at design time (in the Graphics Builder property pages) and
is recommended to prevent Operators from changing performance properties such as DataRequestRate and DisplayRefreshRate.
Limits
Privilege level defined in CitectSCADA 1 - 8. 0 = no security.
Calling Syntax
Assumes you have a page called "myPage" and the Process Analyst has been named
"AN35".

188

Chapter: 4 Automation Model

[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

189

[VBA]
Sub Example()
Dim requestRate As Integer
Retrieve request rate
requestRate = myPage_AN35.DisplayRefreshRate
Set request rate
myPage_AN35.DisplayRefreshRate = 2000
End Sub

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 respectively.
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 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.
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 pens time span by the value of this property, you can calculate the current
display period of the pen. The Process Analyst will only display a maximum of one sample
per display period. See Data Compaction for details.
Limits
Minimum = 10
Maximum = 5000
Default = 300
198

Chapter: 4 Automation Model

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

199

Chapter: 4 Automation Model

[Cicode]
FUNCTION Example()
OBJECT hProcessAnalyst = ObjectByName("AN35");
OBJECT objectView;
// Retrieve the objectview
objectView = _ObjectGetProperty(hProcessAnalyst, "ObjectView");
END

[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 Secondary 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".
203

Chapter: 4 Automation Model

[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

204

Chapter: 4 Automation Model

[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 Analysts
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

205

Chapter: 4 Automation Model

[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 Analysts
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);

206

Chapter: 4 Automation Model

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

207

Chapter: 4 Automation Model

[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

208

Chapter: 4 Automation Model

[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 ObjectView (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

Defined As
[VBA] Remove(Index as Integer)
[Cicode] Remove (INT Index)
[C++] HRESULT Remove (int Index)
Parameters
Index
[in]

The index of the button to remove from this toolbar. (1 Based)

Execution Results
If the method succeeds, the return value will be Success. If the index is out of range, the return value will be InvalidRange. If the method fails, the return value will be GeneralFailure.
Calling Syntax
This example assumes there is a valid ToolbarButtons collection as retrieved from an ObjectView. (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 value will be GeneralFailure.
Calling Syntax
This example assumes there is a valid ToolbarButtons collection as retrieved from an ObjectView. (for example, VBA: objectView.Toolbars.Item(1).Buttons)

213

Chapter: 4 Automation Model

[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

214

Chapter: 4 Automation Model

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)

215

Chapter: 4 Automation Model

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

216

Chapter: 4 Automation Model

ITrendCursor.GetValue [Method]
Gets the value at the cursor for the given pen.
Defined As
[VBA] GetValue(pen As Object, asLocal As Boolean, time As Date, milli As Integer, value As String)
[Cicode] GetValue(OBJECT pen, INT asLocal, REAL time, INT milli, STRING value)
[C++] HRESULT Create GetValue(IPen* pen, VARIANT_BOOL asLocal, DATE *time,
short *milli, BSTR *value)
Parameters
pen
[in]

The pen for which the value is required.

asLocal
[in]

Set to True (-1) if returned time is required in Local form (False (0) for UTC).

time
[out] The time represented by the cursor position. This is accurate to one second and must

be combined with milli to give millisecond accuracy.

milli
[out]

Added to time (see above) to give cursor time in millisecond accuracy.

value

[out] The value of the trend for the given pen at the returned time.
Execution Result
If the function succeeds, the return value will be Success. If one of the return variables are
bad, then the return value will be InvalidArgument. If the cursor is deleted, the return value 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;

217

Chapter: 4 Automation Model

_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

221

Chapter: 4 Automation Model

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 [Property][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 labels X-Axis position of the specified pen on this cursor.
Defined As
[VBA] Double PenLabelX(pen As Object)
[Cicode] REAL PenLabelX (OBJECT pen)
[C++] HRESULT PenLabelX (IPen* pen, double labelX)
Parameters
pen
[in]

The pen for which cursor label is to be referenced.

Execution Result

222

Chapter: 4 Automation Model

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 [Property][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 labels Y-Axis position of the specified pen on this cursor.
Defined As
[VBA] Double PenLabelY(pen As Object)
[Cicode] REAL PenLabelY (OBJECT pen)
[C++] HRESULT PenLabelY (IPen* pIPen, double labelY)
Remarks
The label position is represented in pixels
Syntax
ITrendCursor.PenLabelWidth [Property][Get/Set], ITrendCursor.PenLabelHeight [Property][Get/Set], ITrendCursor.PenLabelX [Property][Get/Set]
Calling Syntax
223

Chapter: 4 Automation Model

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 cursors 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

224

Chapter: 4 Automation Model

[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

225

Chapter: 4 Automation Model

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

226

Chapter: 5 Automation Examples

The best way of understanding how to use the Process Analysts automation model is to
see some example code. The following examples cover the most important concepts of extensibility offered by the Process Analyst:
Event handling
Enumerating collections
Custom commands
Custom columns
All of the samples assume you are using the CSV example project and have pasted a new
Process Analyst onto the test page provided by the project.
You will also need to configure the Process Analyst objects Name and Event class by doing
the following:
In the CSV example project open the "test" page in Graphics Builder
Click the Process Analyst icon in the toolbox to insert the control.
Resize the control to fit the test page.
Double-click the Process Analyst.
Click the Access/Identification tab.
Change the Object Name to CPA.
Change the Event class to CPA_E.
Click Apply and OK.

Handling an Event
The Process Analyst contains many events that are triggered when certain actions occur.
See Events.
To handle an event you must provide a handler for the event by prepending your Process
Analysts event class name with the event name you want to handle and an underscore.
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".

227

Chapter: 5 Automation Examples

[VBA]
Sub CPA_MouseClick(pen As Object, button As Integer)
Dim bZoomMode As Boolean
If (button = 1) Then
bZoomMode = test_CPA.ZoomMode
If (bZoomMode = True) Then
test_CPA.ZoomMode = False
End If
End If
End Sub

[Cicode]
FUNCTION CPA_E_MouseClick(OBJECT hPA, OBJECT hPen, INT button)
INT bZoomMode = 0;
IF (button = 1) THEN
bZoomMode = _ObjectGetProperty(hPA, "ZoomMode")
IF (bZoomMode = -1) THEN
_ObjectSetProperty(hPA, "ZoomMode", 0)
END
END
END

Enumerating collections
The Process Analyst contains many "collections" such as Panes, Pens, Cursors, Commands,
and so on. This example shows you how to enumerate through the buttons on the navigation toolbar.
[VBA]
Sub EnumerateToolbarButtons()
Dim navBar As Object
Dim iButton As Integer
Dim button As Object
Dim nButtons As Integer
The Navigation toolbar is the 2nd toolbar in the collection
Set navBar = test_CPA.Toolbars.Item(2)
If IsNull(navBar) = False Then
nButtons = navBar.Buttons.Count
For iButton = 1 To nButtons
Set button = navBar.Buttons(iButton)
Next iButton
End If
End Sub

[Cicode]
FUNCTION EnumerateToolbarButtons()
OBJECT hPA = ObjectByName("CPA");
OBJECT hToolbars = _ObjectGetProperty(hPA, "Toolbars");
// The Navigation toolbar is the 2nd toolbar in the collection
OBJECT hNavBar = _ObjectCallMethod(hToolbars, "get_Item", 2);
OBJECT hButtons;
OBJECT hButton;
INT nButtons;
INT iButton;

228

Chapter: 5 Automation Examples

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:
Display the properties for your Process Analyst in the Graphics Builder
See Adding New Commands.
Use the following settings:
3. ID ="SelectedPen"
4. Tooltip = "Show the name of the selected pen"
5. Button style = <Push>
6. Enabled = <Checked>
Once youve done this, you need to write an event handler for the CommandExecuted event.
This event will be called when the command is executed, whether by Cicode or by clicking
on the respective toolbar button. The CommandExecuted event when triggered has a commandId parameter identifying the command executed by the operator.
This example implements a command that displays a message box showing the name of
the primary selected pen.
See Also
CommandExecuted [Event]
[VBA]
Sub CPA_E_CommandExecuted(commandId As String)
Select Case commandId
Case "SelectedPen"
Call OnSelectedPen()
End Select
End Sub
Sub OnSelectedPen()
Dim pen As Object
Dim sName As String
Dim sMessage As String
Set pen = test_CPA.LastSelectedPen
If IsNull(pen) = False Then
sName = pen.Name
End If

229

Chapter: 5 Automation Examples

sMessage = "The name of the selected pen is:" + Chr(13) + sName

MsgBox sMessage, 48, "Citect"
End Sub

[Cicode]
FUNCTION CPA_E_CommandExecuted(OBJECT hPA, STRING commandId)
SELECT CASE commandId
CASE "SelectedPen"
OnSelectedPen(hPA);
END SELECT
END
FUNCTION OnSelectedPen(OBJECT hPA)
OBJECT hPen;
STRING sName;
STRING sMessage;
IF ObjectIsValid(hPA) THEN
hPen = _ObjectGetProperty(hPA, "LastSelectedPen");
IF ObjectIsValid(hPen) THEN
sName = _ObjectGetProperty(hPen, "Name");
END
sMessage = "The name of the selected pen is:^n" + sName;
Message("Citect", sMessage, 48);
END
END

Enabling and Disabling a Command

You can also respond to the UpdateCommand event to control the enable/disable state of the
commands toolbar button. The example below disables the button if there are no pens.
[VBA]
Sub CPA_E_UpdateCommand(commandId As String)
Select Case commandId
Case "SelectedPen"
Call OnUpdatedSelectedPen()
End Select
End Sub
Sub OnUpdatedSelectedPen()
Dim pen As Object
Dim 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

230

Chapter: 5 Automation Examples

[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

Implementing a custom column

Custom columns are added to the Object View allowing you to display your own information associated with a pen.
The sample below implements a column that calculates the "Display Period" for each pen
on the Process Analyst. The sample consists of three functions: an update function and two
event handlers to 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 reflects how many panes and pens are being displayed.
The code achieves this by iterating through each pane and pen object in the Process Analyst
while simultaneously keeping a running index count of which pane/pen item it matches up
to in the Object View tree.
By using these indexes the code knows which row to update. A row update is achieved using the PutField method.
Note: Implementing your own column is CPU-intensive. Try to keep the amount of code
required to calculate a row value as efficient as possible and be aware how often the code

231

Chapter: 5 Automation Examples

will be executed. Note also that, for efficiency, the BlockUpdates and UnblockUpdates functions are used to limit the number of updates made to the Object View.
Event Handlers
Once you have a function that implements your custom column, you need to know when
to update that column. The most common method of doing this is to implement event handlers for particular Process Analyst events. The example below uses the PenCreated event
and the HorizontalAxisChanged event. These events will 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], IProcessAnalyst.UnBlockUpdates [Method], PenCreated [Event], HorizontalAxisChanged
[Event]
[VBA]
Sub UpdateMyColumn()
Dim iPaneItem As Integer
Dim iPane As Integer
Dim nPanes As Integer
Dim nSamples As Integer
Dim penItem As Object
Dim paneItem As Object
nSamples = test_CPA.NumberOfSamples
iPaneItem = 0
nPanes = test_CPA.Panes.Count
For iPane = 1 To nPanes
Dim pane As Object
Set pane = test_CPA.Panes.Item(iPane)
If IsNUll(pane) = False Then
Dim pen As Object
Dim iPen As Integer
Dim iPenItem As Integer
Dim nPens As Integer
iPaneItem = iPaneItem + 1
Set paneItem = test_CPA.ObjectView.Items.Item(iPaneItem)
test_CPA.BlockUpdates
iPenItem = 0
nPens = pane.Pens.Count
For iPen = 1 To nPens
Set pen = pane.pens.Item(iPen)
If IsNUll(pen) = False Then
Dim dDiff As Double
Dim sText As string
Dim
Dim
Dim
Dim

232

dtStart As Date
dtEnd As Date
dtStartMs As Integer
dtEndMs As Integer

Chapter: 5 Automation Examples

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
INT
INT
INT
INT
INT
INT

nPanes = _ObjectGetProperty(hPanes, "Count");

nPens;
iPen;
iPane = 0;
nSamples = _ObjectGetProperty(hPA, "NumberOfsamples");
iPenItem = 0;
iPaneItem = 0;

REAL dDiff;
REAL dtStart;
REAL dtEnd;
INT dtStartMs;
INT dtEndMs;
STRING sText;
FOR iPane = 1 TO nPanes DO

233

Chapter: 5 Automation Examples

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

234

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

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 existing CitectSCADA server architecture. Users can configure certain properties of the Process
Analyst control during design time.
A typical Process Analyst view might look like the one shown here. Your Process Analyst
views will probably look different to this example.

The Process Analyst control interface typically consists of the following components:
Main toolbar: Contains commands for performing general operations in the Process Analyst, such as opening views, printing reports, and so on. You can configure this toolbar
to contain different items.
Pens: A Process Analyst pen represents your trend and/or alarm data. The Process Analyst supports three types of pen: analog pen, digital pen, and alarm pen. Each pen has
its own graphical representation. You can configure most pen properties during run
time.
Panes: Panes are used to group pens visually in the Process Analyst and are stacked vertically on the Process Analyst display. Every pen belongs to a single pane. You can configure chart panes.
Chart background (not shown): The panes are drawn over the chart background. Depending on the layout of the pens, the background may be partially visible. You can
configure the chart background.
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.
Vertical axis: Analog pens have a vertical axis on the left-hand side of the pane to indicate data values. You can configure this axis.
Cursor: A cursor allows an Operator to determine value at a given point in time by dragging the cursor line to the point required. You can configure the cursor.
Cursor labels: Display the value where the cursor intersects the trend value line.

237

Chapter: 6 The Process Analyst: An Overview

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.
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.

238

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.
Item

Description
Load View. Loads a saved view from file. For details, see Loading a view.
Save View. Saves a view to file. For details, see Saving a view.
Print. Displays the standard Windows Print dialog box for printing trend reports. For details, see Printing and Exporting.
Copy to Clipboard. Copies visible pens to the Windows Clipboard. For details, see Copying data to the Clipboard.
Export to File. Exports visible pens to an Excel-compatible file. For details,
see Copying data to file.
Add Pen. Displays the Add New Pen(s) dialog box for adding a pen. For details, see Adding Pens.
Remove Pen. Deletes the currently selected pen from the trend display. For
details, see Deleting Pens.
Lock/Unlock Pens. Toggles the locking of pens. For details, see Locking/
Unlocking Pens.
Show/Hide Points. Toggles the display of points representing where sample data was recorded in the archive. For details, see Pens: An Overview.
Show/Hide Cursors. Toggles the display of cursors. For details, see Using
Cursors.
Show/Hide Cursor Labels. Toggles the display of cursor labels. For details,
see Using Cursor Labels.
Toggle Object View. Toggles the display of the Object View. For details, see
Using the Object View.
Properties. Displays the Properties dialog box for configuring the Process
Analyst control. For details, see Configuring the Process Analyst.
Help. Displays the Process Analyst online Help.

See Also
Using the Navigation Toolbar | Operator Command Reference

239

Chapter: 7 Using the Main Toolbar

240

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 indicate where data was recorded in the archive. The style of the line indicates the quality of
the data; the style of the sample marker indicates the compaction of the sample.
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 display as individual points, the multiple samples appear as one data point.

The following illustration zooms in on the second multiple sample, and shows that what
appeared to be a single raw sample actually consists of several raw samples:

The Process Analyst uses the following default point styles for single and multiple samples:
Sample compaction

Point type

Single

Ellipse

Multiple

Rectangle

Interpolated

Triangle (see Interpolated 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
241

Chapter: 8 Understanding Process Analyst Pens

time. A multiple sample will be drawn with a value calculated from the samples within the
period. But the value after that period will be whatever the last sample in the period was.
So an interpolated sample is added at the start of the next display period to correct the
graph.
See Also
Interpolation
Request modes
Because the Process Analyst Control makes requests for a range of data using a display period, CitectSCADA needs to perform calculations on data if it becomes too dense in order
to calculate the value of a multiple sample. The Process Analyst provides the following options for this calculation:
Average - The value will be an average of all the individual samples within the multiple
sample, as will the timestamp. This is the default calculation method.
Maximum: The value will be the maximum value out of all the individual samples within the multiple sample. The timestamp will be that of the individual sample that was the
maximum. The timestamp will be the average of all the individual samples within the
multiple sample.
Minimum: The value will be the minimum value out of all the individual samples within 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 multiple 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 recorded in the trend archive. For alarms, this data quality state indicates that the alarm
has been disabled.
The Process Analyst uses the following default line styles to indicate data quality:

242

Quality

Line style

Good

Solid

None

Gated

Dot

Chapter: 8 Understanding Process Analyst Pens

Consider the following examples:

Data sample

Description
This example shows several single samples. The third sample has a quality of N/A, indicated by the break in the trend
line.
Here the quality of the third sample is gated, indicated by
the broken line connecting these samples.

With multiple samples, the quality of the last sample in the group determines how
the line is drawn. Consider the following examples:
This example shows that the third sample is actually a multiple sample. The quality of the third (multiple) sample and
the next sample is N/A, again indicated by the break in the
trend line.
Here the quality of the third multiple sample is gated, again
indicated by the broken line connecting the samples.

The 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 "<xxx>ms." Since the local time zone is determined from the current computer
settings, these settings must be configured accurately.
The date/time axis can also display data using the universal time coordinate (UTC) format.
You can switch between local or UTC time as you like (see Configuring pen axes). If the current time is 10.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 dynamically depending upon the time span. In the illustration above, the major intervals are 1
minute apart, and the minor are 5 seconds apart.
Note the following:
When the axis time span is 1 minute or less, the format of the axis labels includes milliseconds and the date is removed.
When the axis time span is 1 week or above, the time is removed and only the date is
displayed.
By default, the date/time axis displays a time span of 10 minutes; the major intervals represent 5 minutes, and the minor intervals 30 seconds.

243

Chapter: 8 Understanding Process Analyst Pens

Daylight savings (local time)

The date/time axis can also accommodate daylight savings transitions. For example, when
entering daylight savings, the axis will indicate the transition as 11a.m., 12a.m., 1a.m.,
3a.m., 4a.m., 5a.m., if this transition occurred at 2a.m. Likewise, in the out transition, when
1 hour is removed from daylight savings time, the axis will display 11a.m., 12a.m., 1a.m.,
2a.m., 2a.m., 3a.m., 4a.m., 5a.m.
Now indicator
The Now indicator is a small white circle on the date/time axis that indicates the current
computer time based on the computers time settings.

The position of the Now indicator is refreshed according to the value specified in the Display Refresh Date text box in the Process Analyst Control Properties dialog box.
Note: If you have used the CitectSCADA trend page feature, note the following: In CitectSCADA the right-hand side of the screen always represents Now (when looking at realtime data). In the Process Analyst control, "Now" is represented only by the Now indicator,
which may be located anywhere on the trend display, even off screen, since it is possible to
scroll into the future, or back into the past.
You can scroll and scale the date/time time axis to interact with your Process Analyst pens;
for details, see Interacting with the Process Analyst. You can also configure the date/time
axis to suit your preferences; for details, see Configuring pen axes.

Vertical (Value) Axis

The vertical (value) axis is located at the left-hand edge of the pane.
Like the date/time axis, the value axis consists of major and minor intervals, but they represent value intervals rather than date and time. The intervals are calculated automatically
by the Process Analyst.
The value axis is shown only for analog pens; the axis displayed reflects the values for the
primary selected pen.
By default the vertical axis will use the engineering scale from the tag of the selected pen.
The vertical axis also supports autoscaling. When autoscaling is enabled, the vertical axis
automatically adjusts its limits to accommodate new samples as they are added to each individual pen.

244

Chapter: 8 Understanding Process Analyst Pens

In this example, there are two panes, each of which has a differently scaled vertical axis.
You can scroll and scale the vertical axis; for details, see Scrolling the Chart and Scaling the
Chart. You can also configure the appearance of the vertical axis; for details, see Configuring pen axes.

Gridlines
The Process Analyst pens use gridlines as a visual guide to help an Operator determine the
value of trends. Major gridlines are solid lines; minor gridlines are broken lines. Analog
pens have vertical and horizontal gridlines; alarm and digital pens only have vertical gridlines. The display of gridlines changes dynamically according to the selected time span.
You can configure vertical gridlines at run time for all pen types; you can configure horizontal gridlines for analog pens. For details, see Configuring pen gridlines.

Pen Layout
You can are display pens in the Process Analyst by stacking or overlaying.
In stacked mode, a user-specified amount of vertical real-estate is allocated to the pen,
and with this, stacked pens are laid out under each other on the pane, starting from the
top of the pane under the date/time axis, like this:

Here, three pens (one analog and two digital) are stacked under each other. Stacking applies to all types of pens.
In unstacked mode, pens are drawn on top of each other. The order in which the pens
were added to the pane governs the drawing order: the last pen added is the topmost
pen drawn. When a pen is selected, it is brought to the front of any other pens displayed

245

Chapter: 8 Understanding Process Analyst Pens

Here, two analog pens are overlaid. You can also overlay digital and alarm pens.
You can have any mix of stacked and unstacked pens on a pane.

Pen Types
The Process Analyst control supports three types of pen: analog pens, digital pens, and
alarm pens. Analog and digital pens are associated with trend tags; alarm pens are associated with alarm tags.

Analog pens
The Process Analyst control typically uses analog pens to represent nonbinary data. Only
analog pens have a value (vertical) axis, which the data is plotted against, as shown here:

Interpolation
Analog pens have two types of interpolation that allow you to specify how to connect data
samples on a trend line: straight and stepped:
Straight - a line is drawn directly between the points like this:

246

Stepped - the lines drawn always maintain the value of the previous sample until a sample with a different value arrives, in which case a vertical line is drawn:

Chapter: 8 Understanding Process Analyst Pens

The Process Analyst allows analog pens to be configured at run time and design time. For
details, see Configuring Pens.
See Also
Interpolated samples

Digital pens
The Process Analyst control typically uses digital pens to represent binary data. Values on
the pen are clamped to a range of 0 to 1. Any value equal to or greater than 0.5 is clamped
to 1; all other values are clamped to 0. A fill color is used to indicate where the data is 1, as
shown here:

By default, the layout of digital pens is stacked. For details, see Pen Layout.
The Process Analyst allows the appearance of digital pens to be configured during run time
and design time. You can configure the trend line color, width, and fill color. For details,
see Configuring pen appearance.

Alarm pens
The Process Analyst uses alarm pens to graphically display the history of a CitectSCADA
alarm over time. The Process Analyst supports seven different types of alarm pens.
The alarms on/off transition state changes and acknowledgements are all represented
graphically in the alarm pen display. To achieve this, the alarm pen consists of three elements: the alarm state, on/off, and acknowledgement.
The diagram below illustrates how an alarm pen displays the information of an alarm tag:

The alarm is turned on in its initial state and is unacknowledged.

The alarm changes to a different state, but is still unacknowledged.
The alarm is acknowledged.
The alarm is turned off.

247

Chapter: 8 Understanding Process Analyst Pens

Like other types of pen, alarm pens can represent variations in data quality and data compaction.
The Process Analyst allows alarm pens to be configured at run time and design time. For
details, see Configuring alarm pens.
On/off
When an alarm is off, the alarm pen will draw the line low. When the alarm transitions to
on, the line is drawn high.
Alarm states
When an alarm transitions to on, it enters a particular state. The states of an alarm are dictated by the type of CitectSCADA alarm tag. The Process Analyst supports all CitectSCADA standard alarm types.
Note: For multi-digital alarms1, the state descriptions are retrieved from the CitectSCADA
alarm record.
The Process Analyst uses a different color, shading style, and description to represent each
alarm state; these properties are configurable. For details, see Configuring alarm pens.
Alarm acknowledgment
Process Analyst alarm pens can represent when alarms are acknowledged.
The Process Analyst indicates the period for which the alarm has been left unacknowledged by drawing a line above the trend line. A new unacknowledged period begins
whenever the alarm transitions to an on state.

The unacknowledged period ends when an Operator acknowledges an alarm. The Process Analyst identifies this by placing a sample marker to indicate the exact time the
alarm was acknowledged, and by drawing an unacknowledged line down to that sample marker, as shown here:

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.
248

Chapter: 8 Understanding Process Analyst Pens

Alarm types
The Process Analyst uses the following types of alarm pen:
Alarm type

Alarm pen representation

Digital

Analog
Advanced

Argyle Analog
Multi-digital
Timestamped

Timestamped analog

Timestamped digital

For multiple samples in an alarm, the alarm state value is the last recorded value in the
group.

249

Chapter: 8 Understanding Process Analyst Pens

250

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 indicate where data was recorded in the archive. The style of the line indicates the quality of
the data; the style of the sample marker indicates the compaction of the sample.

Pen Selection
Each pane on the Process Analyst can have one selected pen. The axes that are displayed
on a pane are that of the selected pen. The last pen selected across all panes is referred to as
the primary selected pen.
You can select a Process Analyst pen in several ways:
By clicking on the pens graphical elements (i.e., the pen line).
If the pens are stacked, by clicking the background under the pen line.
By selecting the pen in the Object View.
The selection of a pen is indicated by a subtle halo effect surrounding the pen line. In the
example shown here, the top (green) pen is selected, indicated by the halo surrounding the
pen:

251

Chapter: 9 Interacting with the Process Analyst

Note that the halo does not appear if there is only one pen on the pane. Selecting a pen on
a pane also causes the same pen to be highlighted in the Object View. Selecting a pen causes
that pen to be drawn in front of other pens on the pane.

Locking/Unlocking Pens
By default, the Process Analyst locks together the time span and position in time (horizontal axis) of all pens. However, you can unlock the pens, allowing the pens to be displayed
across different positions in time and/or time spans.
For example, you could unlock pens to compare a previous months data for a tag with the
data for this month. You would do this by adding two pens to a pane that represent the
same tag, then unlocking the pens, and adjusting the time positions for each pen as required.
To control pen locking and unlocking, you use the Lock/Unlock Pens button on the main
toolbar.

This option is also available on the right-click (context) menu.

Locking and unlocking has the following behavior:
When pens are locked, all time-related operations are applied to all pens.
When pens are unlocked, all time-related operations are applied to the primary selected
pen.
Synchronization applies to all pens regardless of their being locked or unlocked.
When transitioning from locked to unlocked, the time span and position in time of all pens
are synchronized to match that of the primary selected pen.

Scrolling the Chart

The Process Analyst allows you to scroll through data in both the horizontal and vertical
directions by dragging the mouse or spinning the mouse wheel.
To scroll by dragging:
Click and hold down the left mouse button on the pen (or background) that you want
to scroll.
252

Chapter: 9 Interacting with the Process Analyst

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.
Release the left mouse button to complete the scrolling.
To scroll by using the mouse wheel:
Click the pen or background that you want to scroll.
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 Using the Right-click Menu for details.
The Process Analyst indicates whether scrolling is enabled or disabled by displaying a different-shaped mouse pointer; for details, see Understanding Mouse Pointers.

Scaling the Chart

The Process Analyst allows you to change the scale of the data in both the horizontal and
vertical direction by dragging the mouse or spinning the mouse wheel.
To scale the data by dragging:
Click and hold down the left mouse button on the axis that you want to scale.
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.
Release the left mouse button to complete the scaling.
To scale by using the mouse wheel:
Click the axis that you want to scale.
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 Using the Right-click Menu for details.
The Process Analyst indicates whether scaling is enabled or disabled by displaying a different-shaped mouse pointer; for details, see Understanding Mouse Pointers.

Using the Navigation Toolbar

Using the navigation toolbar you can:
Specify a start time and end time.
Select predefined time spans.
Lock time spans on the display.
Navigate backward or forward through your data.
Synchronize all pens to "Now."
Toggle autoscrolling of the display.
Zoom in on or out of data.
Undo the last zoom operation.
253

Chapter: 9 Interacting with the Process Analyst

Toggle between Zoom mode and normal mode.

Set nonstandard time spans.
Edit the vertical (value) scale.

Specifying a start time and end time

You can specify a start time and an end time for the trend display by using the date/time
pickers. The start time picker is located on the left-hand side of the navigation toolbar, the
end time picker on the right.

The date/time picker formats the date and time using the settings obtained from your computer for the currently logged in user. The date/time picker displays time in 24-hour format
(dd/mm/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:
Click the element of the date or time you want to change in the start time picker or the
end time picker.
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 respectively.
Note: You can use the Left arrow and Right arrow keys to move between time elements.
Working with Daylight Savings
To indicate whether the time in the time picker control is Standard time or Daylight Savings
time, the clock to the left of the control has a shaded segment if the time is in a Daylight
Savings period. When in Standard time, the clock does not have a shaded segment.
For example, this icon appears when the time pickers value is within the local Daylight
Savings period:

This icon appears when the time pickers value is within the local Standard time period:

If the Daylight Savings transition involves duplicate hours, you can use the spin controls
(or Up and Down arrow keys) to select the hour you want.

254

Chapter: 9 Interacting with the Process Analyst

Note: In order for the Process Analyst to be able to indicate that Daylight Savings is in effect, the Automatically adjust clock for daylight saving changes option on the Date and
Time Properties dialog box must be enabled, as indicated below:

See Also
Daylight savings (local time)
Shifting and fitting time units
You can manipulate the start time and end time by using special keyboard shortcuts. Using
these shortcuts, you can do the following:
Shift by unit
Fit to unit
Shift by unit
Shifting date or time by unit allows you to change the opposite date/time element to the
one selected by the corresponding date or time component. For example, if you shift by unit
the month time element in the start time, the month time element in the end time increments by one month exactly, including days, minutes, and seconds. This also works for
months that have different end days.
To shift by unit:
Press and hold down the Shift key.
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

255

Chapter: 9 Interacting with the Process Analyst

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:
Press and hold the Ctrl key.
Click a date or time element in the date/time picker. Both the start time and end time
element are synchronized to zero based on the date/time element selected.

About time spans

The time span of the trend display is the difference between the start time and the end time.
The start time appears on the left-hand side of the trend display, the end time on the right.
The Span Picker (shown below) indicates the current span being used; it also contains commonly used predefined time spans. Selecting a time span adjusts the start time, leaving the
end time as-is.

Chapter: 9 Interacting with the Process Analyst

Forward One Span - moves forward one time span.

Synchronize to Now
The Synchronize to Now command synchronizes all pens such that the date/time reflects
"Now," which is positioned on the right-hand edge of the screen. "Now" is calculated using
the current system time.

The Synchronize to Command is also available from the right-click (context) menu.
See Also
Now indicator

Toggle Autoscrolling
When Autoscroll is turned on, as time passes the position in time of all pens moves by the
same amount to keep pace; by default, the display is updated every second. The refresh rate
of the display can be controlled by using the Display Refresh Rate property.
When Autoscroll is turned off, as time passes the position in time of all pens remain fixed.
By default, Autoscroll is on. You can toggle Autoscrolling on or off by using the Toggle Autoscrolling button.

Using the navigation controls, including the Time Span picker, causes Autoscrolling to be
turned off
The Autoscroll command is also available from the right-click (context) menu.

Zoom In/Zoom Out

Use the Zoom In 50% and Zoom Out 50% commands like this:
Command

Icon

Description

Zoom In 50%

Zooms in on the displayed data, halving the span of

both axes.

Zoom Out 50%

Zooms out of the displayed data, doubling the span of

both axes.

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.

257

Chapter: 9 Interacting with the Process Analyst

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:
Select the pen to zoom in on.
Click ToggleBox Zoom on the navigation toolbar.

The cursor changes to a cross.

Click and drag the bounding box to enclose the part of the data you want to zoom in on,
as shown below.

Release the mouse button. The display changes to a close-up of the selected data.

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 nonautoscaled analog pens in the pane in which the zoom box was initiated.
For unlocked pens, the zoom is applied only to the selected pen in both the date/time
and vertical (value) axes. The value axis is only affected if autoscale is off.
Note: Vertical zoom is only applied to analog pens, since it has no effect with alarm or digital pens.

Edit Span
Click the Edit Span button to display the Edit Span dialog box, which allows you to set
non-standard time spans.

To edit a time span:

258

Chapter: 9 Interacting with the Process Analyst

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.
Enter a New span. Click the element of the time span that you want to change, then either type in a new value, or use the Up arrow or Down arrow to specify a new value.
You can use the Right arrow and the Left arrow key to move between the time elements.
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:
Click Edit Vertical Scale on the navigation toolbar. The Edit Vertical Scale dialog box
appears.

Click the Limits or Engineering Scale option. The Limits values displayed are the current values used by the vertical scale. The Engineering Scale values are obtained from
the trend tag.
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.
259

Chapter: 9 Interacting with the Process Analyst

See Also
Configuring Defaults | Pen Selection

Using Cursors
A cursor enables an Operator to determine the value of a pen at a given point in time by
dragging the cursor to the specific point on the pen line. A cursor label is used to display
the value.
An Operator can define many of the properties of cursors and cursor labels. For details, see
Configuring Cursors.

In this example the cursor intersects three pens; the cursor labels (the yellow rectangles)
display the corresponding pen values.
To move a cursor, drag the cursor line left or right. As the cursor moves, the cursor labels
move with the cursor and are updated continuously, reflecting the position of the cursor.
Note: The cursor extends across all configured panes.
A line connects the cursor label to the associated pen line. The line has three main states:
State

Style

Intersection within pen data

Line

Intersection before or after pen data

Line with indicator

No intersection and no data

Invisible line

To show/hide a cursor:
260

Example

Chapter: 9 Interacting with the Process Analyst

Click Show/Hide Cursor on the main toolbar. You can display additional cursors by using the Properties dialog box.

You can display as many cursors as you want. To add a cursor, right-click the root item
(Process Analyst View) in the property tree in the Properties dialog box, and choose Add
Cursor.

Using Cursor Labels

Each cursor has one cursor label for each pen displayed. The cursor label displays the value
of the pen at the point where the cursor intersects with the pen data.
To display cursor labels:
Click Show/Hide Cursor Labels on the main toolbar.

This table summarizes how to use cursor labels:

Task

Description

Move a cursor
label

Click the cursor label and drag the label to a new location.

Change the
size of cursor
labels

Click the cursor label you want to resize. Place the mouse cursor on one
of the sizing boxes, and drag the label to the new size. If you drag the
corner of the label, the label text resizes to an optimal size for the label.

Lock or unlock
the cursor labels

Click the Lock/Unlock Cursor Labels. When on, this command causes
cursor labels to be "frozen" in the position.

The cursor label displays the following information:

Cursor field

Applies to

cursor intersects with the date/time axis.

Alarm Sample Comment

Alarms

Comment bound to an alarm sample.

Chapter: 9 Interacting with the Process Analyst

Pen line/pen
background

The mouse pointer looks like this when the pointer is on the
horizontal axis and only horizontal scrolling is enabled.
Clicking and dragging (or scrolling the mouse wheel) will result in the axis being scrolled.

Vertical axis

The mouse pointer looks like this when the pointer is on the
vertical axis and vertical scaling is enabled. Clicking and
dragging (or scrolling the mouse wheel) will result in the
axis being scaled.

Vertical axis

The mouse pointer looks like this when the pointer is on the
vertical axis and only vertical scrolling is enabled. Clicking
and dragging (or scrolling the mouse wheel) will result in
the axis being scrolled.

Box Zoom mode

The mouse pointer looks like this when Box Zoom mode is
enabled. See Toggle Box Zoom.

Adding 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:
Select the Type of server you want to search: Trends or Alarms.
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".
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.
Select one or more tags from the Search Results list. You can use the Ctrl and/or Shift
keys to select multiple tags.
Select the destination pens to Add Add pens to. Pens can be added to any existing pane,
or to a new pane.
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.
263

Chapter: 9 Interacting with the Process Analyst

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<X>
where X is an incremented number, starting with the first available number.
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.
To view details about a selected tag, click Show Detail. The Pen Detail box appears,
showing defined information for the selected tag.
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:
Select the pen you want to delete.
Click RemovePen in the main toolbar. The pen is deleted from the display.

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:
Click Add Pens. The Add Pens dialog box appears.
Navigate to the tag you want to view details for. For details on searching tags, see Adding Pens.
Select the tag in the Selected Items list, and then click Show Detail. The Pen Details dialog box appears, showing the system information for the selected tag.

264

Chapter: 9 Interacting with the Process Analyst

265

Chapter: 9 Interacting with the Process Analyst

266

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 information about associated tags.
See Also
Object View Basics | Using Object View | Configuring the Object View

Object View Basics

The Object View displays a hierarchically arranged view of the panes and pens on the chart,
in the Object Tree column. The Object View lists information about each pen. When displayed, the Object View is located under the navigation toolbar.
The Object View (as it appears in a default configuration) is shown below; your Object
View might look different depending on how it has been customized in your system.

By default, all items in the Object View are expanded (that is, all pens for all panes are
shown). Clicking a pen in the Object View selects that pen. There is always one pen selected
in each pane; in the example above, the primary selected pen is highlighted in blue; all other selected pens are highlighted in gray.
See Also
Pen Selection
The Object View displays the following items:
Icon

Object
Analog pen
Digital pen
Alarm pen
Pane

The check box controls whether the pen is visible on the chart. The gradient-filled color box
to the left of the pen name indicates the pens line color as it appears on the chart.
The Object View always mirrors the items that are displayed on a chart. For example, if you
add a pane to the chart, a new pane is added simultaneously to the Object View. Similarly,
267

Chapter: 10 Using the Object View

if a new pen is added to or deleted from a pane, or if a pens properties are changed, these
changes are reflected in the Object View.
The table below shows the predefined default columns, which are displayed in addition to
the object tree. These columns are arranged by default from left to right in the Object View.
Column

Description

Zero Scale

Vertical axis start position of the pen.

Full Scale

Vertical axis end position of the pen.

Engineering Units

Engineering units associated with the pen.

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.
Task

Description

Toggle the display

of Object View on
or off

Click Toggle Object View on the main toolbar.

Change the size of

Object View

Drag the splitter bar that is located between the chart area
and the Object View up or down.

Expand or collapse
a tree node in the
Object Tree column

Either click the (+) box to expand the node or the (-) box
to collapse the node; or double-click the item to toggle between expanded and collapsed states. This does not affect
the display of panes in the chart.

Select a pen

Click the pen in the Object View table. Selecting a pen in the
Object View gives the focus in the chart to the selected pen,
and vice versa. You can only select one pen per pane at a
time (you cannot select a pane).

Display or hide a
pen

Click to clear the check box to hide the pen; click the check
box again to display the pen.

Dynamically
change the width
of a column during
display

Drag the column divider left or right.

Note: You can quickly resize a column to fit the size of the
widest item in a column by double-clicking a column separator. To resize the column back to its original size, doubleclick the separator again. You can also configure the width
of a column via the Process Analyst Properties dialog; for
details, see Configuring the Object View.

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 documentation.
See Also
About Process Analyst Reports | Configuring Process Analyst Report Options | Exporting
Pen Data

About Process Analyst Reports

Process Analyst reports are formatted automatically by the system to make optimal use of
the paper size and orientation. For example, if the page is small and the report contains a
lot of information, the reports will use a smaller font to try to fit the information to the page.
For larger pages, a larger font will be used. Reports use an Arial font between 8-14 points.
A typical Process Analysis report looks like this:

This example shows a report of a chart titled Citect Process Analyst; the chart has only one
pane, which contains three analog pens. The topmost pen in the report legend is highlighted, indicating that this pen is selected; consequently, the axes shown in the report are associated with this pen. You can see that this pen is selected in the chart by the "halo" effect
269

Chapter: 11 Printing and Exporting

surrounding the pen. The color boxes on the left-hand side of the legend help you to distinguish between the pens.
To print a report:
Click Print. The Print dialog box appears. Click the Print button, or choose Print from
the right-click (context) menu.

Configuring Process Analyst Report Options

You can configure Process Analyst reports to contain such things as specific items on a report legend (pen names, durations, engineering units, for example). You can also include
header information and page numbers.
You use the Print dialog box to configure Process Analyst reports. To display the Print dialog box, click Print on the main toolbar. After configuring your reports, click Print on the
General panel of the Print dialog box to print your report.
See Also
Setting up report legends | Setting up report options

Setting up report legends

You can configure your reports to include report legends. The information in the report legend is derived from the information properties of the underlying tag that is associated with
a pen. If there are no information properties defined for a tag, this information 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:
In the Print dialog box, click the Legend tab. The Legend panel appears.

270

Chapter: 11 Printing and Exporting

The panel shows, by default, the Pen Options, Statistical Analysis Options, and Cursors lists (if there is a cursor currently displayed on the chart). The options available to
you might differ from the ones shown here.
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.
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 value 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 value 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.
Select the Cursors you want to include.
If you want to include a report legend, make sure the Include Legend check box is selected.
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.

271

Chapter: 11 Printing and Exporting

To set up report options:

In the Print dialog box, click the Report tab. The Report panel appears.

In the Header Information area, type a Title for the report. If necessary, include a Comment. Comments are printed under the report title on each report page.
To include a header, make sure the Include Header check box is selected.
To include page numbering, make sure the Include Page Numbers check box is selected.
Click Apply.

Exporting Pen Data

You can export Process Analyst data for pens that are visible to either the Windows Clipboard (by using the Copy to Clipboard command) or to an Microsoft Excel-compatible file
(Copy to File).
When you export data, it is exported using a standard format of columns that represent
time, milliseconds, and then a column per pen, as shown here:

272

Time

Milliseconds

Pane1Pen1

Pane1Pen2

Pane1-Pen3

15/06/2004
01:17:25

100

Off

15/06/2004
01:17:26

100

Low [Unacknowledged]

15/06/2004
01:17:27

100

15/06/2004
01:17:28

100

Low [Acknowledged]
3

Low [Acknowledged]

Chapter: 11 Printing and Exporting

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 <pane>-<pen> where pane is the name of the pane that contains
the pen, and pen is the name of the pen.
See Also
Copying data to the Clipboard | Copying data to file

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:
Select the pen(s) you want to copy data for.
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 correctly. 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:
Select the pen(s) you want to copy data for.
Click Copy to File. The Save As dialog box appears.
Enter a filename and click Save. The data is exported in a delimited format.
Open the file you just created, and complete the Text Import Wizard.

273

Chapter: 11 Printing and Exporting

274

Chapter: 12 Configuring the Process Analyst

Many of the Process Analyst controls properties can be configured at run time to allow an
Operator to customize the control to suit their working preferences. To configure the Process Analyst, you use the Properties dialog box.
See Also
Using the Process Analyst Properties Dialog Box
Configuring Chart-wide Properties
Configuring Chart Panes
Configuring Pens
Configuring Cursors
Configuring Defaults
Configuring Toolbars
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 access the server path properties. The Main page looks like this:

The list on the left-hand side contains the property tree, a hierarchical list of Process Analyst interface components. Selecting an item displays the property controls for that compo275

Chapter: 12 Configuring the Process Analyst

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:
Right-click
this item...

Actions

Chart

Add Pane - add a new pane.

Add Cursor - add a new cursor.

Pane

Add Digital - adds a new digital pen.

Add Analog - adds a new analog pen.
Add Alarm - adds a new alarm pen.
Note: After adding a pen from this menu, configure the data connection by clicking the Connection tab and typing the name of
the tag into the Tag text box.
Delete - deletes the pane.

Pen

Delete - deletes the pen.

Cursor

Delete - deletes the cursor.

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.

276

Chapter: 12 Configuring the Process Analyst

Object View
You use the Object View page to configure the Object View. Operators and Users can select
(at run time and design time) the columns they want to display, as well as change the column width and display order. Users can define new columns and edit existing columns at
design time.
Use the Object View page for the following:
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 Analyst properties page. This page contains two tabs, General and Server Paths, used to modify 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:
Click the General tab on the Main page.

Click the color swatch and select a Background color.

Specify a Display refresh rate.
This value determines the rate at which the display data is refreshed on the display; it
also controls how often the position of the Now indicator is refreshed. This control is
disabled if you do not have appropriate privilege. The default value is 1000 milliseconds. The permitted range is between 10 milliseconds to 60,000 milliseconds. Note that
specifying a rate below 500 is not recommended if your chart contains many pens, since
this may negatively affect performance.
277

Chapter: 12 Configuring the Process Analyst

Specify a Data request rate.

This value determines the maximum frequency of data requests. The Process Analyst
internally determines when a request is required, but you can use this property to cap
the Process Analysts performance.
This control is disabled if you do not have appropriate privilege. The default value is
1000 milliseconds. The permitted range is between 10 to 60,000 milliseconds. Note that
this property affects Trends Server performance.
Specify a Number of Samples.
This specifies the date/time axis span of each pen in number of samples. This control is
disabled if you do not have the appropriate privilege. The default value is 300. The permitted range is between 10-5000. Also see Exporting Pen Data.
Note: 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.
Select the Lock pens check box to lock your pens, or clear the check box to turn off penlocking. For details on pen locking, see Locking/Unlocking Pens.
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.
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 Analyst is embedded in a running CitectSCADA system. This command is disabled at run
time if you do not have the appropriate privilege. For details about saving and loading
views, see Working with Views and Process Analyst View Synchronization.
The Process Analyst uses four possible storage locations:
User - maps to the client machines logged-in users My Documents folder. This option
is available for any possible privilege and CitectSCADA mode.
Primary - User-definable.
Secondary - User-definable.
Local - displays the current CitectSCADA run path (read-only). This text box only gets
populated when the Process Analyst is running in CitectSCADA V6.0 or higher. This
path is an Analyst Views subdirectory under the CitectSCADA current Run directory.
To configure server paths:
Click the Server Paths tab on the Main page.

278

Chapter: 12 Configuring the Process Analyst

Enter the location of the Primary file server.

Enter the location of the Standby file server (optional). This specifies the file server to
use if the primary file server is unavailable.
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 properties can be configured during run time.
To add a pane:
In the property tree of the Properties dialog box, right-click the Process Analyst view
item at the top of the tree, and then select Add Pane. (To remove a pane, right-click a
pane in the tree and choose Delete.)
To configure the chart pane:
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.
Click the color swatch and select a new Background color.
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.
Specify a Size for the pane.
279

Chapter: 12 Configuring the Process Analyst

Click Apply.

Configuring Pens
The Process Analyst allows you to configure your pens to suit your preferences. Pen configuration tasks are performed by using the Properties dialog box, which is used for:
Configuring pen appearance
Configuring pen gridlines
Configuring pen axes
Configuring pen quality
Configuring the pen data connection
Configuring cursor labels

Configuring pen appearance

You use the Process Analyst Properties dialog box to configure the appearance of pens. Pen
appearance can be configured at run time by Operators and Users (and at design time by
Users).
For details about pen appearance, see Pen Types.
Note: To configure default settings for pen appearance, select Analog, Digital,or Alarm in
the property tree under Default Settings, and then complete the procedure below for the
type of pen you want to configure.

Configuring analog and digital pens

Configuring the appearance of analog or digital pens involves selecting the line color, stack
property, line width, and either the method of interpolation (analog pens) or fill color (digital pens).
To configure pen appearance:
Select the pen you want to configure.
Click the Appearance tab to display the appearance property controls.

280

Chapter: 12 Configuring the Process Analyst

Select a Line color using the color swatch.

Specify a Line width.
To stack a pen, select the Stacked option and then specify a Height in pixels for the
stack.
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.
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:
Select the pen you want to configure.
Click the Appearance tab to display the appearance property controls for the selected
alarm pen.

Select a Line color using the color swatch.

Specify a Line width.
To stack a pen, select the Stacked option and then specify a Height in pixels for the
stack.
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.
For each Label for the alarm type you selected, select a Style, a Fill color, and/or a Hatch
color by using the swatches.
281

Chapter: 12 Configuring the Process Analyst

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:
Click the Main Page tab.
From the property tree list, select the pen you want to configure gridlines for.
Click the Gridlines tab to display the gridlines property controls.

In the Vertical: Major area, select a Style, specify a Width, and then select a Color.
In the Vertical: Minor area, select a Style, specify a Width, and then select a Color.
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.
Do the same if necessary for the minor gridline.
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 using local or UTC format.
For more information about pen axes, see Date/Time (Horizontal) Axis and Vertical (Value)
Axis.

282

Chapter: 12 Configuring the Process Analyst

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:
Click the Main Page tab.
From the property tree list, select the pen you want to configure axes for.
Click the Axis tab to display the axis property controls.

In the Vertical area, select a Color by using the color swatch.

Enter a new Line width.
Select a Label type. This specifies the format to use for axis values.
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.

In the Horizontal area, select a Color by using the color swatch.

Select a Background color by using the color swatch.
Enter a new Line width.
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.
Select the Local Time option to display the date/time axis in local time using your machine settings. If this option is not selected, the time is displayed in UTC format. For details about time display on the date/time axis, see Date/Time (Horizontal) Axis.
Select Scale to be able to interactively scale the vertical axis.
Select Scroll to be able to scroll the axis.
Note: The Scale and Scroll options are also available on the right-click (context) menu.
Click Apply.

283

Chapter: 12 Configuring the Process Analyst

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:
Click the Main Page tab.
Select the pen you want to configure.
Click the Quality tab to display the quality property controls.

To enable points for the pen to be visible, select the Points Visible option.
In the Point Styles area, select a Single point style to represent a single data sample.
Select a Multiple point style to represent multiple data samples.
Selected an Interpolated point style for interpolated data samples.
In the Line Styles area, select a line style to represent a Good sample.
Select a line style to represent a Gated/Disabled sample.
Select a line style to represent an NA sample.
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 appropriate privileges.
To configure pen data connection:
Select the pen you want to configure.
Click the Connection tab to display the connection property controls.

284

Chapter: 12 Configuring the Process Analyst

For the Server data connection, a <localhost> connection is selected by default, indicating that the Process Analyst will connect to the CitectSCADA run time client running
on the same computer, and pass its requests through to the client, which will pass them
onto the server.
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 <cluster name.tag
name>. 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.
Select a Request mode. The default is Average.
The request mode defines how multiple samples are treated by the Process Analyst. Regardless of the request mode used, the timestamp for a sample is always averaged.
Click Apply.
See Also
Data Compaction

Configuring cursor labels

You use the Process Analyst Properties dialog box to configure the pen cursor labels. Configuring the pen cursor labels allows you to specify the color used for the lines, background,
and text on the cursor label. Note that the information shown on a cursor label is predefined
and cannot be changed.
For details about cursor labels, see Using Cursor Labels.
Pen cursor labels can be configured at run time by both Operators and Users that have the
appropriate privileges.
To configure cursor labels:
Select the pen you want to configure.
Click the Cursor Label tab to display the connection property controls.

285

Chapter: 12 Configuring the Process Analyst

Select a Line color from the color swatch.

Select a Background color from the color swatch.
Select a Text color from the color swatch.
Click Apply.

Configuring Cursors
You can configure the line width and line color of a selected cursor. Changes to the cursor
line color apply only to the currently selected cursor. For details on cursors, see Using Cursors.
To configure the cursor:
In the property tree of the Process Analyst Properties dialog box, click the cursor you
want to configure. The Appearance property controls appear.

Type in a new Width value, and/or select a new Color.

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 lifetime of the item until its properties are modified.
You configure these defaults in the same way as you configure the individual components.
The Default Settings node on the property tree contains the following items:

286

Chapter: 12 Configuring the Process Analyst

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:
From the Toolbar menu, choose the toolbar you want to customize (MainToolbar or
Navigation Toolbar).
To add a command to the toolbar: In the Available toolbar buttons list, select the command you want to add to the toolbar, and then click Add. The selected command moves
to the Current toolbar buttons list.
287

Chapter: 12 Configuring the Process Analyst

The Available toolbar buttons list contains all the command buttons available in your system, including predefined as well as user-defined commands.
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 columns that are displayed by default. You configure the Object View by using the Properties
dialog box.
Operators can select which columns to display, as well as change the size of existing columns and the column display order. Users can define new columns, or edit or delete existing columns; for details, see Creating or Editing Object View Columns.
You can configure the Object View to display these predefined columns:

288

Column

Description

Scale

Vertical axis start and end position of the pen.

Engineering Units

Engineering units associated with the pen.

Comment

The trend/alarm comment defined for the pen.

Start Time

Date/time axis start position of the pen.

End Time

Date/time axis end position of the pen.

Duration

Difference between the start time and the end time.

Tag

Pens associated trend or alarm tag.

Trend Type

Trend type of associated tag.

Sample Period

Sampling period of the associated trend tag.

Engineering Scale

Engineering scale for associated trend tag.

Raw Scale

Raw scale for associated trend tag.

Alarm Category

Category of associated alarm tag.

Alarm Description

Description of associated alarm tag.

Alarm Area

Area of associated alarm tag.

Alarm Name

Name of associated alarm tag.

Alarm Type

Alarm type of associated alarm tag.

Error

Displays the error of the last data request. Blank if last data
request succeeded.

Minimum

Lowest displayed value (trend tags only).

Maximum

Highest displayed value (trend tags only).

Average

Average of all displayed values (trend tags only).

Chapter: 12 Configuring the Process Analyst

For information on columns that are displayed by default, see Object View Basics.

Object View properties page

The Object View properties page allows you to show or hide existing columns, create custom columns, edit existing columns, and re-order columns.

The Properties page displays all the available columns for the Object View and their properties:
NameID - Internal identifier, which must be unique.
Width - Default width of the column in pixels.
Display Text - Title displayed in the column header.
The check boxes in the NameID column are bound to a columns visibility: a column is visible only if the associated checkbox is selected.
The Move Up and Move Down buttons to the right of the Available Columns list box allow you to reorder columns. The order of the columns from top to bottom in the list dictates
their display order from left to right in the Object View. Clicking Move Up or Move Down
shifts the currently selected item up or down respectively.
See Also
Creating or Editing Object View Columns

Working with Views

An Operator can save the visual setup of a Process Analyst control by saving a view, which
is saved as a Process Analyst View (.pav) file. They can also load views that have been created previously. A view saves the state of all commands, as well as properties for all the
Process Analyst components (panes, pens, axes, backgrounds, and so on).
To save a view or to load a view, you use the Save View and Load View commands, respectively, on the main toolbar.

289

Chapter: 12 Configuring the Process Analyst

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:
On the main toolbar, click Save View. The Save Process Analyst View dialog box appears, showing the location where you can save views.

Choose a location to save your view to.

Note: It is your administrators responsibility to set up the correct directories for saving
views.
Enter a File name for your view, and then click OK.
To support redundancy, if the Local option is available and selected, CitectSCADA attempts to save the view to the primary, standby and local locations.

Loading a view
When loading a view, the start time and end time of a view is restored only autoscroll is off.
If autoscroll is on, pens are synchronized to "Now."
When loading a view, the only locations that are available (My Documents, Primary, and
Standby) are those that have been configured by your administrator.
To load a view:
On the main toolbar, click Load View. The Load dialog box appears.

290

Chapter: 12 Configuring the Process Analyst

Select a view to load, and then click OK. The view is loaded.

291

Chapter: 12 Configuring the Process Analyst

292

Chapter: 13 Operator Command Reference

You use the toolbar commands on the main toolbar and navigation toolbar to perform commonly used functions for viewing and interacting with Process Analyst data, such as adding or removing pens, displaying cursors, and so on.
Process Analyst has predefined commands, grouped into the following categories:
View Commands
Zoom Commands
Navigation Commands
Export Commands
Interface Commands
General Commands
The toolbars in your run time environment might have been customized during implementation, so not all these commands might appear on your toolbars. Additionally your toolbars might have custom commands not described here. The tables describe the default set
of commands delivered with the Process Analyst.

View Commands
The Process Analyst has the following view commands by default:
Icon

Tooltip

Description

Save View

Displays the Save File dialog box allowing an Operator

to save a Process Analyst view to a specified location.
For details, see Saving a view.

Load View

Displays the Load View dialog box allowing the operator

to specify a view to load. For details, see Loading a
view.

See Also
Zoom Commands | Navigation Commands | Export Commands | Interface Commands |
General Commands

Zoom Commands
The Process Analyst has the following zoom commands by default:
Icon

Tooltip

Description

Toggle Box
Zoom

Toggles the Process Analyst into box zoom mode. The

mouse cursor changes to a crosshair used to define an
area to zoom in on. Zoom may be cancelled by rightclicking or toggling the Zoom command off. For details,
see Toggle Box Zoom.

Zoom in
50%

Executes a horizontal and vertical zoom in of 50% of the

current span(s) of the pen(s). For details, see Zoom In/
Zoom Out.

Zoom out
50%

Executes a horizontal and vertical zoom out of 50% of

the current span(s) of the pen(s). For details, see Zoom
In/Zoom Out.

293

Chapter: 13 Operator Command Reference

Icon

Tooltip

Description

Undo Last
Zoom

Undoes the last zoom operation. For details, see Undo

Last Zoom.

Reset to Default Span

Restores the pen(s) spans to their original default settings. For details, see Reset to Default Span.

Edit Span

Displays the Edit Span dialog box allowing an operator to

explicitly enter a time span to apply to the display. For
details, see Edit Span.

Edit Vertical
Scale

Enabled when an analog pen is selected. For details, see

Edit Vertical Scale.

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.
Icon

Tooltip

Description

Toggle Span Lock

Toggles the locking of the time span. A time span

is the "distance" in time between the start time
and end time of the chart. For details, see Span
Lock.

Back One Span

Moves the pen(s) back in time exactly one time

span. For details, see Navigating time.

Back Half a Span

Moves the pen(s) back half a span. For details, see

Navigating time.

Forward One Span

Moves the pen(s) forward in time exactly one

span. For details, see Navigating time.

Forward Half a
Span

Moves the pen(s) forward half a span. For details,

see Navigating time.

Synchronize to
Now

Synchronizes pen(s) such that the end date time

reflects "now" which is positioned on the righthand edge of the screen. "Now" is calculated using
the current system time. For details, see Synchronize to Now.

Toggle AutoScrolling

Toggles the automatic scrolling off and on for all

pens. For details, see Toggle Autoscrolling.

See Also
View Commands | Zoom Commands | Export Commands | Interface Commands | General Commands

294

Chapter: 13 Operator Command Reference

Export Commands
The Process Analyst has the following export commands by default:
Icon

Tooltip

Description

Export to File

Copies visible pens to an Excel compatible file. For

details, see Copying data to file.

Copy to Clipboard

Copies visible pens to the clipboard.Interface Commands. For details, see Copying data to the Clipboard.

See Also
View Commands | Zoom Commands | Navigation Commands | Interface Commands |
General Commands

Interface Commands
The Process Analyst has the following interface commands by default:
Icon

Tooltip

Description

Show/Hide Cursor

Toggles the display of cursors. For details, see

Using Cursors.

Show/Hide Cursor
Labels

Toggles the display of cursor labels. Enabled only

when a cursor is visible and when a pen exists.
For details, see Using Cursor Labels.

Show/Hide Points

Toggles the display of points representing where

sample data was recorded in the archive. For details, see Understanding Pens.

Lock/Unlock Cursor
Labels

Toggles the locking/unlocking of cursor labels.

Enabled only when a cursor is visible and when a
pen exists. For details, see Using Cursor Labels.

Lock/Unlock Pens

Toggles the locking/unlocking of pens. For details, see Locking/Unlocking Pens.

Add Pane

Adds a new pane to the view. For details, see

Configuring Chart Panes.

Remove Pane

Removes the pane of the primary selected pen. A

dialog confirms the delete. For details, see Configuring Chart Panes.

Autoscale Vertical
Axis for Analog
Pens

Toggles autoscaling for the selected pen on a perpen basis. For details, see Scaling the Chart.

Lock/Unlock Vertical Axis Scrolling

Toggles interactive scrolling of the vertical axis

and disables autoscaling. For details, see Scrolling the Chart.

See Also
View Commands | Zoom Commands | Navigation Commands | Export Commands |
General Commands

295

Chapter: 13 Operator Command Reference

General Commands
The Process Analyst has the following general commands by default:
Icon

Tooltip

Description

Add Pen

Displays the add pen dialog. For details, see Adding

Pens.

Remove Pen

Removes the selected pen from the display. For details, see Deleting Pens.

Toggle Object
View

Toggles the display of the Object View. For details,

see Using the Object View.

Displays the print dialog, allowing the user to print

the current state of the Process Analyst. For details,
see Printing and Exporting.

Refresh Data

Refreshes the data for the selected pen, or all pens

(if locked).

Show Properties

Displays the Process Analyst Properties dialog box.

For details, see Using the Process Analyst Properties
Dialog Box.

Help

Displays the Process Analyst Help.

See Also
View Commands | Zoom Commands | Navigation Commands | Export Commands | Interface Commands

296

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 functionality cannot be obtained with the other alarm types. If you configure too many advanced alarms, your system 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 category, you can specify the display characteristics, the action to be taken when an alarm in the category is triggered, 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.

297

Glossary

alarm summary page

Displays alarm summary information in the following format: alarm name, time on, time off, delta time, comment.
Alarms Server
Monitors all alarms and displays an alarm on the appropriate control client(s) when an alarm condition becomes 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 geographically (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). Arguments 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
298

Glossary

number of duplicated (and hence wasteful) requests, whether the protocol supports multiple outstanding requests, 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 functions.
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 configuration 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 clientserver 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 possess 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.
299

Glossary

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 modem.
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 communication 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,

300

Glossary

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 active 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 switches, 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).

301

Glossary

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 number 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 timeline. 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 displayed 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 mathematical formula, or a function.
302

Glossary

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 installations, 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 corner 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.

303

Glossary

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, controllers, 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 information with an I/O device by reading and writing variables. refers to I/O device variables by their register addresses. 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 processing 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 containing 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.

304

Glossary

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 updated 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 distribution). Kurtosis < 3 indicates a thin distribution with a relatively high peak. Kurtosis > 3 indicates a distribution 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 updated 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.

305

Glossary

local Cicode variable

Only recognized by the function within which it is declared, and can only be used by that function. Local variables 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 represents 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 description (e.g., healthy or stopped), and whether or not the state triggers an alarm.

306

Glossary

N
native language
Generally the language of the project developer. Display items such as alarm descriptions, button text, keyboard/alarm logs, graphic text, Cicode strings and so on can be configured in the native language, and displayed, 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 graphic. 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 sigma and +1 sigma, 95.45% between -2 sigma and+2 sigma, and 99.73% between -3 sigma and +3 sigma. The values 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 distribution 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 dynamically under user-definable runtime conditions allowing them to provide animated display of conditions within
the plant.

307

Glossary

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 databases 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 supplied by your PLC manufacturer, and you can connect it to a PLC or a PLC network. You can only use proprietary 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 device 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.

308

Glossary

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 expression 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"
309

Glossary

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.
310

Glossary

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 , client-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 distribution). 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 distribution'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.

311

Glossary

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 completes, 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.
312

Glossary

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 variables. .
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 historical 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.

313

Glossary

W
wizard
A facility that simplifies an otherwise complex procedure by presenting the procedure as a series of simple
steps.

314

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
315

Index

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

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

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

halo effect 252

HatchStyle enumeration 35
Help command 296
HorizontalAxisChanged event 43

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
316

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

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
317

Index

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
318

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

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
319

Index

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
320

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

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

321

Citect SCADA Configuration Training Manual
No ratings yet
Citect SCADA Configuration Training Manual
382 pages
CitectSCADA Technical Reference
No ratings yet
CitectSCADA Technical Reference
375 pages
CitectSCADA Cicode Reference
100% (2)
CitectSCADA Cicode Reference
1,355 pages
Vijeo Citect Installation Guide
No ratings yet
Vijeo Citect Installation Guide
76 pages
Vt230se English Manual
100% (4)
Vt230se English Manual
253 pages
CitectSCADA Cicode Reference
100% (1)
CitectSCADA Cicode Reference
1,355 pages
MDDE Dryer Manual
100% (2)
MDDE Dryer Manual
87 pages
Man Dio55 Uk
No ratings yet
Man Dio55 Uk
18 pages
Vijeo Citect Technical Reference
0% (1)
Vijeo Citect Technical Reference
555 pages
Vijeo Citect Quick Start Guide Part 2
No ratings yet
Vijeo Citect Quick Start Guide Part 2
61 pages
Citect SCADA 2018 R2 Module 1 Situational Awareness Projects
No ratings yet
Citect SCADA 2018 R2 Module 1 Situational Awareness Projects
11 pages
Citect SCADA Cicode 2016 - Study Guide
No ratings yet
Citect SCADA Cicode 2016 - Study Guide
13 pages
Citect-Quickstart Tutorial Programming
100% (1)
Citect-Quickstart Tutorial Programming
67 pages
Citect SCADA Assignment1
No ratings yet
Citect SCADA Assignment1
11 pages
CitectSCADA User Guide
No ratings yet
CitectSCADA User Guide
1,393 pages
CitectSCADA User Guide
No ratings yet
CitectSCADA User Guide
733 pages
CitectSCADA User Guide
No ratings yet
CitectSCADA User Guide
1,100 pages
Citect SCADA Installation Guide
No ratings yet
Citect SCADA Installation Guide
64 pages
Vijeo Citect V70 Getting Started
No ratings yet
Vijeo Citect V70 Getting Started
94 pages
Vijeo Citect User Guide
No ratings yet
Vijeo Citect User Guide
1,509 pages
CitectSCADA Installation Guide
No ratings yet
CitectSCADA Installation Guide
64 pages
CITECT-1hr Quick Start Tutorial2
0% (1)
CITECT-1hr Quick Start Tutorial2
53 pages
CitectSCADA Cicode Reference
100% (2)
CitectSCADA Cicode Reference
908 pages
CitectSCADA v7.1 - CitectVBA Reference Guide
No ratings yet
CitectSCADA v7.1 - CitectVBA Reference Guide
195 pages
CitectSCADA Cicode Reference
100% (1)
CitectSCADA Cicode Reference
952 pages
Home Automation
No ratings yet
Home Automation
193 pages
Vijeo Citect Cicode Reference
No ratings yet
Vijeo Citect Cicode Reference
1,284 pages
CitectSCADA 7.20 Web Client Quick Start Guide
No ratings yet
CitectSCADA 7.20 Web Client Quick Start Guide
56 pages
Cicode Reference PDF
No ratings yet
Cicode Reference PDF
716 pages
2015 04.SCADA - Overall Chapter
100% (1)
2015 04.SCADA - Overall Chapter
60 pages
Manual Qhmi
No ratings yet
Manual Qhmi
305 pages
PI Citect
No ratings yet
PI Citect
78 pages
Vijeo Citect User Guide
100% (1)
Vijeo Citect User Guide
1,108 pages
SCADA - CitectSCADA Configuration
No ratings yet
SCADA - CitectSCADA Configuration
2 pages
CitectVBA Reference Guide
No ratings yet
CitectVBA Reference Guide
197 pages
HD71 User Manual (V1 - 0)
No ratings yet
HD71 User Manual (V1 - 0)
108 pages
Installation Guide
No ratings yet
Installation Guide
52 pages
CitectSCADA CSV - Include PDF
No ratings yet
CitectSCADA CSV - Include PDF
130 pages
Advanced Alarm Citect SCADA
No ratings yet
Advanced Alarm Citect SCADA
3 pages
EcoStruxure Hybrid DCS Control Participant Services User Guide - Eng - EIO0000001524.13
No ratings yet
EcoStruxure Hybrid DCS Control Participant Services User Guide - Eng - EIO0000001524.13
100 pages
ActiveX Controls in CitectSCADA
No ratings yet
ActiveX Controls in CitectSCADA
22 pages
CitectSCADA User Guide
No ratings yet
CitectSCADA User Guide
1,100 pages
PCS7 OpenOS 3rdparty Integration Foxboro en PDF
No ratings yet
PCS7 OpenOS 3rdparty Integration Foxboro en PDF
51 pages
Installation Guide
No ratings yet
Installation Guide
89 pages
Quickstart Tutorial V70 PDF
No ratings yet
Quickstart Tutorial V70 PDF
75 pages
Citect SCADA Learning Path
No ratings yet
Citect SCADA Learning Path
1 page
CSV7.0 Qs Eng PDF
No ratings yet
CSV7.0 Qs Eng PDF
75 pages
The Compact C14 and C16 Specifications
No ratings yet
The Compact C14 and C16 Specifications
12 pages
VJC 2015 Web Client Guide
No ratings yet
VJC 2015 Web Client Guide
33 pages
Process Control System PCS 7 Part1
No ratings yet
Process Control System PCS 7 Part1
198 pages
Installation Guide
No ratings yet
Installation Guide
64 pages
Introduction - The CitectSCADA Environment
No ratings yet
Introduction - The CitectSCADA Environment
10 pages
LM 200 Upgrade Kit Manual
No ratings yet
LM 200 Upgrade Kit Manual
14 pages
Citect SCADA 2016 Communication
No ratings yet
Citect SCADA 2016 Communication
6 pages
UpgradeGuide v720 To v820
100% (1)
UpgradeGuide v720 To v820
11 pages
Project Configuration Tool - Release Notes - StruxureWare Building Operation v1.9.1
No ratings yet
Project Configuration Tool - Release Notes - StruxureWare Building Operation v1.9.1
16 pages
Mod Bus Rtu Example
No ratings yet
Mod Bus Rtu Example
15 pages
Citect Sylabus
No ratings yet
Citect Sylabus
8 pages
Upgrading To CitectSCADA Version 6
No ratings yet
Upgrading To CitectSCADA Version 6
6 pages
Vijeo Citect Architecture Redundancy v7.30 Exam Study Guide
100% (1)
Vijeo Citect Architecture Redundancy v7.30 Exam Study Guide
19 pages
Citect 2013
No ratings yet
Citect 2013
12 pages
Citectscada Networks: Citect Pty LTD 3 Fitzsimmons Lane Gordon NSW 2072 Australia
No ratings yet
Citectscada Networks: Citect Pty LTD 3 Fitzsimmons Lane Gordon NSW 2072 Australia
0 pages
As IEC 61131.2-2004 Programmable Controllers Equipment Requirements and Tests
No ratings yet
As IEC 61131.2-2004 Programmable Controllers Equipment Requirements and Tests
14 pages
Siemens S7 MPI (Eng)
No ratings yet
Siemens S7 MPI (Eng)
6 pages
CitectSCADA 7.20 User Guide-1
No ratings yet
CitectSCADA 7.20 User Guide-1
100 pages
Beginner’s Guide to ChatGPT
From Everand
Beginner’s Guide to ChatGPT
Don Rider
No ratings yet
Smart Manufacturing Terms You Need to Know!
From Everand
Smart Manufacturing Terms You Need to Know!
Mike Nager
No ratings yet

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.