You are on page 1of 340

Advanced Configuration Concepts

Training Manual

LY
Version 6.00

N
O
se
lU
r na
te
In
ct
ite
C

Citect Pty. Ltd.

3 Fitzsimons Lane
GORDON NSW 2072

PO Box 174
PYMBLE NSW 2073
AUSTRALIA

Telephone: 61 2 9496 7300


Fax: 61 2 9496 7399
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. Furthermore, Citect Pty. Ltd. reserves the right to revise this publication at any time
without incurring an obligation to notify any person of the revision.

Citect Pty Ltd ABN 88 001 158 854 (“Citect”)

Advanced Configuration Concepts Training Manual

INTRODUCTION AND LEGAL NOTICE

Your purchase of this official Advanced Configuration Concepts Training Manual entitles you to undertake the
Advanced Configuration Concepts training course. The number allocated to you on purchase of this manual is

LY
your key to complete the course evaluation.

Satisfactory completion of this evaluation is mandatory for you to obtain a Citect certificate of completion of the
training course.

N
The contents of this manual are proprietary to Citect Pty. Ltd. and all rights, including copyright, are reserved by
Citect Pty. Ltd.. You must not copy any part of the manual in hard or electronic form or make any adaptation or
other commercial use of it without Citect’s prior written consent.

O
Citect Pty. Ltd. will not accept any liability for action taken in reliance on this training manual.

COPYRIGHT
se
lU
© Copyright 2005 Citect Pty. Ltd. All rights reserved.

TRADEMARKS
na

Citect Pty. Ltd. has made every effort to supply trademark information about company names, products and
services mentioned in this manual. Trademarks shown below were derived from various sources.
r

CitectSCADA, CitectHMI and CitectIIM are registered trademarks of Citect Pty. Ltd.
te

Windows, Windows NT, Windows 2000, Windows XP, MSSQL Server and Excel are trademarks of Microsoft
Corporation.
In

Oracle is a registered trademark of Oracle Corporation and/or its affiliates.

Novell and NetWare are registered trademarks of Novell Inc.


ct

dBASE is a trademark of Borland Inc.


ite

General Notice:
Some product names used in this manual are used for identification purposes only and may be trademarks of their
respective companies.
C

August 2005 Edition for CitectHMI/SCADA Version 6.00


Manual Revision 2-INT
Written, printed and bound in Australia.

ii CitectHMI/SCADA Version 6.00 August 2005


Table of Contents

CHAPTER 1: INTRODUCTION TO ADVANCED CONFIGURATION CONCEPTS 1-1


Overview ..............................................................................................................................1-1
Before You Begin ................................................................................................................1-2
Course Overview..................................................................................................................1-3
Conventions Used in this Manual ........................................................................................1-5
CHAPTER 2: CUSTOM TEMPLATES 2-1
Overview ..............................................................................................................................2-1
CitectHMI/SCADA Templates ............................................................................................2-2

LY
Creating Your Own Templates ............................................................................................2-4
Unlinking Templates ............................................................................................................2-7
Displaying Alarms .............................................................................................................2-12

N
Navigation ..........................................................................................................................2-16
Custom Menus ...................................................................................................................2-20

O
Animation Points................................................................................................................2-22
Applying Templates ...........................................................................................................2-24
Templates within Templates ..............................................................................................2-25
CHAPTER 3: SMART GENIES
se 3-1
Overview ..............................................................................................................................3-1
Genies – Revision ................................................................................................................3-2
lU
Genies inside Genies ............................................................................................................3-6
Structured Tag Names........................................................................................................3-12
Using Structured Tag Names with Genies .........................................................................3-14
na

Smart Genies ......................................................................................................................3-19


Genie Forms .......................................................................................................................3-29
CHAPTER 4: SMART POPUPS AND SUPERGENIES 4-1
r

Overview ..............................................................................................................................4-1
te

Popup Pages and Supergenies ..............................................................................................4-2


Smart Popup Pages and Supergenies ...................................................................................4-7
In

CHAPTER 5: FORMS 5-1


Overview ..............................................................................................................................5-1
ct

Cicode Forms .......................................................................................................................5-2


Adding Information to Your Form.......................................................................................5-5
Input Values Using Forms....................................................................................................5-7
ite

CHAPTER 6: TRUE COLOR 6-1


Overview ..............................................................................................................................6-1
C

Choosing Standard Colours..................................................................................................6-2


Choosing Custom Colours ...................................................................................................6-6
Creating Custom Colours .....................................................................................................6-8
Choosing Colour Values ....................................................................................................6-14
Custom Fonts and Colour Labels .......................................................................................6-19
Adjust Colours....................................................................................................................6-22
Flashing Colours ................................................................................................................6-27
Flashing Images..................................................................................................................6-31

Advanced Configuration Concepts Manual Revision 2-INT iii


CHAPTER 7: GRAPHICS BUILDER AUTOMATION INTERFACE 7-1
Overview.............................................................................................................................. 7-1
Automation .......................................................................................................................... 7-2
Placing Symbols on a Page ..................................................................................................7-3
Adding Properties to Objects ............................................................................................. 7-10
Using Genies ...................................................................................................................... 7-13
Drawing Objects on Pages .................................................................................................7-19
CHAPTER 8: CITECTSCADA AND OTHER APPLICATIONS 8-1
Overview.............................................................................................................................. 8-1
CitectSCADA and ODBC....................................................................................................8-2
Data Source Names..............................................................................................................8-3
How CitectHMI/SCADA Uses ODBC ................................................................................8-5

LY
CiRecipe Active X Control................................................................................................8-14
Configuring the ActiveX Control ...................................................................................... 8-16
Editing the Database from CitectSCADA Runtime........................................................... 8-24

N
Updating CitectSCADA Tags............................................................................................8-26
Active X and Citect............................................................................................................ 8-30

O
ActiveX Objects Using Cicode .......................................................................................... 8-34
Using ActiveX Methods ....................................................................................................8-36
Events................................................................................................................................. 8-42
CHAPTER 9: KERNEL AND DEBUGGING
se 9-1
Overview.............................................................................................................................. 9-1
The Citect Kernel................................................................................................................. 9-2
lU
Security and the Kernel........................................................................................................ 9-5
Foreground and Background Tasks .....................................................................................9-8
Page Table Cicode ............................................................................................................. 9-12
na

Probe Command.................................................................................................................9-14
Page Table Stats................................................................................................................. 9-18
The TaskNew() Function ................................................................................................... 9-20
r

Thread Window ................................................................................................................. 9-23


te

Global Variable Window ................................................................................................... 9-25


Stack Window....................................................................................................................9-27
In

CHAPTER 10: PROCESS ANALYST 10-1


Overview............................................................................................................................ 10-1
Process Analyst Active X Control .....................................................................................10-2
ct

Properties of the Process Analyst ......................................................................................10-5


Toolbars ............................................................................................................................. 10-6
ite

Pens .................................................................................................................................... 10-8


Displaying Pens in the Process Analyst............................................................................. 10-9
Pen Types......................................................................................................................... 10-13
C

Interacting with the Process Analyst................................................................................10-18


Configuring Pens .............................................................................................................10-25
Views ............................................................................................................................... 10-40
Object View ..................................................................................................................... 10-45
Customising Toolbars ...................................................................................................... 10-49
Cursor and Cursor Labels ................................................................................................ 10-53
Security and Permissions .................................................................................................10-57

iv CitectHMI/SCADA Version 6.00 August 2005


CHAPTER 11: OPC 11-1
Overview ............................................................................................................................11-1
What is OPC? .....................................................................................................................11-2
Citect OPC Server ..............................................................................................................11-3
Citect OPC Client...............................................................................................................11-9
CHAPTER 12: ALARMS AND TRENDS 12-1
Overview ............................................................................................................................12-1
Alarm Filtering...................................................................................................................12-2
Table Maths........................................................................................................................12-7
CHAPTER 13: COURSE SUMMARY 13-1
Course Evaluation ..............................................................................................................13-2

LY
Further Training .................................................................................................................13-3
Online Course Quizzes.......................................................................................................13-5
Citect Examinations ...........................................................................................................13-6

N
O
se
lU
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT v


LY
N
O
se
lU
nar
te
In
ct
ite
C

vi CitectHMI/SCADA Version 6.00 August 2005


Chapter 1: Introduction to Advanced Configuration
Concepts
Overview

Introduction You can configure a CitectHMI/SCADA monitoring and control system to


suit any industrial application. Because CitectHMI/SCADA has been
designed with flexibility in mind, you can design a system to suit your exact
requirements.

LY
CitectHMI/SCADA suits both small and large applications. Because it is
flexible, CitectHMI/SCADA will keep pace with your plant and information
requirements as they change and expand.

N
CitectHMI/SCADA is easy to learn and use. Programming techniques may

O
be used to customise your application to suit your requirements. Features
such as templates, genies, forms and wizards reduce the time and effort
required to configure your CitectHMI/SCADA system, as well as maximising
performance.
se
lU
Contents This chapter contains the following topics:

Topic See Page


na

¾ Before You Begin 1-2


¾ Course Overview 1-3
r

¾ Conventions Used in this Manual 1-5


te
In
ct
ite
C
Before You Begin

Your Instructor Please write the name of your Instructor here ) ____________________

Your Instructor will be spending the next three days with you, and will guide
you through this training course. Your Instructor is an experienced
CitectHMI/SCADA user so please feel free to ask questions.

Defining the This training manual is a supplement to Citect Certified Training. In order to

LY
Scope of this make full use of the software you should also reference the Online Help and
Training CitectSCADA Knowledge Base.
Manual

N
The graphics displaying screen shots have been taken using the Windows XP
operating system. If you are running a different version of Windows then

O
your screens may differ slightly from the ones shown in the training manual.

se
lU
r na
te
In
ct
ite
C

1-2 CitectHMI/SCADA Version 6.00 August 2005


Course Overview

Course By the completion of this training course you will:


Objectives
¾ Understand how to create and use Custom Templates
¾ Create and use Smart Genies and Smart Popups
¾ Write Forms and Genie Forms
¾ Learn about True Color and the new Color Tools

LY
¾ Use VBA to use the Graphics Builder Automation Interface
¾ Connect CitectSCADA to other Applications
¾ Learn to use the Process Analyst

N
¾ Connect to other SCADA software using OPC

O
¾ Use Alarm Filtering and Table Maths

Course se
Please take a few moments to have a look through your Training Pack. In
lU
Material addition to this manual, you will find the following items:

¾ Citect Compendium
na

¾ Citect Mouse Pad


¾ Pen
r

¾ Notepad
te

¾ Memory Stick
¾ The current version of Plant2Business on CD Rom
In

¾ The current version of CitectHMI/SCADA on CD Rom


ct

Continued on next page


ite
C

Advanced Configuration Concepts Manual Revision 2-INT 1-3


Course Overview, Continued

Course The training course will take three days to complete. The following program
Program outlines the topics that will be covered on each day:

Day Topics
1 ¾ Custom Templates
¾ Smart Genies
¾ Smart Popups and Super Genies

LY
¾ Forms
2 ¾ True Color

N
¾ Graphics Builder Automation Interface
¾ CitectSCADA and Other Applications

O
3 ¾ Kernel and Debugging
¾ Process Analyst
¾
¾
OPC
Alarms and Trends
se
lU
r na
te
In
ct
ite
C

1-4 CitectHMI/SCADA Version 6.00 August 2005


Conventions Used in this Manual

Objectives These are the skills you will achieve by the end of each chapter. An overview
providing a brief synopsis of the topic begins each section. Often, examples
are given to illustrate the conceptual overview.

Example -

Objectives CitectHMI/SCADA is easy to learn and use. Features such as templates,


genies, and wizards reduce the time and effort required to configure your

LY
CitectHMI/SCADA system, as well as maximising performance.

Contents This chapter contains the following topics:

N
Topic See Page

O
¾ Topic A
¾ Topic B
¾ Topic C
se
lU
Exercises After a concept is explained you will be given exercises that practise the skills
you just learned. These exercises begin by explaining the general concept of
each exercise and then step-by-step procedures are listed to guide you through
na

each procedure.

Example –
r
te

Exercise 6-1 Paste a genie from a library in the Include project onto a test page called Utility.
Run the Milk_Upgrade project then trigger and view some alarms.
In

i. Use the following template settings:


ct

Hints and Tips This heading will provide you with useful or helpful information that will
make configuring your project easier
ite

Example –
C

9 Hints & Tips:

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 1-5


Conventions Used in this Manual, Continued

Note A note will refer to a feature which may not be obvious at first glance but
something that you should always keep in mind

Example -

Note:

LY
N
Menus and Text separated by the pipe symbol “|” indicates that you are to go to a menu
Menu Options
Example –

O
File | New…

se
Go to a menu “File” then to the menu option “New…”
lU
Horizontal and Text written this way indicates the Horizontal then the (Vertical) tab you are to
Vertical Tabs choose.
na

Example –

Appearance (General)
r
te

Whenever you are required to type information into a field or dialog box it
In

will be written in this font

Example –
ct

KETTLE_TEMP/25
ite

See Also Text written in this way indicates further references about the current topic.
C

Example –

See Also:
For further information about Templates, see CitectSCADA Help - Using Page
Templates.

1-6 CitectHMI/SCADA Version 6.00 August 2005


Chapter 2: Custom Templates
Overview

Introduction If the pages in your project contain items that are common to all pages such
as toolbars and status bars you can create your own template (containing all
common objects) to use as a base for the pages. You can then create the
pages based on the template, and add individual objects to each page.

If you subsequently decide to delete or change the location of a common

LY
object, or to add a new common object, you do not have to change each page
- you can change the template. CitectHMI/SCADA automatically updates all
pages based on the template.

N
O
Contents This chapter contains the following topics:

Topic See Page


¾ CitectHMI/SCADA Templates
¾ Creating Your Own Templates se 2-2
2-4
lU
¾ Unlinking Templates 2-7
¾ Displaying Alarms 2-12
¾
na

Navigation 2-16
¾ Custom Menus 2-20
¾ Animation Points 2-22
r
te

¾ Applying Templates 2-24


¾ Templates within Templates 2-25
In
ct
ite
C
CitectHMI/SCADA Templates

Getting Started When starting a new project, new pages created can be designed to follow the
“look and feel” that is required. The simplest page is based upon the Blank
template, which is simply a blank window. The developer can then add
objects and functionality to the window and develop new templates for their
project pages.

For a developer with a short development schedule or someone who is new to


CitectHMI/SCADA, there are a number of pre-designed templates that enable

LY
the user to quickly create pages. The standard templates in the Include project
are designed to reliably perform all of the basic functions required in a
project. The Normal page from the Include project looks like this.

N
O
se
lU
r na
te
In
ct
ite

Continued on next page


C

2-2 CitectHMI/SCADA Version 6.00 August 2005


CitectHMI/SCADA Templates, Continued

CSV Templates The CSV_Include Project is a preconfigured project that is installed with
CitectHMI/SCADA Version 5.5 or later. Designed to reduce the amount of
time required to configure a new project, it includes a set of templates and
pages styled for the Windows XP environment.

When a new CitectSCADA project is created, the CSV_Include project is


automatically incorporated as an included project. This means that all of the
project's templates and associated content are available for implementation

LY
when creating your graphics pages in the Citect Graphics Builder. The
project created using these templates will have a Windows XP design style.
This is the Normal page from the CSV_Include.

N
O
se
lU
r na
te
In

Alongside a standard graphics page template for the creation of plant graphic
ct

pages, the project includes predefined trend and alarm display pages, an
administration tools page, a file page for displaying text and Rich Text
ite

Format files, and a selection of popup windows. All feature common


navigation and alarm menus for consistent functionality and appearance
across an entire project. The project even supports multi monitor display,
C

allowing a number of graphics pages to be simultaneously displayed across


several computer screens.

Advanced Configuration Concepts Manual Revision 2-INT 2-3


Creating Your Own Templates

Overview Most projects create templates that are designed specifically for the site. The
templates that we will be creating in this chapter will be based on the standard
templates.

How to ¾ To create a new template:


Double click on the Create a new template button in Citect
Explorer,

LY
or

N
click on the New button in the Graphics Builder,

O
or

select the menu File | New… in the Graphics Builder

se Continued on next page


lU
r na
te
In
ct
ite
C

2-4 CitectHMI/SCADA Version 6.00 August 2005


Creating Your Own Templates, Continued

Exercise 2-1

Step Action
1 Create a new Normal template for the pages in your Milk
project.
i. Create a new Template in your Milk project – use the following
template settings:

Style standard

LY
Linked
Title Bar
Resolution XGA

N
Template Blank

O
ii. Save your template in the Milk project, naming it Normal.
Untick the Title Bar box. Click OK.
iii.
se
When you click OK you will see this error message appear.
lU
r na
te

iv. Click Yes. In the dialog provided create a new style called
Training. Click OK to create the style.
In
ct
ite
C

v. Click OK to save the template.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 2-5


Creating Your Own Templates, Continued

Exercise 2-1 (continued)

Step Action
vi. You will see this warning message. Click OK.

LY
N
vii. Select File | Properties from the menu. Open the Appearance
tab and choose a Background Colour: for your template.

O
se
lU
r na
te
In
ct
ite

viii. Click OK and save your template.


C

2-6 CitectHMI/SCADA Version 6.00 August 2005


Unlinking Templates

Standard There are many features in the standard templates that you may wish to
Templates incorporate into your own templates. The standard templates in the included
projects are provided so that you have examples to use within your own
projects. You can copy these features from the included templates into your
new designs.

Exercise 2-2

LY
Step Action
1 Add a Title Bar to your template.

N
i. Add a filled rectangle to the top of your page to form your title
bar.

O
2 Use some of the features from one of the XP_Style templates
on your new Normal template.
i. Choose File | Open from the menu and choose the normal

se
xp_style template from the csv_include project.
lU
r na
te
In
ct

ii. Look at the top right hand corner of the template. Select the
ite

objects on the middle toolbar and copy them onto the top of
your new template underneath your Title Bar. They are the
text object =UserInfo(1), the rectangle behind the text object
and the page wide toolbar. This will form your Utility
C

Toolbar.

Select these
three objects

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 2-7


Unlinking Templates, Continued

Exercise 2-2 (continued)

Step Action
2 iii. Double click the Utility Toolbar rectangle to open the
(cont.) properties of the object. Remove the Fill property from the
object. You may also change the colours of the rectangle if
you wish.

LY
N
O
se
lU
r na
te

iv. Return to the CSV_Include Normal template and copy the red
In

Close button . You may need to ungroup the title bar


objects before you can select the Close button.
v. Paste the close button onto the top right hand corner of your
page.
ct

vi. Double click the button to remove the properties inherited from
the CSV_Include project. Add this expression to the button.
ite

Input (Touch) Access (General)


C

Up command Tool tip:


ShutdownForm() Close

Continued on next page

2-8 CitectHMI/SCADA Version 6.00 August 2005


Unlinking Templates, Continued

Exercise 2-2 (continued)

Step Action
2 vii. Look at the bottom right hand corner of the CSV_Include
(cont.) Normal template. Select the two text objects and the
background toolbar. Copy and paste those three objects onto
your template.

LY
Toolbar
Text Objects

N
viii. Replace the standard CitectSCADA symbol with the

O
CES_Logo symbol from your Icons library onto the page
above the two text objects.

se
lU
na

Continued on next page


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 2-9


Unlinking Templates, Continued

Exercise 2-2 (continued)

Step Action
3 Add the standard items to the Utility Toolbar.
i. Move animation points 1 and 2 to the top toolbar. These
animation points (ANs) display the Keyboard Echo and the
Prompt. Choose Tools | Goto Object from the menu.

LY
N
O
se
lU
r na
te
In

ii. Double click Animation Point AN1. This will open a dialog
showing the properties of AN1.
ct
ite
C

Continued on next page

2-10 CitectHMI/SCADA Version 6.00 August 2005


Unlinking Templates, Continued

Exercise 2-2 (continued)

Step Action
iii. When this dialog opens change the X and Y Coordinates to
100. This will allow you to find the animation numbers.
Repeat this step to find AN2.

LY
N
iv. Move both of the ANs to the Utility toolbar. You might like to
add rectangles behind them to assist with their visibility.

O
 se
lU
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 2-11


Displaying Alarms

Overview You may decide to display the most recent alarms on all pages. The function
AlarmDsp() displays an alarm list, starting at a specified AN and then on
subsequent ANs. This functionality has been used on the standard pages
provided in the CSV_Include project.

LY
N
Cicode Object You specify the number of alarms to display and the type of alarms, for
example, active hardware alarms or disabled non-hardware alarms. Before

O
you call this function, you must first add animation points to the graphics
page for each alarm to be displayed. Each of the animation points must be
consecutive numbers. You can check the AN number by opening the Access

se
(General) tab of the Cicode Object. The AN number below is 17.
lU
r na
te
In

Continued on next page


ct
ite
C

2-12 CitectHMI/SCADA Version 6.00 August 2005


Displaying Alarms, Continued

Exercise 2-3

Step Action
1 Create a toolbar to display the most recent alarms.
i. Draw a black rectangle on the bottom toolbar that you placed
on your page in the previous exercise.

ii. Place three Cicode Objects on the left hand side of the

LY
rectangle. Ensure that the AN numbers are consecutive.

N
O
iii. Open the properties of the first Cicode Object. Go to the

se
Cicode General tab and add the AlarmDsp() function. The first
argument of this function is the AN number of the Cicode
object. Check your own AN number. The second argument is
the number of alarms to display. The third argument is the
lU
type. In this case we will be displaying all active alarms so the
mode will be 0.
r na
te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 2-13


Displaying Alarms, Continued

Exercise 2-3 (continued)

Step Action
iv. Add a command to enable the operator to acknowledge the
alarm by clicking the alarm. This command will need to be
placed into all three Cicode Objects. Use these settings:

Input (Keyboard Commands) ‘LBUTTON_CMD_UP’

LY
Key Sequence command
LBUTTON_CMD_UP AlarmAck(0,0)

N
2 Add symbols to your Normal template to indicate active alarms.
i. Use Windows Explorer to copy the file csv_icons.ctl from the

O
CSV_Include project into your Milk project.
ii. Add two Symbol Sets to the top left hand corner of the Utility
Toolbar. This is the toolbar where you previously placed AN1

se
and AN2. You may need to resize the toolbar to fit the symbol
sets.
lU
na

Use these settings:


r

iii.
te

Symbol Set Current Alarms Hardware Alarms


In

Appearance AlarmActive(1) AlarmActive(6)


(General)
Animate when
ct

Input (Touch) PageAlarm() PageHardware()


Up command
ite

Symbols OFF csv_icons.aalarm_01_ csv_icons.halarm_01_


xp xp
Frame 1 csv_icons.aalarm_02_ csv_icons.halarm_02_
C

xp xp
Frame 2 csv_icons.aalarm_01_ csv_icons.halarm_03_
xp xp

Continued on next page

2-14 CitectHMI/SCADA Version 6.00 August 2005


Displaying Alarms, Continued

Exercise 2-3
(continued)

Step Action
2 9 Hints & Tips:
(cont.)
The functions PageAlarm(), PageHardware() and PageSummary()
are set by default to open pages named Alarm, Hardware and
Summary respectively. If you wish to use different names for the

LY
alarm pages you may enter custom names for these pages in the
Citect.ini file. Set the INI parameters [Page] AlarmPage,
HardwarePage and SummaryPage to the custom names for your
pages.

N
O
iv. Save the template.


se
lU
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 2-15


Navigation

Overview Large CitectHMI/SCADA projects can often contain a significant number of


pages. It is common to have side toolbar and drop down menus that take the
user to other pages, or groups of pages in the project. In this section we will
add side toolbars and drop down menus to the template.

Side Toolbars Side toolbars have been used in CitectSCADA projects for many years.
Typically these toolbars have a flyout that contains links to a related group of

LY
pages.

Continued on next page

N
O
se
lU
r na
te
In
ct
ite
C

2-16 CitectHMI/SCADA Version 6.00 August 2005


Navigation, Continued

Exercise 2-4

Step Action
1 Create a popup page that will contain navigation buttons to the
production pages in your project.
i. Open the Citect Graphics Builder and create a new page based
on the Blank template.
ii. Add four buttons to the top left hand corner of the page.

LY
N
O
iii. Add these properties to the four buttons.

Appearanc
e (General)
Symbol
Input (Touch)
Up Command
se Access (General)
Tool Tip
lU
icons.cow WinFree();WinGoto(0); Pasteurisation
PageDisplay(“gr_Past”) Page
icons.carton WinFree();WinGoto(0); Recipe Page
na

PageDisplay(“gr_Recipe”)
icons.silo WinFree();WinGoto(0); Silo Page
PageDisplay(“gr_Silos”)
r
te

csv_icons.d WinFree();WinGoto(0);
isabled_01_
xp
In

iv. Choose File | Properties from the menu. Change the View
area of the page so that only the buttons are visible.
ct

v. Save the page as !ProdMenu.


ite

Continued on next page


C

Advanced Configuration Concepts Manual Revision 2-INT 2-17


Navigation, Continued

Exercise 2-4 (continued)

Step Action
2 Create a popup page that will contain navigation buttons to the
alarm pages in your project.
i. Change the buttons to use these settings.

Appearance (General) Input (Touch) Access (General)


Symbol Up Command Tool Tip

LY
csv_icons.AAlarm_01_xp WinFree(); Current Alarms
WinGoto(0);
PageAlarm()

N
csv_icons.SAlarm _01_xp WinFree(); Summary Alarms
WinGoto(0);

O
PageSummary()
csv_icons.HAlarm _01_xp WinFree(); Hardware
WinGoto(0); Alarms

csv_icons.disabled_01_xp se
PageHardware()
WinFree();
lU
WinGoto(0);

ii. Save the page.


na

3 Create a popup page that will contain navigation buttons to the


miscellaneous pages in your project.
i. Save your !ProdMenu page as !UtilityMenu.
r

ii. Change the buttons to use these settings.


te

Appearance Input (Touch) Access


In

(General) Symbol Up Command (General)


Tool Tip
csv_icons.note_03_ WinFree(); Forms Page
ct

xp WinGoto(0);
PageDisplay(“gr_Forms”)
ite

Blank Text WinFree();


WinGoto(0);
PageDisplay(“ ”)
C

Blank Text WinFree();


WinGoto(0);
PageDisplay(“ ”)
csv_icons.disabled WinFree();
_01_xp WinGoto(0);

iii. Save the page.

Continued on next page

2-18 CitectHMI/SCADA Version 6.00 August 2005


Navigation, Continued

Exercise 2-4 (continued)

Step Action
4 Add the side toolbar buttons to your page.
i. Return to your Normal template.
ii. Place four buttons on the page in the top left hand corner of
the page.

LY
N
O
se
lU
iii. Use these settings in the buttons.
na

Appearance Input (Touch) Access


(General) Up Command (General)
r

Symbol Tool Tip


te

icons.milk WinNewAt("!ProdMenu", Production


48,72,1+8+16+128) Menu
In

csv_icons.AAlar WinNewAt("!AlarmMenu", Alarm Menu


m_01_xp 48,120,1+8+16+128)
csv_icons.tools_0 WinNewAt("!UtilityMenu", Utility Menu
ct

1_xp 48,168,1+8+16+128)
csv_icons.Back Last Page
ite

PageLast()
_02_White
C

Note: You will need to substitute the X and Y coordinates for


the WinNewAt() function that are correct for your
template.

iv. Save the template.

Advanced Configuration Concepts Manual Revision 2-INT 2-19


Custom Menus

Overview Drop-down menus are capable of calling a Cicode function or navigating to a


specific page. This allow the user to have point and click functionality
throughout the project with Windows-style popup and context sensitive
menus

The function DspPopupMenu() creates a popup menu consisting of a number


of menu items. Multiple calls to this function enable you to add new items
and create sub menus, building a system of linked, Windows-style menus.

LY
Menu items can be displayed as checked and/or disabled. You can also
specify a bitmap to display as a menu icon.

N
The first call to this function builds the menu items.

O
Example –

The expression,
se
DspPopupMenu(0,"Item1, !Item2, ~Item3");
lU
builds a menu with three items:

¾ 'Item 1' will be shown as normal


na

¾ 'Item 2' will be shown as disabled,


¾ 'Item 3' will be shown as checked.
r
te

The second call to this function displays the menu on the screen.
In

Example –

The expression,
ct

iSelection = DspPopupMenu(-1, " ", 20, 40);


ite

displays the menu at position (20, 40) and returns the number of the selected
item as an integer.
C

Continued on next page

2-20 CitectHMI/SCADA Version 6.00 August 2005


Custom Menus, Continued

Exercise 2-5

Step Action
1 Add a title to your page.
i. Open the Cicode Editor and open a new file. Save the file as
Menu.ci.
ii. Create a new function called PageTitle(). This function will
return the title of the current page as a String.

LY
STRING

N
FUNCTION
PageTitle()

O
STRING sTitle;
sTitle = PageInfo(2);

END se
RETURN sTitle;
lU
iii. Save the file.
iv. Place a String object that will run your new function on the title
na

bar of your Normal Template.


r
te
In


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 2-21


Animation Points

Overview Each point on a graphics page where an object is displayed is called an


animation point. When you add an object (text, symbols, pipes, etc.) to your
page, CitectHMI/SCADA automatically allocates a number (termed an AN)
to the animation point. The number of objects that you can use is limited by
the performance of your computer, though this would rarely be a problem. A
good rule of thumb is to try and keep the number of objects (and hence ANs)
less than 3000.

LY
Reserved ANs

N
CitectHMI/SCADA uses the first 2 ANs for automatically displaying system
information such as messages, alarm information and page details. In some

O
applications, such as trend pages, some other ANs are reserved.

When you create your own templates a good practice is to reserve your own

se
animation points for later use. This practice allows for the possibility of
adding new objects to your templates at a later stage. When an object is
added to a page based on one of your templates it will use the next available
lU
AN number.
r na
te
In

If at some later stage you decide to make changes to your template any object
you place on the template will use the next animation point.
ct
ite
C

When you then update your template the two AN numbers will conflict. In
order to prevent this from happening reserve animation numbers in your
template. If at some later stage you decide to add more objects delete one of
your reserved animation numbers first.

Continued on next page

2-22 CitectHMI/SCADA Version 6.00 August 2005


Animation Points, Continued

Exercise 2-6

Step Action
1 Reserve twenty animation points to your normal template.
i. Return to your Normal template.
ii. Choose Tools | Options from the menu.
iii. Select the option Show version 3.xx/4.xx tools.

LY
N
O
se
lU
iv. Select the Animation Point tool.
v. Add twenty Animation Points to your page. A good place to add
these is outside the visible boundaries of the page.
r na
te
In

vi. Save the template.


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 2-23


Applying Templates

Exercise 2-7

Step Action
1 Apply the completed template to your pages.
i. Open the page gr_Past.
ii. Choose File | Properties from the menu. Open the
Appearance tab and change the Style to training.

LY
N
O
se
lU
r na
te

iii. Save the page.


In

iv. Change the Template Style of all your pages to the training
style.
ct


ite
C

2-24 CitectHMI/SCADA Version 6.00 August 2005


Templates within Templates

Exercise 2-8 Once you have created your basic template you can use that template as the
basis for your other templates. This way if you need to make changes to all of
the templates you only need to make the change on the original template.
When the templates are updated the templates based on the original will also
change.

LY
Step Action
1 Create Alarm templates based on your new Normal template.
i. Return to the Citect Graphics Builder and create a new
Template based on the Normal training template.

N
O
se
lU
r na
te
In

ii. Add a black rectangle to the page to create a background for


the alarms.
iii. Place a Cicode object in the top left hand corner of the
ct

rectangle.
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 2-25


Templates within Templates, Continued

Exercise 2-8 (continued)

Step Action
1 iv. Add these settings to the Cicode object.
(cont.)

Cicode (General) Input (Keyboard ‘LBUTTON_CMD_


Command Commands) UP’ command
Key Sequence

LY
AlarmDsp(21,25,0) LBUTTON_CMD_UP AlarmAck(0,0)

N
Note: The first argument of the AlarmDsp() function is the AN
number of the Cicode object itself. The second

O
argument is the number of alarms to be displayed on the
page. You will need to check your own Cicode object
and apply the appropriate values for your page.

v. se
Add Scroll Up and Scroll Down buttons to the right side of the
page so that you can scroll to another page of alarms. Use the
lU
functions AlarmDspNext(21) and AlarmDspPrev(21). Again
check that the argument is the same AN number as your first
Cicode object.
vi. Save the template as Alarm.
na

Continued on next page


r
te
In
ct
ite
C

2-26 CitectHMI/SCADA Version 6.00 August 2005


Templates within Templates, Continued

Exercise 2-8 (continued)

Step Action
2 Create a Summary alarm template.
i. Save the Alarm template as Summary.
ii. Change the Cicode (General) Command in the first Cicode
object so that the Type argument is 10. This will display all
Summary alarms.

LY
N
O
se
lU
r na
te
In

iii. Save the Summary template.


3 Repeat this procedure to create a Hardware alarm template.
Hardware is Type 5.
ct

4 Create alarm pages for your project.


i. Create a page for current alarms, a summary alarm page and
ite

a hardware alarm page. Name the pages Alarm, Summary


and Hardware.
ii. Run your project to test your new pages.
C

Advanced Configuration Concepts Manual Revision 2-INT 2-27


LY
N
O
se
lU
nar
te
In
ct
ite
C

2-28 CitectHMI/SCADA Version 6.00 August 2005


Chapter 3: Smart Genies
Overview

Introduction Usually each graphical object on a graphics page is configured individually.


With a genie, you can combine several related objects into a group and store
the group in a genie library (similar to a symbol library). The genie can then
be used as if it was a single object (pasted, moved, resized, etc.) and the
elements of the genie are then configured collectively.

LY
Simple Genies were covered in the Citect Configuration Course. This chapter
will take genies several steps further

N
O
Contents This chapter contains the following topics:

Topic See Page


¾ Genies – Revision
¾ Genies inside Genies se 3-2
3-6
lU
¾ Structured Tag Names 3-12
¾ Using Structured Tag Names with Genies 3-14
¾
na

Smart Genies 3-19


¾ Genie Forms 3-29
r
te
In
ct
ite
C
Genies – Revision

Exercise 3-1 The Citect Configuration Training course explains how to create simple
genies. The first part of this chapter will revise simple genies.

Step Action
1 Create a new genie with a numeric object that will display the
value a milk level tag and a command to change the value.

i. Click on the New button on the toolbar. The following


dialog will be displayed:

LY
N
O
se
lU
r na

ii. Click the Genie button. A blank page will be displayed, with a
te

Genie Locator Point (this is reference point when the


genie is pasted onto a graphics page).
In

iii. Click on the Numeric tool and click near the Genie Locator
Point to place a numeric object.
ct

Continued on next page


ite
C

3-2 CitectHMI/SCADA Version 6.00 August 2005


Genies – Revision, Continued

Exercise 3-1 (continued)

Step Action
1 iv. Insert %TAG% into the Numeric expression field, as shown:
(cont.)

LY
N
O
se
lU
na

v. Go to the Input (Keyboard Commands) properties and


complete the dialog as shown:
r
te
In
ct
ite
C

%Tag% = ArgValue1

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 3-3


Genies – Revision, Continued

Exercise 3-1 (continued)

Step Action
1
(cont.)
Note: This is a level indicator not a controller. In a real
situation you would not need an Input command. This
is for the purpose of the training course only so that you
can change the values in your Disc PLC.

LY
vi. Click on OK.
vii. Draw a filled rectangle object behind the numeric object for
display purposes.

N
O
viii.
se
Click on Save. Create a new library called Training.
lU
r na
te

ix. Save the new genie with the name Silo_Level_1 into the
training library.
In

Continued on next page


ct
ite
C

3-4 CitectHMI/SCADA Version 6.00 August 2005


Genies – Revision, Continued

Exercise 3-1 (continued)

Step Action
2 Paste the Genie on to a graphics page.
i. Open the page called Genies.

ii. Use the Paste Genie tool to paste the Silo_Level_1 genie
onto your Genies page under the heading Simple Genies.

LY
Specify the tag Silo_TI_1_PV in the TAG field.
iii. Your page should look like this.

N
O
se
lU

r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 3-5


Genies inside Genies

Overview A genie may be used to combine several objects together and paste them onto
a page as one object. Genies are also reusable.

A little known bonus is that Genies can be used inside genies!

Example –

Valve_Simple is a genie with a simple valve symbol set with the genie syntax

LY
%Valve%

N
O
se
lU
r na
te

Continued on next page


In
ct
ite
C

3-6 CitectHMI/SCADA Version 6.00 August 2005


Genies inside Genies, Continued

Overview You would like to create a new genie that displays the value of an integer tag
(continued) that is related to a valve object. A new genie may be created that uses the
original genie. When the numeric object is pasted onto the page it would be
configured normally.

LY
N
O
se
lU
r na

When the Valve_Simple genie is added its syntax will need to be passed
te

through the new genie. In this situation genie syntax is used for the genie
substitution.
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 3-7


Genies inside Genies, Continued

Overview When you hold down the control key and double click the Valve_Simple
(continued) genie you will see that the new syntax has been substituted.

LY
N
O
se
lU
The effect is that when the new genie is pasted onto a page the user is asked
na

for both substitutions.


r
te
In
ct

Continued on next page


ite
C

3-8 CitectHMI/SCADA Version 6.00 August 2005


Genies inside Genies, Continued

Exercise 3-2

Step Action
1 Use the genie that you created in the previous exercise to
create a new genie that displays the value of three tags.
i. Return to the Citect Graphics Builder and create a new genie.
ii. Paste the Silo_Level_1 genie onto the new genie page three
times. Use this genie syntax for each of the three instances of

LY
the genie.

Genie Syntax

N
%Temp%

O
%Level%
%MilkAge%

se
Notice that when you hold down the control key and double
click one of the numeric objects you will see that the new
genie syntax has passed through into the original genie and
lU
replaced the syntax %Tag%.
r na
te
In
ct
ite
C

iii. Save the genie as Silo_Level_2.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 3-9


Genies inside Genies, Continued

Exercise 3-2 (continued)

Step Action
2 Paste the genie on to the graphics page.
i. Open the page called Genies.

ii. Use the Paste Genie tool to paste the Silo_Level_2 genie
onto your Genies page under the heading Genie in Genie.

LY
The genie dialog will open asking you to insert tags into the
three fields that you specified in the genie.

N
O
se
lU
iii. Substitute the three tags for Silo 1.

Temp
na

Silo_TI_1_PV
Level Silo_LI_1_PV
MilkAge Silo_AOMI_1_PV
r
te

iv. Add another genie for Silo 2 using these tags.


In

Temp Silo_TI_2_PV
Level Silo_LI_2_PV
ct

MilkAge Silo_AOMI_2_PV
ite

Continued on next page


C

3-10 CitectHMI/SCADA Version 6.00 August 2005


Genies inside Genies, Continued

Exercise 3-2 (continued)

Step Action
2 v. Your page should look like this.
(cont.)

LY
N
O
se
lU
3 Save the page and compile.
na


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 3-11


Structured Tag Names

Overview Citect puts few restrictions on the names of variable tags, but you will benefit
from using a tag naming convention. By using a tag naming convention, your
project will be easier and faster to design, configure, and commission, and
will require less time for future maintenance.

The following naming convention is recommended for a CitectHMI/SCADA


system - to obtain maximum benefit when using features such as Genies and
Super Genies.

LY
Each tag name can contain up to 32 characters. To establish a convention,
you must divide the characters in the tag name into sections that describe

N
characteristics of the tag, for example, the area where the tag is located, the
type of variable, and any specific attributes. Four basic sections are suggested

O
for a CitectHMI/SCADA naming convention:

Area_Type_Occurrence_Attribute

See Also:
se
For further information about Structured Tag Names, see Citect Help Topics -
lU
Using Structured Tag Names.
na

Area The Area section identifies a plant area, number, or name. If you use a prefix
that identifies tags within a particular area, you can easily duplicate all
r

CitectHMI/SCADA functions within the area. For example, if you have three
te

pasteurisers with the same controls on each pasteuriser, you can configure the
tags for pasteuriser number one, and copy the tags to pasteurisers two and
In

three. You then only need to change the area section in the tag names to the
area of the second and third pasteuriser. The remainder of the tags remain
unchanged, for example:
ct
ite

Pasteuriser 1 Pasteuriser 2 Pasteuriser 3


P1_TIC_101_PV P2_TIC_101_PV P3_TIC_101_PV
C

If you do not need this facility, you can omit the Area section of the Tag
Name to reduce the number of characters in the tag.

Continued on next page

3-12 CitectHMI/SCADA Version 6.00 August 2005


Structured Tag Names, Continued

Type The Type section identifies the Type of parameter, process equipment, or
control hardware. The ISA standard naming system is recommended.

Variable Tag Meaning


P1_TIC_101_PV Temperature indicating controller
P1_FIC_101_PV Flow Indicating controller
P1_PUMP_101_PV Pump
P1_VALVE_101_PV Valve

LY
Occurrence The Occurrence section identifies the equipment number.

N
Variable Tag Meaning

O
P1_TIC_101_PV Temperature indicating controller 101
P1_TIC_102_PV Temperature indicating controller 102
P1_PUMP_101_PV Pump 101
P1_PUMP_102_PV Pump 102
se
lU
Attribute The Attribute section identifies the attribute or particular parameter that is
associated with the equipment.
na

Variable Tag Meaning


P1_TIC_101_PV Process Variable
P1_TIC_101_SP Setpoint
r

P1_TIC_101_OP Output
te

P1_TIC_101_P Gain or proportional band


P1_TIC_101_I Integral
In

P1_TIC_101_CMD Command signal to start pump


P1_TIC_101_M Auto/Manual mode
P1_TIC_101_V Value (running/stopped)
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 3-13


Using Structured Tag Names with Genies

Overview Using structured tag names provides more power when using Genies and
Super Genies. Most Genies refer to the same physical device, and therefore
using similar tag names for each element in the device reduces project
configuration.

Genie When you define a Genie, you can add a prefix or suffix to a Genie property
Definition to generate the complete tag when the Genie is used. For example, if you

LY
define a Genie property as %Name%_Valve, and then use Malt for the tag, the
Genie will generate the complete tag Malt_Valve.

N
You can add extra information at the beginning (prefix), or on the end (suffix)
of the Genie property, or use both a prefix and suffix in the same Genie

O
property. For example, if you have defined a loop controller with three bar
graphs (created using the fill property in a rectangle) to display the tags
DEV1_PV, DEV1_SP and DEV1_OP, you can configure a Genie as follows:

se
lU
na

When you configure the Genie (with the Genie dialog), you have to enter
three separate tags: DEV1_PV, DEV1_SP and DEV1_OP.
r
te
In
ct
ite
C

Continued on next page

3-14 CitectHMI/SCADA Version 6.00 August 2005


Using Structured Tag Names with Genies, Continued

Structured Tag However, if you use structured tags, you can configure the rectangles as
Definition follows:

LY
In this case, you need only enter one tag (DEV1) to generate six objects.

N
O
se
lU
The Genie automatically concatenates DEV1 with either _PV, _SP, or _OP,
depending on where the tag is substituted. As well as a reduction in
na

configuration time, this Genie is easier to maintain.

Continued on next page


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 3-15


Using Structured Tag Names with Genies, Continued

Exercise 3-3 Create a new genie that uses structured tag names to substitute the tags into
the genie syntax.

Step Action
1 Create a new genie.
i. Return to the Citect Graphics Builder and open the
Silo_Level_2 genie that you created in the last exercise.
ii. Create a copy of the genie by saving it as Silo_Level_3.

LY
iii. Change the genie syntax in the three text objects to take
advantage of the structured tag names.

N
O
se
lU
Use these values for the three genie text objects to pass
through to the original genie Silo_Level_1.
na

Value Genie Syntax


Temp Silo_TI_%Silo_No%_PV
Level Silo_LI_%Silo_No%_PV
r
te

MilkAge Silo_AOMI_%Silo_No%_PV
In

Continued on next page


ct
ite
C

3-16 CitectHMI/SCADA Version 6.00 August 2005


Using Structured Tag Names with Genies, Continued

Exercise 3-3 (continued)

Step Action
iv. Hold down the control key and double click each of the text
objects. You should see that the new syntax has passed
through the genie Silo_Level_1 to the original text object.

LY
N
O
se
lU
r na
te

v. Save the genie.


In

Continued on next page


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 3-17


Using Structured Tag Names with Genies, Continued

Exercise 3-3 (continued)

Step Action
2 Paste the genie on to the graphics page.
i. Open the page called Genies.

ii. Use the Paste Genie tool to paste the Silo_Level_3 genie
onto your Genies page under the heading Structured Tags.

LY
The genie dialog will open asking you to insert tags into the
three fields that you specified in the genie.

N
O
iii.
se
Hold down the control key and double click each of the text
lU
objects. You will see that the silo number has been substituted
into each of the tags.
r na
te
In
ct
ite
C

iv. Add another genie for Silo 2.

3-18 CitectHMI/SCADA Version 6.00 August 2005


Smart Genies

IfDef Macro One of the key benefits of using genies is that they are reusable. However,
sometimes you may wish to use a genie that has been configured for multiple
tags but you do not need to use all of the tags. This creates a problem when
adding the tags and compiling. If we use the Silo_Level_3 genie created in the
last exercise to display the values of Silo 3 there will be a tag not found error
as the tag Silo_AOMI_3_PV does not exist.

LY
N
O
se
lU
na

The IFDEF macro allows you to define two possible outcomes based on
whether or not a specified tag exists within a project at the time of compiling.
r

The macro can be implemented anywhere a simple expression is used,


te

including fields within relevant CitectHMI/SCADA dialogs. By allowing a


"0" or "1" to be generated within the Hidden When field of a genie’s
In

properties, elements could simply be hidden if a required tag was missing,


allowing the genie to still be pasted onto a graphics page.
ct

The macro accepts three arguments: the first specifies the tag that requires
confirmation, the second defines the outcome if the tag exists and the third
ite

defines the outcome if it does not exist. In the case of a genie being pasted on
a graphics page, the IFDEF function would be configured as follows in the
Hidden When field of the object properties dialog:
C

IFDEF("Silo_AOMI_3_PV",0,1)

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 3-19


Smart Genies, Continued

IfDef Macro If the tag "Silo_AOMI_3_PV" is defined in the tag database, the value in the
(continued) Hidden When field will be 0. If Silo_AOMI_3_PV is undefined, the value will
be 1. Since the object is hidden when the value is TRUE (1), the object will
be hidden when Silo_AOMI_3_PV is undefined. See the topic Hiding Graphics
Objects for more information.

Beyond this purpose, the IFDEF macro can be broadly used as a conditional
variable. The [<value if defined>] and <value if not defined> arguments can

LY
support any variable, expression, or constant. The [<value if defined>]
argument is optional – if you leave it blank it will generate the current
variable. You can also use nested IFDEF macros.

N
See Also:

O
For further information about the IFDEF Macro, see CitectSCADA KB Article
Q3461 - IFDEF() Generic Genie Enhancement.

se Continued on next page


lU
r na
te
In
ct
ite
C

3-20 CitectHMI/SCADA Version 6.00 August 2005


Smart Genies, Continued

TagWrite The IFDEF macro will not allow you to write a value to a variable tag as it
Function only checks to see whether the tag exists. If you wish to write to a tag you
will need to add an expression into one of the Input commands.

%Tag%= ArgValue1

When the genie is placed on the page the tag name is substituted and it is then
possible to input values into the tag. However, in the case of Silo 3 we know

LY
that one of the expected tags does not exist and the compile error would look
like this.

Silo_AOMI_3_PV= ArgValue1

N
If the tag does not exist then an error will be generated when the project is

O
compiled.

se
lU
r na
te

The function TagWrite() allows you to write to a tag using this format

TagWrite(sTag, sValue, nOffset)


In

The arguments are:


¾ the tag name as a string
ct

¾ the value you wish to write to the tag


ite

¾ the array index of the sTag argument (optional)


By using TagWrite() the Citect compiler in this instance does not care if the
C

tag exists because the tag is being treated as a string. Therefore, the project
will compile.

TagWrite("Silo_AOMI_3_PV", ArgValue1);

If the function was performed at runtime, you would however get a hardware
alarm saying that the TagWrite() failed. This will not be the case in this
example because if the tag did not exist, the 'Visibility' option entered
previously would have ensured that the tag was not shown and the keyboard
entry would not be available.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 3-21


Smart Genies, Continued

Exercise 3-4

Step Action
1 Create a new genie that uses the IFDEF macro to check for the
existence of a tag.
i. Open the genie Silo_Level_1 and save it as Silo_Level_4.
ii. Open the Appearance (Display Value) tab and add this
expression.

LY
IfDef("%Tag%",,0)

N
O
Note: When the second argument is left blank the function will
generate the current value for the specified tag

se
lU
r na
te
In
ct
ite

Continued on next page


C

3-22 CitectHMI/SCADA Version 6.00 August 2005


Smart Genies, Continued

Exercise 3-4 (continued)

Step Action
1 iii. Open the Appearance (Visibility) tab and add this expression.
(cont.)

IfDef("%Tag%",0,1)

LY
N
O
se
lU
r na
te

9 Hints & Tips:


In

If you added a filled rectangle object behind the numeric object for
display purposes add the IFDEF macro to the Hidden when property
in the Appearance (Visibility) tab of the rectangle as well.
ct
ite

Continued on next page


C

Advanced Configuration Concepts Manual Revision 2-INT 3-23


Smart Genies, Continued

Exercise 3-4 (continued)

Step Action
2 Use the TagWrite function to allow the compiler to ignore the
keyboard command if the tag does not exist.
i. Open the Input (Keyboard Commands) tab and replace the
original expression with the new TagWrite() expression.

LY
TagWrite("%Tag%",ArgValue1)

N
O
se
lU
r na
te
In
ct
ite
C

Continued on next page

3-24 CitectHMI/SCADA Version 6.00 August 2005


Smart Genies, Continued

Exercise 3-4 (continued)

Step Action
2
(cont.)
Note: This tag is a process variable and in a real situation
would not need a controller. It is being used for the
purpose of the training exercise only so that you may
change the values in your Disk PLC.

LY
ii. Save the genie.

N
3 Create a new genie similar to the genie Silo_Level_3. This

O
genie will display three numeric objects.
i. Create a New genie.
ii.
iii.
se
Paste the genie Silo_Level_4 onto the page three times.
Add the genie syntax for each of the three tags making use of
the structured tag names.
lU
Variable Tag Genie Syntax
Temp Silo_TI_%Silo_No%_PV
Level Silo_LI_%Silo_No%_PV
na

MilkAge Silo_AOMI_%Silo_No%_PV
r

iv. Save the genie as Silo_Level_5.


te

4 Paste the genie on to the graphics page.


i. Open the page called Genies.
In

ii. Use the Paste Genie tool to paste the Silo_Level_5 genie
onto your Genies page under the heading Smart Genies. Add
ct

three genies to the page for the silos. Add these values for
each silo.
ite

Silo Value
C

Silo 1 1
Silo 2 2
Silo 3 3

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 3-25


Smart Genies, Continued

Exercise 3-4 (continued)

Step Action
5 Run the project to test your genies.
i. Open the page Genies.
ii. The objects on your page should look like this.

LY
N
O
se
lU
na

6 Shutdown your project.


7 Create the final Silo genie.
i. Open the genie Silo_Level_5.
r
te

ii. Paste the symbol tanks.Silo into your genie. Position the Silo
symbol behind the three text objects.
iii. Add a rectangle to the genie to indicate the level of the Silo as
In

a bar graph. Use the genie syntax Silo_LI_%Silo_No%_PV in


the Fill | Level property. Your completed genie should look
like this.
ct

8 Save the genie as Silo.


9 Paste the Silo genie onto your Genies page. Use 1 in the genie
ite

field.
10 Run the project and test the genie.
C


Continued on next page

3-26 CitectHMI/SCADA Version 6.00 August 2005


Smart Genies, Continued

Exercise 3-5

Step Action
1 Create a genie that will control a pump and display the speed
of the pump.
i. Open the Citect Graphics Builder and create a New genie.
ii. Paste a pump to display the status near the Locator point,
using the Symbol Set tool. Use these settings.

LY
Symbols OFF pumps_base_small.left_red
ON pumps_base_small.left_green

N
ON symbol when IfDef("%Tag%_Pump_Run",,0)
Visibility IfDef("%Tag%_Pump_Run",0,1)

O
(Hidden when) OR
IfDef("%Tag%_Pump_Man",0,1)

Symbols
iii.

se
Paste a Hand to display the auto/manual status near the pump
using the Symbol Set tool. Use these settings.

OFF
lU
ON icons.hand2
ON symbol when IfDef("%Tag%_Pump_Man ",,0)
na

iv. Open the Silo_Level_4 genie. Copy the objects in the genie
then return to the new genie and paste the objects underneath
r

the pump.
te
In
ct

v. Save the genie as PumpController.


ite

Continued on next page


C

Advanced Configuration Concepts Manual Revision 2-INT 3-27


Smart Genies, Continued

Exercise 3-5 (continued)

Step Action
2 Create a new genie to indicate and control the status of a valve
and a numeric object.
i. Paste a valve to display the status near the Locator point,
using the Symbol Set tool. Use these settings.

Symbols OFF valve_solenoid.down_small_red

LY
ON valve_solenoid.down_small_green
ON symbol when IfDef("%Valve%_Valve_Open",,0)

N
Visibility IfDef("%Valve%_Valve_Open",0,1)
(Hidden when)

O
ii. Add a numeric object to control and indicate the value of
integer tags.

Appearance
(Numeric Expression)
Visibility (Hidden when)
se
IfDef("Past_%Control%",,0)

IfDef("Past_%Control%",0,1)
lU
iii. Add a text object to display the tag name.
na

Appearance (General) Text %Control%


Visibility (Hidden when) IfDef("Past_%Control%",0,1)
r

iv. You may also decide to add a rectangle as a background


te

object. If you do the result will look something like this.


In
ct
ite

v. Save the genie as IndController.


C

3-28 CitectHMI/SCADA Version 6.00 August 2005


Genie Forms

You may have noticed that the genies that come included with
CitectHMI/SCADA often have drop down combo boxes that list your variable
tags whereas the forms on your genies only allow you to enter the name of the
field specified in the genie.

LY
N
You can create your own drop down boxes by using Genie Forms. A genie

O
library is a file with a .ctm extension and each genie library can have an
associated genie form file written for it (for example Training.ctm would have
Training.frm). The form file should reside in the same directory as the library

se
(ctm) file. A form definition for each genie in the associated library can be
provided. If one is not provided then a default form is created as per normal.
A Genie form follows this format
lU
FORM "<genie>"[,"<form title>"];
<field number>:"<field name>",<field size>
[,readonly/readwrite [, "<list form>", "<list
na

field>"[,"<list filter>"]]];
NORMAL
"<prompt> {<field number> }"
r
te

When you see it written for the Genie – Pump shown below it makes a little
more sense.
In

FORM "Pump_East", "Genie - Pump";


1: "Tag",32, readwrite,"Variable Tags",
ct

"NAME","TYPE=DIGITAL";
NORMAL
"Tag {1 }"
ite

Continued on next page


C

Advanced Configuration Concepts Manual Revision 2-INT 3-29


Genie Forms, Continued

Genie Form The Genie Form Format is divided into three distinct sections.
Format
¾ Genie Definition and Title
¾ Record Definition
¾ Form Definition

LY
Genie The first section identifies the genie and sets the text of the Title Bar
Definition

N
Field Definition
Form Keyword Start your genie form definition with the keyword FORM.

O
Name This is followed by the Name of the Genie as it is
specified in the Genie library.

Genie Title Bar


FORM "Pump_East"
se
This is followed by the text that will appear in the Genie
Form Title Bar.
lU
FORM "Pump_East", "Genie - Pump";
na

Record The next section is the Record Definition and defines each of the fields that
Definition will appear on the Genie Form.
r
te

Field Definition
Field Number Firstly each field is numbered.
In

1:
Field Name Next the Field Name is inserted between quote marks “
ct

”. This is the word that appears between the percentage


marks in your genie e.g. %Tag%.
ite

1: “Tag”
Field Size Variable tags may be up to 32 characters in length.
C

However if you are putting a field for privilege on the


form you may wish to use fewer characters.

1: "Tag",32
Write Access The two options for this are readwrite and readonly.

1: "Tag",32, readwrite

If you are not using a dropdown list (e.g. formatting the field for privilege)
this will be enough to define this field. Finish the line with a semicolon.

Continued on next page

3-30 CitectHMI/SCADA Version 6.00 August 2005


Genie Forms, Continued

Record However, if you are defining the field for something which will extract values
Definition from a .dbf file you will need some more definition on the line.
(continued)

Field Description
List Form The next field identifies the List Form which contains the
options to go into the list. The name of the list form
must have quote marks.

LY
1: "Tag",32, readwrite,"Variable Tags"
List Field The List Field comes next. This is the field that contains
the values that will appear in the combo box. It must

N
also appear between quotes.

O
1: "Tag",32, readwrite,"Variable Tags",
"NAME"
List Filter The last field on this line is the List Filter. The filter

se
allows you to only have tags of a certain type or
extension (or both) display in the drop-down list. You
may have created a genie which is an on/off switch and
lU
will therefore only apply to digital tags. If this is the
case then you would filter TYPE=DIGITAL.
na

1: "Tag",32, readwrite,"Variable Tags",


"NAME","TYPE=DIGITAL";
r

If you would like to filter on an extension then you may


te

also do this e.g. if you have named all of your _CMD


tags with the last characters “_CMD” then the line will
In

look like this.

1: "Tag",32, readwrite,"Variable Tags",


ct

"NAME","*_CMD";

When a list is filtered this way the drop down list will
ite

strip the filter characters, i.e. “_CMD”, from the end of


the tag name. This is actually desired when using
C

structured tag names as the genie will probably be


adding the _CMD or other extension itself.

It is even possible to filter for both type and extension.


In this example we would be filtering for an INTEGER
type and a _CMD extension. The line ends with a
semicolon.

1: "Tag",32, readwrite,"Variable Tags",


"NAME", “TYPE=INT",”*_CMD”;

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 3-31


Genie Forms, Continued

Form After the Record Definition comes the Form Definition. This section defines
Definition the look of the genie form that will pop up.

Field Description
Normal Keyword It starts with the keyword NORMAL

Normal
Field Prompt Next comes the String that describes the form. The string

LY
consists firstly of a prompt for the field.

NORMAL

N
"Tag
Field Number Next the field itself is indicated by the field number

O
enclosed in braces. You must leave spaces between the
braces to display the size of the field. This string is
copied directly across to the form and since it is a string

se
it must all be enclosed in quotes.
lU
NORMAL
"Tag {1 }"
na

Continued on next page


r
te
In
ct
ite
C

3-32 CitectHMI/SCADA Version 6.00 August 2005


Genie Forms, Continued

What the Form The result of this genie form with this format…
Looks Like
FORM "Pump_East", "Genie - Pump";
1: "Tag",32, readwrite,"Variable Tags", "NAME",
"TYPE=DIGITAL";

NORMAL
"Tag {1 }"

LY
…is a form that will look like this.

N
O
You may decide to have more fields and descriptive prompts on your form.
This Genie form…
se
lU
FORM "ValveControl", "Genie - Valve";
1: "Name", 32, readwrite, "Variable Tags", "NAME",
"*_Valve";
2: "Privilege", 3, readwrite;
na

NORMAL
"Enter the Name of the Valve here
r

{1 }
te

Privilege {2 }"

…will display a form that looks like this.


In
ct
ite
C

See Also:
For further information about the Genie forms, see CitectSCADA KB Article
Q1764 - Writing Genie Form Files and Q3643 - Creating Custom Dropdown Lists
for Genie Forms.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 3-33


Genie Forms, Continued

Exercise 3-6

Step Action
1 Create a genie form to use with the genies PumpController and
IndController.
i. Use Windows Notepad to create a new file called Training.frm.
Save the file in your project directory.
ii. The first line on your genie form identifies the genie with which

LY
to be associated and assigns a label to the title bar.

FORM "Pumpcontroller", "Genie - Pump Controller";

N
iii. Each genie field in the genie must then be identified. The

O
genie field is surrounded by quotes.

1: "Tag",

iv.
se
Next add the number of characters and the read/write
lU
attribute.
na

1: "Tag", 32, readwrite,

v. Field that are not going to have drop down lists may finish here
r

and the line is ended with a semi colon. However, these three
te

fields are going to be populated by tags from the Variable


Tags database. The next field identifies the database.
In

1: "Tag", 32, readwrite, “Variable Tags”,


ct

vi. The next attribute to be added identifies the database field


from which the information is taken. In this case it will be the
ite

Name field.
C

1: "Tag", 32, readwrite, “Variable Tags”,


“Name”,

vii. Next we will filter the list so that only the most appropriate
tags are displayed.

1: "Tag", 32, readwrite, “Variable Tags”,


“Name”,"*_PUMP_RUN";

Continued on next page

3-34 CitectHMI/SCADA Version 6.00 August 2005


Genie Forms, Continued

Exercise 3-6 (continued)

Step Action
1 viii. Underneath add the code that will draw the form.
(cont.)

NORMAL
"Base Tag {1 }”

LY
ix. Save the form.
2 Associate the form with the genie.

N
i. Return to the PumpController genie and Save.
ii. Test the genie by placing a pump on the page gr_Past next to

O
the Balance Tank. Add the tags to the fields.

se
lU
r na
te
In

iii. Save the page and compile.

Continued on next page


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 3-35


Genie Forms, Continued

Exercise 3-6 (continued)

Step Action
3 Create a genie form for the IndController genie.
i. Add this genie form to the same Notepad file Training.frm.
ii. Associate the form with the genie.
iii. Test the genie by pasting it onto the page gr_Past next to the
Balance Tank.

LY
N
O
se
lU
na

iv. Save the page and compile the project.


r
te
In
ct
ite
C

3-36 CitectHMI/SCADA Version 6.00 August 2005


Chapter 4: Smart Popups and SuperGenies
Overview

Introduction Popup pages and super genies are dynamic pages to that you can use to pass
information when the page displays in the runtime system. You can use them
for pop-up type controllers for a process or a single piece of plant floor
equipment. The same page can then be re-used with different sets of tags.
For example you could configure a graphics page with several pumps, and
use a super genie pop-up controller for each of the pumps on the page.

LY
Simple super genies and popup pages were covered in the Citect
Configuration Course. This chapter will take the concepts several steps

N
further.

O
Contents This chapter contains the following topics:

Topic
¾ Popup Pages and Supergenies
¾
se See Page
4-2
lU
Smart Popup Pages and Supergenies 4-7
r na
te
In
ct
ite
C
Popup Pages and Supergenies

Exercise 4-1 Popup pages and Super Genies are dynamic pages to which you can pass
information when the page displays in the runtime system. You can use them
for pop-up type controllers for a process or a single piece of plant floor
equipment. For example you could configure a graphics page with several
pumps, and use a super genie or a pop-up controller for each of the pumps on
the page.

Step Action

LY
1 Create a popup page as shown that displays and controls both
a digital and a numeric tag.

N
O
se
lU
na

i. Open the Citect Graphics Builder.


r

ii. Create a New page based on the Standard Blank template.


te
In
ct
ite
C

Continued on next page

4-2 CitectHMI/SCADA Version 6.00 August 2005


Popup Pages and Supergenies, Continued

Exercise 4-1 (continued)

Step Action
1 iii. Add five buttons to the page.
(cont.)

Appearance (General) Input (Touch)


Text/Symbol Execute Command
Start ?Digital 1? = 1

LY
Stop ?Digital 1? = 0
Auto ?Digital 2? = 0
Manual ?Digital 2? = 1

N
icons.clos2 WinFree();

O
iv. Draw the four light symbols using the Symbol Set tool .

se
Set the properties as follows:
lU
Object ON symbol when Symbols
Start light ?Digital 1? = 1 ON lights_square_medium.
grey
na

OFF lights_square_medium.
green
Stop light ?Digital 1? = 0 ON lights_square_medium.
r

grey
te

OFF lights_square_medium.
green
In

Auto light ?Digital 2? = 0 ON lights_square_medium.


grey
OFF lights_square_medium.
ct

green
Manual light ?Digital 2? = 1 ON lights_square_medium.
ite

grey
OFF lights_square_medium.
green
C

v. Add a numeric object to the page.

Appearance (Display Value) ?INT 3?


Numeric expression
Input (Keyboard Commands) #### ENTER
Key sequence
‘#### ENTER’ command ?INT 3? = ArgValue1

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 4-3


Popup Pages and Supergenies, Continued

Exercise 4-1 (continued)

Step Action
vi. Place the pointer at the bottom right hand corner of the
objects.

LY
N
O
se
lU
Check the pointer position display on the status bar.
na

vii. Go to File | Properties | Appearance Tab and enter the X and


Y pointer positions into the Width and Height. This will define
r

the size of the popup page. If you wish you may also change
te

the Background colour of the page here.


viii. Save the page as !PopControl.
In

See Also:
ct

For further information Supergenie page sizes, see CitectSCADA KB


Article Q3083 - Minimum size of a SuperGenie page.
ite

Continued on next page


C

4-4 CitectHMI/SCADA Version 6.00 August 2005


Popup Pages and Supergenies, Continued

Exercise 4-1 (continued)

Step Action
2 Assign the popup page to the genie.
i. Open the genie PumpController.
ii. Double click the pump and add this command to the genie.

LY
Input (Touch) AssWin("!PopControl",%X=480%,%Y=120%,
Up Command 1+8+512,"%Tag%_Pump_Run",
"%Tag%_Pump_Man","%Tag%_Pump_Speed");

N
WinTitle(AssInfo(1,0));

O
9 Hints & Tips:
Using the expression X=480 as shown above creates a default value
for the parameter.

iii. se
Add the same command to the touch command of the numeric
object.
lU
iv. Open your Training.frm file and add the fields for the X and Y
co-ordinates of the genie
na

FORM "Pumpcontroller", "SuperGenie - Pump


Controller";
r
te

1: "Tag", 32, readwrite, "Variable Tags",


"NAME", "*_PUMP_RUN";
In

2: "X", 4, readwrite;
3: "Y", 4, readwrite;
ct

NORMAL
ite

"Tag {1 }
X {2 } Y {3 }"
C

v. Save the genie and choose Tools | Update Pages from the
menu.
vi. Open the genie on your gr_Past page and add X and Y co-
ordinates to position your popup page.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 4-5


Popup Pages and Supergenies, Continued

Exercise 4-1 (continued)

Step Action
3 Compile and run the project to test your genie.
4 Shutdown the project
5 Add these genies to the gr_Past page.

LY
Pump Tag Name from List
Homogeniser Feed Pump Past_Homog
Flow Control Pump Past_Flow

N
Hot Water Pump Past_HW

O
Ice Water Pump Past_IW

i. Your page should look something like this:

se
lU
r na
te
In
ct
ite

6 Save the page and compile.


7 Run the project to test your genies and popup pages.
C

4-6 CitectHMI/SCADA Version 6.00 August 2005


Smart Popup Pages and Supergenies

Overview The functionality of these pages may be extended in the same way as genies
by using Smart Pages. A popup page may be used with other objects but
sometimes there may be a tag association that is not used. If this happens you
will see a #ASS (association) error displayed on the page.

LY
N
O
se
By using a few simple lines of code you can allow the popup pages to ignore
lU
assignment errors and increase the usability of your popup pages.

Continued on next page


r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 4-7


Smart Popup Pages and Supergenies, Continued

Exercise 4-2

Step Action
1 Write a function that will check for the existence of three
variable tags using the function TagInfo(). The function will
then open a popup page using the function WinNewAt().
i. Open the Cicode Editor.
ii. Create a new Cicode file called Popup.ci.

LY
iii. Write a new function called IndControl() that will check if the
three tags have been substituted in the genie and then assign
them to the popup page !PopControl.

N
FUNCTION IndControl( STRING sTagName1,STRING

O
sTagName2, STRING sTagname3, INT X, INT Y )
STRING sTag1;
STRING sTag2;
STRING sTag3;
se
sTag1 = sTagname1 + "_Valve_Open"
lU
sTag2 = sTagname2 + "_Valve_Man"
sTag3 = "Past_" + sTagName3
IF TagInfo( sTag1, 0 ) <> "" THEN
na

Ass(-2, 1,sTag1, 0);


END
IF TagInfo( sTag2, 0 ) <> "" THEN
r

Ass(-2, 2,sTag2, 0);


te

END
IF TagInfo( sTag3, 0 ) <> "" THEN
In

Ass(-2, 3,sTag3, 0);


END
ct
ite

Continued on next page


C

4-8 CitectHMI/SCADA Version 6.00 August 2005


Smart Popup Pages and Supergenies, Continued

Exercise 4-2 (continued)

Step Action
1 iv. Use the WinNewAt() function to open the popup page
(cont.) !PopControl.

WinNewAt("!PopControl",X,Y,1+8+512);

LY
v. Check for the existence of the first tag. If it exists write the tag
name into the title bar of the popup page.

N
IF TagInfo( sTag1, 0 ) <> "" THEN

O
WinTitle(sTag1);
END

vi. End the function.


se
lU
END
2 Save your file and compile.
na

 Continued on next page


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 4-9


Smart Popup Pages and Supergenies, Continued

Exercise 4-3

Step Action
1 Hide the objects in the popup page if tags are not assigned to
the objects.
i. Return to the Citect Graphics Builder and open the popup page
!PopControl.
ii. Use the function AssInfo() in the buttons and symbol sets to

LY
hide the objects if the tags do not exist.

Object Appearance (Visibility)

N
Hidden when
Start Button AssInfo(1,0)=""

O
Start Light
Stop Button
Stop Light
Auto Button se
AssInfo(2,0)=""
lU
Auto Light
Manual Button
Manual Light
na

Numeric Object AssInfo(3,0)=""


Numeric Object AssInfo(3,0)=""
Rectangle
r
te

iii. Add a text object above the numeric object to identify the tag
that will be displayed.
In

Appearance (Display Value) AssInfo(3,0)


String expression
ct

iv. Save the page.


ite

Continued on next page


C

4-10 CitectHMI/SCADA Version 6.00 August 2005


Smart Popup Pages and Supergenies, Continued

Exercise 4-3
(continued)

Step Action
2 Add the new function to the IndController genie.
i. Open the genie IndController.
ii. Add this function to the numeric object and the symbol set.

LY
Input (Touch) IndControl("%Valve%","%Valve%",
Up command "%Control%",%X%,%Y%)

N
3 i. Open the genie form Training.frm.

O
ii. Add the syntax for the X and Y coordinates to the form. Your
form should look like this:

se
FORM "IndController", "SuperGenie - Valve
Indicator/Controller";
lU
1: "Valve", 32, readwrite, "Variable Tags",
"NAME","*_Valve_Open";
2: "Control", 32, readwrite, "Variable
na

Tags","NAME","Past_*";
3: "X", 4, readwrite;
4: "Y", 4, readwrite;
r

NORMAL
te

"Base Valve {1 }
Control {2 }
X {3 } Y {4 }"
In

Note: The number of spaces after the numbers 1 and 2 for the
Base Valve and Control is 31 because the number of
ct

characters in that field is 32.


ite

iii. Save the genie and update the pages.


C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 4-11


Smart Popup Pages and Supergenies, Continued

Exercise 4-3 (continued)

Step Action
4 Add these genies to the gr_Past page.

Valve/Indicator Field Variable Tag/Coordinate


Balance Valve / Valve Past_Balance
Balance Tank Control Balance_LIC

LY
Level X
Y
Homogeniser Valve Past_Homog

N
Valve Control
X

O
Y
Homogeniser Valve
Pressure Control Homog_PIC
X
Y se
lU
Product Flow Valve
Control Product_FIC
X
Y
na

Hot Water Valve / Valve Past_HW


Hot Water Temp Control HW_TIC
r

X
te

Y
Ice Water Valve / Valve Past_IW
In

Ice Water Temp Control IW_TIC


X
Y
ct

Vat Valve Valve Past_Vat


Control
ite

X
Y
C

Continued on next page

4-12 CitectHMI/SCADA Version 6.00 August 2005


Smart Popup Pages and Supergenies, Continued

Exercise 4-3
(continued)

Step Action
4 iv. Your page should look like this.
(cont.)

LY
N
O
se
lU
na

v. Save the page and compile.


r

5 Run your project to test your genies and popup pages.


te


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 4-13


LY
N
O
se
lU
nar
te
In
ct
ite
C

4-14 CitectHMI/SCADA Version 6.00 August 2005


Chapter 5: Forms
Overview

Introduction Forms may be used to read and write values into variable tags, send and
receive information from databases and pass data into functions. Standard
forms are provided with CitectSCADA to enter information into the
CitectSCADA databases but you also have the facility to create your own
custom forms.

LY
Contents This chapter contains the following topics:

N
Topic See Page
¾ Cicode Forms 5-2

O
¾ Adding Information to Your Form 5-5
¾ Input Values Using Forms 5-7

se
lU
r na
te
In
ct
ite
C
Cicode Forms

Overview Cicode forms may be used to read and write values into variable tags, send
and receive information from databases, and pass data into functions. A form
is defined by the FormNew() function and then displayed with the
FormRead() function.

FUNCTION
FormExample()
FormNew("My Form",20,1,1);

LY
FormRead(0);
END

The rest of the form definition is placed between those two functions. After

N
the form has been defined using the different form functions the FormRead()
function will then display the form.

O
See Also:
For further information about Form functions, see Citect Help Topics - Form
Functions.
se
lU
Continued on next page
r na
te
In
ct
ite
C

5-2 CitectHMI/SCADA Version 6.00 August 2005


Cicode Forms, Continued

Exercise 5-1

Step Action
1 Create a simple form that is called from a button.
i. Open the Cicode Editor and create a new Cicode file.
ii. Save the file as Forms.
iii. Create a new function called MyForm1().

LY
FUNCTION
MyForm1()

N
iv. Create the form by using the function FormNew().

O
FormNew("My Form",20,1,1);

v. se
Add two buttons to the form for OK and Cancel. To do this
use the function FormButton().
lU
FormButton(0,0 ," OK ", 0, 1);
na

FormButton(10 ,0 ," Cancel ", 0, 2);

9 Hints & Tips:


r
te

Check the functions FormNew(), FormButton() and FormRead() in


the Citect Help to find information on the parameters.
In
ct
ite

Continued on next page


C

Advanced Configuration Concepts Manual Revision 2-INT 5-3


Cicode Forms, Continued

Exercise 5-1 (continued)

Step Action
1 vi. Now the form is complete. Use the function FormRead() to
(cont.) display the form.

FUNCTION
MyForm1()

LY
FormNew("My Form",20,1,1);
FormButton(0,0 ," OK ", 0, 1);
FormButton(10 ,0 ," Cancel ", 0, 2);

N
FormRead(0);
END

O
9 Hints & Tips:
Hotkeys may be used in Forms. Add the ampersand (&) character

se
before the character that you would like to use as the hotkey e.g. &OK.
This will place an underline underneath the character when it is
displayed on the form. You may then execute the button command or
lU
jump to the field by using Alt + the character.

vii. Save the Cicode file Forms.ci.


na

2 Test the new function.


i. Open the Citect Graphics Builder and open the page called
r

gr_Forms.
te

ii. Add a button called My Form 1 to the page.


iii. Add the function MyForm1() to the Input (Touch) command.
In

iv. Save the page and compile your project.


v. Run your project and test that the new function works
correctly.
ct
ite
C

3 Shutdown your project.

5-4 CitectHMI/SCADA Version 6.00 August 2005


Adding Information to Your Form

Overview Custom forms may be used to display information from your runtime system
or external databases. This information may be taken from external sources
such as dBase files, Access databases or SQL databases. Connecting external
sources of information to your forms will be covered in later chapters.

Information may be displayed on your form by using the FormPrompt()


function. The information displayed by this function must be a STRING type
variable. The function may therefore be used for text labels and other

LY
prompts. However, if you need to display information of other types on the
form then this may be done by converting the type to a string first.

N
See Also:
For further information about String Conversion functions, see Citect Help Topics -
String Functions.

O
se Continued on next page
lU
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 5-5


Adding Information to Your Form, Continued

Exercise 5-2

Step Action
1 Add some information to your form using the function
FormPrompt().
i. Copy and paste your MyForm1() function underneath the
original function. Rename the function MyForm2().
ii. Display the value of the tag AlfastRecPLC on your form. Add

LY
a text label in front of the value. You will also need to change
the position of the OK and Cancel buttons. Note that the
parameters of the FormNew() function have changed in this
example.

N
FUNCTION

O
MyForm2()
FormNew("My Form Read",20,2,1);

FormButton(0,1 ," se
FormPrompt(0,0,"Alfast");
FormPrompt(10,0,AlfastRecPLC);
OK ", 0, 1);
lU
FormButton(10 ,1 ," Cancel ", 0, 2);
FormRead(0);
END
na

iii. Save the page and compile.


2 Test your new function.
r

i. Add a new button to the gr_Forms page to call your function.


te

ii. Save the page and compile


iii. Run the project.
In

iv. Open the gr_Forms page and call your form. You may use the
recipe table to change the value of the tag.
ct
ite
C

3 Shutdown your project.

5-6 CitectHMI/SCADA Version 6.00 August 2005


Input Values Using Forms

Exercise 5-3 A form may be used to send values to variable tags and databases. The
function FormInput() adds a prompt and edit field to the current form. When
FormRead() is called, the form will display with the prompt and edit box. The
operator's input is passed back as a string. This means that if you are going to
read and write to information types other than strings you will need to convert
your information into string types and then convert back after the input from
the user has been entered. The following exercise will demonstrate how this
may be done using a recipe.

LY
Step Action
1 Add input fields to your form to display current data and send
values into your tags.

N
i. Copy the function MyForm2() below the original function.
Rename the function MyForm3().

O
ii. You will need to create module string variables for all of the
recipe ingredients that are going to be used in the next set of
exercises. Create the variables at the top of the page.

STRING sAlfastRecipe;
se
lU
STRING sMilkFat;
STRING sProtein;
STRING sSNF;
na

iii. Add the FormInput() function to your form. You may need to
adjust the size of your form and reposition the buttons.
r
te

FUNCTION
MyForm3()
In

FormNew("My Form Input",30,5,1);


FormPrompt(0,0,"Alfast");
FormPrompt(10,0,AlfastRecPLC);
ct

FormInput(0, 1, "Enter Value",


sAlfastRecipe, 16);
ite

FormButton(5, 3 ," OK ", 0, 1);


FormButton(15 , 3 ," Cancel ", 0, 2);
FormRead(0);
C

END

iv. Add error checking to your function to check whether the form
has been Cancelled or OKed by the operator before writing
the value to the variable tag. Replace the line FormRead(0)
with this code:
IF FormRead(0) = 0 THEN
AlfastRecPLC = sAlfastRecipe;
END

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 5-7


Input Values Using Forms, Continued

Exercise 5-3 (continued)

Step Action
2 Test your function.
i. Add a new button to your gr_Forms page.
ii. Run the project to test your form. Check that the values are
not set to zero if the form is cancelled.

LY
N
O
3 Shutdown the project.
4
se
Create a function to populate the memory variables with the
values in the variable tags as the Forms page is opened.
lU
i. Name the function OpenRecipe().

FUNCTION
na

OpenRecipe()
sAlfastRecipe = AlfastRecPLC;
sMilkFat = IntToStr(MilkFatPLC);
r

sProtein = IntToStr(ProtPLC);
te

sSNF = IntToStr(SNF_PLC);
END
In

Continued on next page


ct
ite
C

5-8 CitectHMI/SCADA Version 6.00 August 2005


Input Values Using Forms, Continued

Exercise 5-3 (continued)

Step Action
4 ii. Add the function to the OnPageEntry command of your
(cont.) gr_Forms page.

LY
N
O
se
lU
r na
te

Continued on next page


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 5-9


Input Values Using Forms, Continued

Exercise 5-3 (continued)

Step Action
5 Add the rest of the recipe ingredients to the form.
i. Add input lines for the ingredients Milk Fat, Protein and Solids
Non Fat. You may prefer to create a new function.

FUNCTION

LY
MyForm4()
FormNew("My Recipe Input",31,6,1);
FormInput(0, 0, "Alfast ",

N
sAlfastRecipe, 16);
FormInput(0, 1, "Milk Fat ",

O
sMilkFat, 5);
FormInput(0, 2, "Protein ",
sProtein, 5);

FormButton(5,5 ," se
FormInput(0, 3, "Solids Non Fat",
sSNF, 5);
OK ", 0, 1);
lU
FormButton(15 ,5 ," Cancel ", 0, 2);
IF FormRead(0) = 0 THEN
AlfastRecPLC = sAlfastRecipe;
MilkFatPLC = StrToInt(sMilkFat);
na

ProtPLC = StrToInt(sProtein);
SNF_PLC = StrToInt(sSNF);
END
r

END
te

ii. Save the page and add another button to the Forms page.
In

iii. Compile your project.


ct

Continued on next page


ite
C

5-10 CitectHMI/SCADA Version 6.00 August 2005


Input Values Using Forms, Continued

Exercise 5-3 (continued)

Step Action
6 Test your new functions.
i. Run your project and open the gr_Forms page. The
OnPageEntry command should populate the memory variables
with the existing values in the variable tags.

LY
N
O
se
lU
ii. Change the values to test your function.
iii. Shutdown your project.
7 Add a combo box to your form.
na

i. Copy your existing function and rename this one MyForm5().


ii. Create a combo box and a list of values to select for the Alfast
recipe using the functions FormComboBox() and
r

FormAddList(). The function FormComboBox() will be used to


te

replace the command FormInput(). Since the


FormComboBox() function has no prompt field you will need to
add a FormPrompt() line to label the combo box.
In

FormPrompt(0,0,"Alfast");
ct

FormComboBox(16, 0, 16, 5, sAlfastRecipe, 0);


FormAddList("Full Cream");
FormAddList("Skim");
ite

FormAddList("Light");
FormAddList("High Protein");
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 5-11


Input Values Using Forms, Continued

Exercise 5-3 (continued)

Step Action
7
(cont.)
9 Hints & Tips:
The current value of the buffer variable (sAlfastRecipe) will be added
to the combo box list if it is different from what you add with

LY
FormAddList().
The current value of the buffer variable is also selected by default
when the form displays.

N
You should always set the buffer variable before executing
FormComboBox() or a blank record will be added to the list.

O
iii. Save the page.
iv.

se
Add another button to the gr_Forms page then save the page
and compile.
lU
8 Test your combo box.
r na
te
In
ct

9 Shutdown your project.


ite

 Continued on next page


C

5-12 CitectHMI/SCADA Version 6.00 August 2005


Input Values Using Forms, Continued

Exercise 5-4

Step Action
1 Create a login form for your project that will display a combo
box containing the most commonly used Users in the User
database.
i. Create a new Cicode file called OpLogin.ci.
ii. Create a new function called OpLogin() that will display a form

LY
using a combo box. The form will list the users who will be
using the system. The users are listed in the System | Users
menu in the Citect Project Editor.
iii. Add a password field using the function FormPassword().

N
2 Add a button to the page gr_Forms to test your new function.

O
3 Use error checking to verify that the password has been
entered correctly and log out if it is incorrect.
4 If the login fails send an error message to the SYSLOG.DAT file.

9 Hints & Tips:


se
lU
Check the CitectSCADA Help for information regarding the ErrLog()
function.
na


r
te

Continued on next page


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 5-13


Input Values Using Forms, Continued

Exercise 5-5

Step Action
1 Create a drop down menu to display common User functions.
i. Open the Cicode Editor and create a new Cicode file called
Menu.ci.
ii. Create a new function called UserMenu(). Add a local variable
for the menu item selection number that the DspPopupMenu()

LY
function will return.

FUNCTION

N
UserMenu()
INT nSelection;

O
iii. Add an IF THEN ELSE statement to display a context sensitive

se
menu that will disable items depending upon whether a User is
logged in to the system.
IF UserInfo(0)<>"1" THEN
lU
DspPopupMenu(0,"Login,!Logout,
!Change Password,,
!Edit User, !Create User");
nSelection = DspPopupMenu(-1, "",888,38);
na

ELSE
DspPopupMenu(0,"!Login,Logout,,
Change Password,, Edit User,
r

Create User");
te

nSelection = DspPopupMenu(-1,"",888,38);
END
In

iv. Add a SELECT CASE statement that will call the appropriate
functions depending upon which menu item was selected.
ct

SELECT CASE nSelection


CASE 001
ite

OpLogin();
CASE 002
Logout();
C

CASE 003
UserPasswordForm();
CASE 004
UserEditForm();
CASE 005
UserCreateForm();
END SELECT
END

Continued on next page

5-14 CitectHMI/SCADA Version 6.00 August 2005


Input Values Using Forms, Continued

Exercise 5-5 (continued)

Step Action
2 Add a button to the Normal template to call the new function.
i. Return to your Normal template and add three buttons next to
the UserInfo(1) string object. The third button (Logout) is
hidden behind the Login button.

LY
N
ii. Add these settings to your buttons.

O
Button Appearance (General) Input (Touch) Access
Symbol Up Command (Disable)

Login
Logout csv_icons.
se
csv_icons.couple_01_xp OpLogin()
Logout()
Tool Tip
Login
Logout
lU
couple_02_grey_xp
User icons.dnar UserMenu() User Menu
Menu
na

iii. Add these disable parameters to the Login and Logout buttons.
r
te

Button Access (Disable) Disable Style


Disable when
Login UserInfo(0) = "1" Hidden
In

Logout UserInfo(0) <> "1" Hidden


ct

iv. Save and update the template.


ite


C

Advanced Configuration Concepts Manual Revision 2-INT 5-15


LY
N
O
se
lU
nar
te
In
ct
ite
C

5-16 CitectHMI/SCADA Version 6.00 August 2005


Chapter 6: True Color
Overview

Introduction True Color support allows CitectSCADA users to create graphically rich
display pages more easily by supporting a far greater number of colours than
the 256-colours available in previous releases.

True Color is supported for all animation objects and static objects, including
page backgrounds, imported images, symbols, metafiles, and bitmaps (with

LY
the exception of colour floods).

N
Contents This chapter contains the following topics:

O
Topic See Page
¾ Choosing Standard Colours 6-2
¾ Choosing Custom Colours 6-6
¾
¾
Creating Custom Colours
Choosing Colour Values
se 6-8
6-14
lU
¾ Custom Fonts and Colour Labels 6-19
¾ Adjust Colours 6-22
na

¾ Flashing Colours 6-27


¾ Flashing Images 6-31
r
te
In
ct
ite
C
Choosing Standard Colours

The Color The first 11 rows of the Color Picker show a set of standard colours, including
Picker transparent (marked with a black cross). The remaining rows display any user
defined colours, referred to as Color Favorites. This includes flashing colours,
represented by a two colour block, divided diagonally.

Standard Colours

LY
N
Custom Colours

O
(Color Favorites)

Flashing Colours

se
lU
How to ¾ To select one of the colours:
na

Open the Color Picker and click on the colour.


r
te

If the required colour does not appear, you have the option to create a custom
colour, or match an existing colour from one of your graphics pages.
In

Continued on next page


ct
ite
C

6-2 CitectHMI/SCADA Version 6.00 August 2005


Choosing Standard Colours, Continued

Exercise 6-1 Choose standard colours for text objects.

Step Action
1 Go to the Citect Graphics Builder and open the page gr_Past.
2 Change the colours in the animated text objects.
i. Double click the text object Silo Agitator OFF.
ii. Open the Fill tab and change the ON color: to Flash Green.
Click OK to close the text properties dialog.

LY
N
O
se
lU
r na
te
In
ct
ite

 Continued on next page


C

Advanced Configuration Concepts Manual Revision 2-INT 6-3


Choosing Standard Colours, Continued

Exercise 6-2 Choose standard colours to use with the Swap Color tool.

Step Action
1 Create a new symbol.

i. Click the New button.


ii. Choose Symbol.
iii. Paste the symbol tanks_conical.tank and place it near the

LY
locator point. Make sure you untick the Linked box

N
O
iv.
se
Create a new library called Tanks and save the symbol in the
tanks library of your project (not the Include project) as
fill_template.
lU
2 Use the Swap Color tool to change the colour of the tank.
i. Select the tank and choose Tools | Swap Colors… from the
menu.
r na
te
In
ct
ite
C

ii. Untick the From any color box.


iii. Tick the Swap range box.

Continued on next page

6-4 CitectHMI/SCADA Version 6.00 August 2005


Choosing Standard Colours, Continued

Exercise 6-2 (continued)

Step Action
2 iv. Choose a colour from the grey range for the From colour and a
(cont.) colour from the brown range for the To colour.

LY
N
O
se
lU
na

Click OK.
r

v. Choose File | Save As… from the menu and save the symbol
te

as fill_malt.
In


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 6-5


Choosing Custom Colours

The Color If you cannot find the colour you need in the standard colours you can match
Selector an existing colour from an existing graphics page.

The Color Selector tool allows you to select a colour from an existing
graphic.

How to ¾ To select a colour from a graphic:

LY
In the Citect Graphics Builder click on the Color Selector tool. This tool
allows you to select a colour from an existing graphic.

N
Exercise 6-3 Use the Color Selector tool to choose a colour from an imported graphic.

O
Step Action
1 Import a picture into a page in the Citect Graphics Builder.
i.
ii.
se
Return to the page gr_Past.
Choose File | Import… from the menu.
lU
iii. Import the graphic Strawberry.jpg provided by your instructor.
2 Use colours from the imported graphic in a text object.
i. Open the properties of the text object Silo Agitator OFF.
na

ii. Go to the OFF Color: and open the Color Chooser. Click the
Color Selector tool.
r
te
In
ct
ite
C

Continued on next page

6-6 CitectHMI/SCADA Version 6.00 August 2005


Choosing Custom Colours, Continued

Exercise 6-3 (continued)

Step Action
iii. Position the Color Selector over the strawberry graphic and
click on the colour you would like to use.

LY
N
O
iv. The OFF color: indicator will change to the colour you have
selected from the graphic. Click OK to close the dialog.

se
lU

r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 6-7


Creating Custom Colours

Color Favorites Version 6 has replaced the Colour Palette with Color Favorites. This offers
greater flexibility in the management and implementation of colours. During
upgrade, the CITECT.PAL file defined for a project is used to calculate the
initial colour entries for the Color Favorites. If no palette file has been
defined, the Include Project palette is used.

Edit Favorite If you cannot find the colour you need in the standard colours the Edit

LY
Colors Favorite Colors tool allows you to create the colours you need.

N
O
se
lU
r na
te

With the Edit Favorite Colors tool, you can:


In

¾ Make a visual selection of a colour you would like to use by clicking on


the colour wheel.
ct

¾ Decide the brightness level for a colour by clicking on the brightness bar.
¾ Create a colour by entering hue, saturation and luminance values.
ite

¾ Create a colour by entering red, green and blue colour values.


Modify the colours available on the Color Picker by adding, replacing and
C

removing colours on the colour grid.

Continued on next page

6-8 CitectHMI/SCADA Version 6.00 August 2005


Creating Custom Colours, Continued

Add The Add button allows you to add the currently defined colour to the Color
Favorites panel.

Replace The Replace button will replace a colour in the colour grid with the currently
defined colour.

LY
Clear Removes the selected colour, leaving an "unused" position on the colour grid.

Name Allows you to associate a name with a predefined colour. The name can be

N
viewed as a tool tip in the Color Picker, making it easy to distinguish a

O
specific colour among similar shades.

You can associate a name with a newly created colour by typing in a name

se
before clicking the Add button. You can also apply a name to an existing
colour by selecting the colour, keying in a name and clicking the Replace
button.
lU
Note: The pre-defined colour labels are already defined as colour names.
na

Continued on next page


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 6-9


Creating Custom Colours, Continued

Exercise 6-4 Add a custom colour to the Color Favorites panel.

Step Action
1 Add the strawberry colour taken from the graphic to the Color
Favorites.
v. Return to the Citect Graphics Builder. Click the current colour
on the toolbar then click the Edit… button.

LY
N
O
se
lU
na

vi. Edit Favorite Colors will open and the currently selected colour
will be displayed in the Color: panel.
r
te

Continued on next page


In
ct
ite
C

6-10 CitectHMI/SCADA Version 6.00 August 2005


Creating Custom Colours, Continued

Exercise 6-4 (continued)

Step Action
vii. Type Strawberry in the Name: field then click the Add button.

LY
N
O
se
lU
na

viii. The new colour will be added to the Color Favorites panel in
the next available space. When you hover the pointer over the
r

new colour the name will be displayed as a tool tip.


te
In
ct

Continued on next page


ite
C

Advanced Configuration Concepts Manual Revision 2-INT 6-11


Creating Custom Colours, Continued

Exercise 6-4 (continued)

Step Action
2 Use the new colour to change a symbol.
i. Open the symbol fill_template.
ii. Select the grey tank.
iii. Choose Tools | Swap Colors… from the menu.

LY
iv. Select a colour in the grey range for the From colour.

N
O
se
lU
r na
te
In

Continued on next page


ct
ite
C

6-12 CitectHMI/SCADA Version 6.00 August 2005


Creating Custom Colours, Continued

Exercise 6-4 (continued)

Step Action
v. Select your new colour Strawberry for the To colour. Make
sure the Swap range box is ticked.

LY
N
O
vi. se
Click OK to implement the colour change
lU
vii. Choose File | Save As… from the menu and save the symbol
as fill_str.
na


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 6-13


Choosing Colour Values

HLS Model The Edit Favorite Colors tool offers you several ways to choose colours. One
of these is the HLS model. The HLS model describes colours in the
following terms:

Hue Hue describes the colour as a


point in the colour spectrum.
These colours vary from red -

LY
yellow - green - cyan - blue -
magenta - red and may be
described as an angle around a

N
circle with values from 0 - 359
degrees.

O
Luminance Luminance describes
lightness, which varies from 0
the

and 255 and ranges from black at se


lU
0, through the standard colour
itself at 128 to white at 1.0.
r na
te

Saturation Saturation describes the depth of


the colour or how “grey” it is.
In

The values range from 0 to 255


with 0 being completely
unsaturated (grey, white or black)
ct

and 255 being completely


saturated.
ite
C

Continued on next page

6-14 CitectHMI/SCADA Version 6.00 August 2005


Choosing Colour Values, Continued

RGB Model RGB stands for Red Green and Blue. This model represents how your
computer sees colours. Each pixel in your screen can be 'switched on' like a
little 'light-bulb' by means of a 'light-ray' produced by an electronic gun inside
your monitor. This ray can be a shade of Red, a shade of Green or a shade of
Blue. For this reason the pixel shot by the ray can assume a shade of red, a
shade of green or a shade of blue.

LY
Colour Values According to the RGB model, each
shade of each of the 3 colours
(Red, Green and Blue) is

N
represented by a number ranging
from 0 to 255. For example, the red

O
colour is represented by the value:

255 0 0

Combining When the numbers are used in se


lU
Colour Values combination the RGB model can
represent more than 16 millions of
colours. RGB is an additive model,
because Red Green and Blue are
na

additive colours. In other words


when red green and blue are
combined,
r
te

255 255 255


In

they create white. Red + Green +


Blue = White.
ct
ite

Note: When you create a colour by using HLS values, you may find that
the HLS values you specified for a colour have changed when you
reopen the dialog box. This happens because RGB values are less
C

precise than HLS values, sometimes resulting in several HLS


values being assigned the same RGB value. As a result, when the
HLS values are generated from the RGB values, some values may
change.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 6-15


Choosing Colour Values, Continued

Visual Colour The Edit Favorite Colors tool has two features that allow colour selection in a
Selection visual manner.

Color Wheel The Color Wheel allows you to


visually select a colour. It
represents two components in the
HLS model.

LY
¾ Hue is represented by the
circumference of the circle.

N
The full spectrum of colours is
represented starting with red

O
on the right. The values
increase in the anticlockwise
direction.
¾ Saturation is represented by
the radius of the circle. The
centre of the circle is
se
lU
saturation value 0. Colour
saturation increases from the
centre towards the outside
na

edge.
Simply click on the wheel to
select a colour. The panel labelled
r

Color: will display your current


te

selection.
In

Brightness Bar The Brightness Bar allows you to


visually select the brightness you
would like applied to a colour.
ct

¾ Luminance is represented by
ite

the Brightness Bar. As the


pointer moves up the bar
colours move away from pure
C

black towards pure white.

Click on the bar in the appropriate


location or drag the arrow
indicator to apply a brightness
level.

Continued on next page

6-16 CitectHMI/SCADA Version 6.00 August 2005


Choosing Colour Values, Continued

Exercise 6-5 Create new colours using HLS values, RGB values and the Color Wheel.

Step Action
1 Create a new colour using HLS values.
i. Return to the Citect Graphics Builder and open Edit Favorite
Colors.
ii. Create a new colour using these values.

LY
Hue: 35
Lum: 47

N
Sat: 255

O
iii. Name the new colour Chocolate.

se
lU
r na
te
In
ct
ite

iv. Click Add to create the new colour.


C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 6-17


Choosing Colour Values, Continued

Exercise 6-5 (continued)

Step Action
2 Create a Chocolate tank.
i. Open the fill_template tank.
ii. Open Swap Colors.
iii. Select Chocolate for your To colour.

LY
iv. Click OK to implement the colour change.
v. Save this tank three times using the names fill_choc, fill_car
and fill_coff.

N
3 Create a new colour using RGB values.
i. Return to the Citect Graphics Builder and open Edit Favorite

O
Colors.
ii. Create a new colour using these values.

Red:
Green:
se
243
218
lU
Blue: 11
na

iii. Name the new colour Banana.


iv. Click Add to create the new colour.
2 Change one of the tanks to Banana.
r

i. Open the symbol fill_template.


te

ii. Open Swap Colors.


In

iii. Select Banana for your To colour.


iv. Click OK to implement the colour change.
v. Save the symbol twice using the names fill_ban and fill_malt.
ct

4 Create a new colour using the Color Wheel and the Brightness
Bar.
ite

i. Return to the Citect Graphics Builder and open Edit Favorite


Colors.
C

ii. Use the Color Wheel and Brightness Bar to create a colour for
Vanilla.

9 Hints and Tips


Vanilla essence is a deep brown colour.

iii. Use Swap Colors to create a new tank called fill_van.


6-18 CitectHMI/SCADA Version 6.00 August 2005
Custom Fonts and Colour Labels

Overview It has always been possible to define your own custom fonts for use in
buttons, Cicode functions and alarm categories. However, Version 6.00 now
requires a change in the way colours are defined due to the change from the
Citect Palette to True Color. The colour labels now use HEX or DECIMAL
values to define the colour where palette references were used in previous
versions. This is the reason why the alarm colours change when the projects
are upgraded from previous versions. If the colour palette reference was used
then the number could only have been one number from 0 to 255.

LY
N
O
se
CitectSCADA will interpret this as the last three digits in a DECIMAL value.
Since the last three digits define the Blue value that is why the alarms
lU
appeared blue when the project was upgraded.

Note: You cannot use the colour names defined in your Color Favorites to
na

define Font colours. Fonts use Colour Labels and the Expression in
the Label definition will not be able to interpret a Color Favorite.
r
te

How to ¾ To create a colour label for use in custom fonts:


In

In the Citect Explorer, select a project and open the System


folder, then double click on the Labels icon:
ct

or
ite

in Project Editor, select System | Labels from the main menu.


C

¾ To create a custom font:


In the Citect Explorer, select a project and open the System
folder, then double click on the Fonts icon:

or

in Project Editor, select System | Fonts from the main menu.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 6-19


Custom Fonts and Colour Labels, Continued

Exercise 6-6 Create colours and custom fonts for the Alarm Categories.

Step Action
1 Choose a colour.
i. Open Edit Favorite Colors.
ii. Create a colour to use for Unacknowledged Alarms, for
example, a bright orange colour. Note that the RGB colours in
this example are 240, 133 and 12.

LY
N
O
se
lU
r na
te

iii. Choose a Dim Orange colour for the Acknowledged Alarms.


In

iv. The colour values must then be converted to HEX values.


There are many freeware utilities that will convert RGB to HEX
values such as this one. Your Instructor will provide you with
ct

the utility that they want you to use.


ite
C

Continued on next page

6-20 CitectHMI/SCADA Version 6.00 August 2005


Custom Fonts and Colour Labels, Continued

Exercise 6-6 (continued)

Step Action
2 Create Colour Labels.
i. In the Citect Project Editor select System | Labels from the
main menu.
ii. Create two new labels for the colours Bright Orange and Dim
orange. The characters 0x must be placed in front of the HEX

LY
value so that the compiler will interpret the value as
DECIMAL.

N
Label Name Expression Comment
Bright_Orange 0xF0850C Bright Orange colour

O
number
Dim_Orange 0x824806 Dim Orange colour number

3 Create custom fonts.


i.
se
In the Citect Project Editor select System | Fonts from the
lU
main menu.
ii. Create two new fonts
na

Font Name Font Type Pixel Size Foreground Colour


UnAckAlm Tahoma,B -11 Bright_Orange
r

AckAlm Tahoma,B -11 Dim_Orange


te

4 Change the fonts in the Alarm Categories.


In

i. In the Citect Project Editor select Alarms | Alarm Categories


from the main menu.
ct

ii. Change these fonts in all three categories.


ite

Alarm On Font
UnAcknowledged Acknowledged
C

UnAckAlm AckAlm

5 Compile and Run your project.


6 Trigger some alarms and check that your new fonts are being
displayed.

Advanced Configuration Concepts Manual Revision 2-INT 6-21


Adjust Colours

Overview The Adjust Colors tool allows more refined colour adjustment than is
available in Swap Colors.

Hue (degrees) The Hue area allows the user to set the colour hue range to be mapped. The
bars displayed span values of 0 (zero) to 359 degrees, representing the cyclic
nature of hue colour values. A numeric value for each slider can be keyed in

LY
to the field to the right.

N
O
se
lU
na

¾ The slider above the From Hue Range: bar selects the start of the colour
range that will be mapped.
¾
r

The slider below the From Hue Range: bar selects the end of the colour
te

range to be mapped.
¾ The slider above the To Hue Range: bar selects the start point for the
In

colour range that you will be mapping to. Because the value range is
cyclic, the selected area can span across to the left side of the bar.
ct

Note: The range of colours that is excluded by your selection is greyed


out, allowing for a visual assessment of the selected range.
ite
C

Continued on next page

6-22 CitectHMI/SCADA Version 6.00 August 2005


Adjust Colours, Continued

Lightness (%) The Lightness slider allows you to boost the lightness of colours across a
range of (negative) - 100% to 100%. If the slider is increased above zero,
colours will become lighter. If the slider is set below zero, colours will
become darker. A numeric value for the slider can be entered into the field to
the right.

LY
The Selected Hues Only check box applies the lightness setting to only those
colours that will be remapped. Leaving the box unchecked allows the

N
lightness to be adjusted for all colours.

O
Saturation (%)

se
The Saturation slider allows you to boost the saturation of colour across a
range of (negative) -100% to 100%. If the slider is increased above 0, colours
will tend towards primary colours. If the slider is set below zero, colours will
lU
move towards greyscale. A numeric value for the slider can be entered into
the field to the right.
r na

The Selected Hues Only check box applies the saturation setting to only those
te

colours that will be remapped. Leaving the box unchecked allows saturation
to be adjusted for all colours.
In

Continued on next page


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 6-23


Adjust Colours, Continued

Exercise 6-7 Use the Adjust Colors tool to further refine the colours of your graphics.

Step Action
1 Adjust the colours of an object in a photograph.
i. Return to the Citect Graphics Builder and open the Truecolor
page.
ii. Select the photograph with the red tank.
iii. Choose Tools | Adjust Colors… from the menu.

LY
iv. Select the colours in the red spectrum for the From Hue
Range: panel. The sliders will wrap around to select the red
ranges at each end.

N
O
se
lU
r na
te
In
ct
ite

v. Select values in the blue spectrum for the To Hue Range:


panel. Click OK to implement the change.
vi. Repeat these steps to change the colours of individual objects
C

in the other two photographs.

Continued on next page

6-24 CitectHMI/SCADA Version 6.00 August 2005


Adjust Colours, Continued

Exercise 6-7 (continued)

Step Action
2 Adjust the colours of the tanks using the Lightness control in
Adjust Colors.
i. Open the tank fill_choc.
ii. Open Adjust Colors.
iii. Change the Lightness (%) setting to darken the image.

LY
N
O
se
lU
r na
te
In

iv. Click OK to continue.


ct

v. Repeat these steps to adjust the colour of the fill_coff and


fill_van tanks.
ite

Continued on next page


C

Advanced Configuration Concepts Manual Revision 2-INT 6-25


Adjust Colours, Continued

Exercise 6-7 (continued)

Step Action
3 Adjust the colour of a tank using the Saturation control in
Adjust Colors.
i. Select the tank fill_malt.
ii. Open Adjust Colors.
iii. Lower the Saturation (%) level to create a creamier colour.

LY
You may also need to lift the Lightness level.

N
O
se
lU
r na
te
In
ct

iv. Click OK to continue.


v. Open the fill_template tank and use the Lightness setting to
ite

change it to white.
vi. Save the tank as fill_sug.
C

4 Create a new symbol.


i. Paste the symbol tanks_conical.tank_large next to the locator
point.
ii. Use Adjust Colors to change the tank to white.
iii. Save the tank as fill_milk.

6-26 CitectHMI/SCADA Version 6.00 August 2005


Flashing Colours

Overview Flashing colour is now implemented as two linked colours to provide an ON


and OFF state.

The Citect Graphics Builder will no longer display animated flashing colours,
they will appear as a diagonally divided cell with the two colour states
represented.

LY
How to ¾ To Create a new Flashing Colour:

N
In the Citect Graphics Builder choose Tools | Edit Favorite
Colors… from the main menu.

O
Tick the check box Flashing then choose colours for the On and
OFF states.

se
lU
Continued on next page
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 6-27


Flashing Colours, Continued

Exercise 6-8 Use the Edit Color Favorites tool to create a new flashing colour to use in text
objects.

Step Action
1 Create a new Flashing Colour.
i. Return to the Citect Graphics Builder and open the Pasteuriser
page.
ii. Open Edit Favorite Colors select an Unused space.

LY
N
O
iii. se
Tick the Flashing box and make sure that On State is
selected. Choose a bright green colour for the On State.
lU
r na
te
In
ct
ite
C

Continued on next page

6-28 CitectHMI/SCADA Version 6.00 August 2005


Flashing Colours, Continued

Exercise 6-8 (continued)

Step Action
iv. Select the Off State and choose a dull green as the Off State
colour.

LY
N
O
se
lU
v. Name the new colour Flashing Green then click the Replace
button.
r na
te
In
ct
ite
C

vi. Click OK to save the settings.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 6-29


Flashing Colours, Continued

Exercise 6-8 (continued)

Step Action
2 Add the new flashing colour to the animated text objects on
the gr_Past page.
i. Return to the Pasteuriser page and open the properties of the
text object Silo Agitator OFF.
ii. Change the ON color: to the new colour Flashing Green.

LY
N
O
se
lU
r na
te

iii. Click OK to continue.


iv. Change the colours in these text objects :
In

Text Object OFF color: ON color:


ct

Centrifugal Strawberry Flashing Green


Clarifier OFF
ite

Agitator OFF Strawberry Flashing Green


Homogeniser Strawberry Flashing Green
C

OFF

3 Save the page.


4 Compile and Run your project. Open the gr_Past page to check
your new colours.

6-30 CitectHMI/SCADA Version 6.00 August 2005


Flashing Images

Overview The Graphics Builder has several file format filters to allow you to import
graphics from other applications, such as drafting programs, illustration
programs, presentation packages, scanners, etc. After a graphic is imported,
you can use the graphics builder to edit the image.

CitectSCADA now has a facility to allow you to import two images to create
a flashing image.

LY
Note: If you have selected Import as Flashing , two Import dialog boxes
will appear in sequence, allowing you to choose two images that

N
you'd like to implement as a flashing symbol. The Import Primary
dialog, allows you to select the initial image used, while the

O
Import Flashing dialog allows you to choose the second images
used.

Creating a New ¾ To create a new flashing image:


se
lU
Flashing Image
In the Citect Graphics Builder choose File | Import As Flashing… . Select a
Primary Image then select a Secondary Image.
na

Continued on next page


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 6-31


Flashing Images, Continued

Exercise 6-9 Create a flashing image of a tank that changes colour from red to green.

Step Action
1 Import an image as flashing.
i. Return to the Citect Graphics Builder and open the page
Pasteuriser.
ii. Choose File | Import As Flashing… from the menu.
iii. The first image you need is the primary. Select the file

LY
red_tank.jpg. This file will be provided by your instructor. Click
Open to continue.

N
O
se
lU
r na
te
In
ct

Continued on next page


ite
C

6-32 CitectHMI/SCADA Version 6.00 August 2005


Flashing Images, Continued

Exercise 6-9 (continued)

Step Action
iv. The next image you need is the Flash Image. Select the file
green_tank.jpg as the Flash Image. Click Open to continue.

LY
N
O
se
lU
na

The image that appears on your page looks like the original red
r

tank.
te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 6-33


Flashing Images, Continued

Exercise 6-9 (continued)

Step Action
v. Select the new image and open the bitmap Editor. Examine
the pixels in the image. You will see that the pixels display
both colours as a two colour block, divided diagonally.

LY
N
O
se
lU
2 Save the page.
3 Compile and Run the project. Open the Truecolor page and
na

view the image.


r
te
In
ct
ite
C

6-34 CitectHMI/SCADA Version 6.00 August 2005


Chapter 7: Graphics Builder Automation Interface
Overview

Introduction The Citect Graphics Builder now offers support for "Automation", a concept
developed by Microsoft that enables the integration of development tools and
applications. The Citect Graphics Builder Automation Interface enables
Citect Graphics Builder to act as an Automation Server, as it exposes many
Graphics Builder functions as well as some Project Editor and Citect Explorer
functions.

LY
Contents This chapter contains the following topics:

N
Topic See Page

O
¾ Automation 7-2
¾ Placing Symbols on a Page 7-3
¾
¾
Adding Properties to Objects
Using Genies se 7-10
7-13
lU
¾ Drawing Objects on Pages 7-19
r na
te
In
ct
ite
C
Automation

Overview Automation is an OLE service based on Microsoft’s COM technology. It


allows applications to expose their functionality, or to control the
functionality of other applications on the same computer or across a network.
As a result, applications can be integrated and automated with programming
code, creating endless development possibilities.

The two key elements of Automation are:

LY
¾ Applications or software components, called Automation Servers that can
be controlled because their functionality has been exposed and made
accessible to other applications. Examples of Microsoft Automation

N
servers are all Microsoft Office applications and Microsoft Project. These
Automation servers expose their functionality through object models.

O
¾ Other applications or development tools, called Automation Controllers
that can control OLE Automation servers through programming code, by
accessing the functionality exposed by the Automation servers. Examples

se
of Microsoft Automation controllers are Microsoft Visual Basic,
Microsoft Visual C++, and Microsoft Visual Basic for Applications
(which is built into Microsoft Access, Microsoft Excel, and Microsoft
lU
Project).

Automation is the umbrella term for the process by which an Automation


na

controller sends instructions to an Automation server (using the functionality


exposed by the Automation server), where they are run.
r

The Citect Graphics Builder Automation Interface enables Citect Graphics


te

Builder to act as an Automation Server, as it exposes many Graphics Builder


functions as well as some Project Editor and Citect Explorer functions.
In

In this series of exercises we will be using Microsoft Excel as the Automation


Controller. The Visual Basic Editor in Excel will be used to create macros
ct

that will place objects on pages in the Citect Graphics Builder.


ite
C

7-2 CitectHMI/SCADA Version 6.00 August 2005


Placing Symbols on a Page

Simple Objects The first of these tasks will be to place simple objects on the page. This may
be achieved by using the Graphics Builder Automation Interface Library
Functions. In the Visual Basic script we need to define:

¾ The Project where the symbols are located


¾ The Symbol Library
¾ The Symbol

LY
¾ The X and Y co-ordinates where the object will be placed on the page.

Once the script has been written the objects will be listed in an Excel

N
worksheet. An added benefit of using the Graphics Builder Automation
Interface in this way is that you will have a database that lists every object

O
placed on your pages.

See Also:

se
For further information about Library Functions, see Citect Help Topics -
Graphics Builder Automation Interface functions: Library.
lU
Continued on next page
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 7-3


Placing Symbols on a Page, Continued

Exercise 7-1

Step Action
1 Create an Excel macro to run the Visual Basic script.
i. Open a new Excel workbook.
ii. Choose Tools | Macro | Security… from the menu. Make sure
that the Security Level is set to either Medium or Low.

LY
N
O
se
lU
r na
te

iii. Rename the first worksheet Symbols.


iv. Save the workbook as RecipePage.xls.
In

Continued on next page


ct
ite
C

7-4 CitectHMI/SCADA Version 6.00 August 2005


Placing Symbols on a Page, Continued

Exercise 7-1 (continued)

Step Action
2 Create your Module.
i. Choose Tools | Macro | Visual Basic Editor from the menu.
This will open the Visual Basic Editor within Excel and allow
you to write your code.
ii. Choose Insert | Module from the menu.

LY
N
O
iii.
se
You will see your VBAProject in the Project pane on the left
side of your work area. In the Properties pane change the
lU
Name of your module from Module1 to DrawTanks.
r na
te
In
ct
ite

iv. The Excel worksheet needs to be able to reference Citect


Graphics Builder functions. Choose Tools | References from
the menu.
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 7-5


Placing Symbols on a Page, Continued

Exercise 7-1 (continued)

Step Action
2 v. Select GraphicsBuilder 6.1 Type Library from the list of
(cont.) Available References.

LY
N
O
se
lU
na

3 Write the code to insert the objects onto the gr_Silo page.
i. Create a new subroutine called DrawObjectsOnPage().
r

ii. Declare these variables.


te
In

Public Sub DrawObjectsOnPage()


Dim gb As GraphicsBuilder.GraphicsBuilder
Dim project As String
ct

Dim library As String


Dim object As String
Dim xpos As Integer
ite

Dim ypos As Integer


Dim row As Integer
C

iii. Connect to the current instance of the Citect Graphics Builder.

Set gb=New GraphicsBuilder.GraphicsBuilder


gb.Visible = True

Continued on next page

7-6 CitectHMI/SCADA Version 6.00 August 2005


Placing Symbols on a Page, Continued

Exercise 7-1 (continued)

Step Action
3 iv. Loop through the list of objects on the spreadsheet.
(cont.)

row = 2
While Cells(row, 1).Value <> ""
project = Cells(row, 1).Value

LY
library = Cells(row, 2).Value
object = Cells(row, 3).Value
xpos = CInt(Cells(row, 4).Value)
ypos = CInt(Cells(row, 5).Value)

N
O
v. Ask the Citect Graphics Builder to place the object on the
current page. This may be done by using the function
LibraryObjectPlaceEx().

se
gb.LibraryObjectPlaceEx project,library,
object, 0, True, xpos, ypos
lU
vi. Go to the next row.
na

row = row + 1
r

vii. End the loop and the subroutine.


te
In

Wend
End Sub
ct

viii. Save the module.


ite

Continued on next page


C

Advanced Configuration Concepts Manual Revision 2-INT 7-7


Placing Symbols on a Page, Continued

Exercise 7-1 (continued)

Step Action
4 Return to the workbook. List the symbols that will be placed
on your page gr_Recipe.
i. Create headings for each of the columns in your worksheet
Symbols. Use these values to place tanks onto the page.
Save the workbook.

LY
N
O
se
lU
Continued on next page
r na
te
In
ct
ite
C

7-8 CitectHMI/SCADA Version 6.00 August 2005


Placing Symbols on a Page, Continued

Exercise 7-1 (continued)

Step Action
5 Place the symbols on a graphics page.
i. In the Citect Graphics Builder open the page gr_Recipe.
ii. Return to the Excel worksheet and go to Tools | Macro |
Macros to Run the macro DrawObjectsOnPage.

LY
N
O
se
lU
na

iii. Open the Citect Graphics Builder. The nine objects will be
pasted onto the page.
r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 7-9


Adding Properties to Objects

Exercise 7-2 The Citect Graphics Builder Automation Interface has a library of Dynamic
Properties Functions. These functions will allow you to modify the dynamic
properties of the graphics objects in your project (movement, scaling,
rotation, sliders, dynamic colour fill).

See Also:
For further information about Dynamic Properties Functions, see Citect Help
Topics - Graphics Builder Automation Interface functions: dynamic properties.

LY
Step Action

N
1 Create a new Excel macro to run the Visual Basic script that
will add objects with dynamic properties to your page.

O
i. Return to your Excel workbook and open the Visual Basic
Editor.
ii. Copy the DrawObjectsOnPage() subroutine and paste

iii. se
underneath. Rename the subroutine DrawDynamicObjects().
Add two more variables, tag and max, to the new subroutine
as shown below in bold.
lU
Public Sub DrawDynamicObjects()
na

Dim gb As GraphicsBuilder.GraphicsBuilder
Dim project As String
Dim library As String
Dim object As String
r

Dim xpos As Integer


te

Dim ypos As Integer


Dim tag As String
In

Dim max As String


Dim row As Integer
ct

iv. Add the references to the tag and max values to the while
loop.
ite

project = Cells(row, 1).Value


library = Cells(row, 2).Value
C

object = Cells(row, 3).Value


xpos = CInt(Cells(row, 4).Value)
ypos = CInt(Cells(row, 5).Value)
tag = Cells(row, 6).Value
max = Cells(row, 7).Value

Continued on next page

7-10 CitectHMI/SCADA Version 6.00 August 2005


Adding Properties to Objects, Continued

Exercise 7-2 (continued)

Step Action
1 v. After the objects have been placed on the page the Fill
(cont.) properties need to be added to the objects. This is done using
the function PropertiesFillLevelPut(). The code will look like
this.

LY
gb.LibraryObjectPlaceEx project, library,
object, 0, True, xpos, ypos
If tag <> "" Then

N
gb.PropertiesFillLevelPut tag, True, 0,
max, 0, 100, 0, 0

O
End If

2
vi. Save the module.

se
Return to the Excel workbook and add the tanks symbols that
lU
will have the fill properties defined.
i. Add these values to your worksheet underneath the tanks
defined in the first exercise.
r na

Project Library Object X Y Tag Max


te

Milk tanks fill_milk 56 76 Rec_Milk_PV 1000


Milk tanks fill_sug 224 120 Rec_Sugar_PV 100
In

Milk tanks fill_choc 328 120 Rec_Chocolate_PV 100


Milk tanks fill_car 432 120 Rec_Caramel_PV 100
Milk tanks fill_str 536 120 Rec_Strawberry_PV 100
ct

Milk tanks fill_ban 640 120 Rec_Banana_PV 100


Milk tanks fill_coff 744 120 Rec_Coffee_PV 100
ite

Milk tanks fill_malt 848 120 Rec_Malt_PV 100


Milk tanks fill_van 952 120 Rec_Vanilla_PV 100
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 7-11


Adding Properties to Objects, Continued

Exercise 7-2
(continued)

Step Action
3 Test the macro.
i. Save the workbook.
ii. Return to the Citect Graphics Builder and open the page
gr_Recipe. Delete the symbols that were pasted in the

LY
previous exercise. This macro will paste those symbols back
onto the page.
iii. Return to the Excel worksheet and Run the macro
DrawDynamicObjects.

N
iv. Open the Citect Graphics Builder. All eighteen objects will be
pasted onto the page. Open the objects to check that the Fill

O
properties have been added correctly.

se
lU
na


r
te
In
ct
ite
C

7-12 CitectHMI/SCADA Version 6.00 August 2005


Using Genies

Exercise 7-3 Genies may be added to a page in the same way as symbols. However, genies
have properties that need to be defined. This is also possible using the
Automation Interface. The function LibraryObjectPutProperty() sets the value
of a specified property for the active genie.

Step Action
1 Create a new controller genie for the Recipe page.
i. Open the Cicode file Popup.ci. Copy the function IndControl()

LY
underneath the original. Change the name of the function to
RecControl(). Change the sTag3 reference.
From

N
To

O
ii.

iii.
RecController. se
Open the genie IndController. Save the genie as

Change the commands in the Valve Symbol Set


lU
Symbols OFF valve_solenoid.down_small_red
na

ON valve_solenoid.down_small_green
ON symbol IfDef("%ValveOpen%_Valve_Open",,0)
r

when
te

Visibility IfDef("%ValveOpen%_Valve_Open",0,1)
(Hidden
when)
In

Input RecControl("%ValveOpen%",
(Touch) "%ValveMan%","%Control%",%X%, %Y%)
ct

iv. Change the commands in the numeric object.


ite

Appearance IfDef("Rec_%Control%",,0)
(Numeric
C

Expression)
Visibility IfDef("Rec_%Control%",0,1)
(Hidden when)
Input (Touch) RecControl("%ValveOpen%",
"%ValveMan%","%Control%",%X%, %Y%)
Input TagWrite("Rec_%Control%",ArgValue1)
(Keyboard
command)
#### ENTER

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 7-13


Using Genies, Continued

Exercise 7-3 (continued)

Step Action
1 v. Change this command in the %Control% text object.
(cont.)

Visibility (Hidden when) IfDef("Rec_%Control%",0,1)

LY
vi. If you have added any other objects to your genie you will
need to update the corre3sponding commands.
2 Add another definition to the Genie Form.

N
i. Open the genie form training.frm.
ii. Add this definition for your new genie.

O
FORM "RecController", "SuperGenie - Valve
Indicator/Controller";

1: "ValveOpen", se
32, readwrite,
lU
"Variable Tags", "NAME","*_Valve_Open";
2: "ValveMan", 32, readwrite,
"Variable Tags", "NAME","*_Valve_Man";
3: "Control", 32, readwrite,
na

"Variable Tags", "NAME","Rec_*";


4: "X", 4, readwrite;
5: "Y", 4, readwrite;
r
te

NORMAL
"Valve Open {1 }
In

Valve Man {2 }
Control {3 }
X {4 } Y {5 }"
ct

iii. Save the genie form.


ite

iv. Return to the genie and save.


C

Continued on next page

7-14 CitectHMI/SCADA Version 6.00 August 2005


Using Genies, Continued

Exercise 7-4

Step Action
1 Create a new subroutine that will paste genies onto your
graphics page.
i. Return to the Visual Basic Editor and copy and paste the code
from the DrawDynamicObjects() subroutine. Rename the new
subroutine DrawGeniesOnPage().

LY
ii. Delete the tag and max variables. Add three more variables
for the genie definitions and two more variables for the X and
Y co-ordinates of the supergenie page.

N
Public Sub DrawGeniesOnPage()

O
Dim gb As GraphicsBuilder.GraphicsBuilder
Dim project As String
Dim library As String
Dim object As String
Dim xpos As Integer
Dim ypos As Integer
Dim tag1 As String
se
lU
Dim tag2 As String
Dim tag3 As String
Dim sgx As String
na

Dim sgy As String


Dim row As Integer

iii. Add references to the sgx and sgy values to the while loop.
r
te

project = Cells(row, 1).Value


library = Cells(row, 2).Value
In

object = Cells(row, 3).Value


xpos = CInt(Cells(row, 4).Value)
ypos = CInt(Cells(row, 5).Value)
ct

tag1 = Cells(row, 6).Value


tag2 = Cells(row, 7).Value
ite

tag3 = Cells(row, 8).Value


sgx = Cells(row, 9).Value
sgy = Cells(row, 10).Value
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 7-15


Using Genies, Continued

Exercise 7-4 (continued)

Step Action
1 iv. Delete the previous if statement that added the fill properties
(cont.) to the dynamic objects. Replace that statement with one that
will add properties to each of the genie substitutions.

If object = "reccontroller" Then

LY
If tag1 <> "" Then
gb.LibraryObjectPutProperty
"ValveOpen",tag1
End If

N
If tag2 <> "" Then

O
gb.LibraryObjectPutProperty
"ValveMan",tag2
End If

If tag3 <> "" Then


se
gb.LibraryObjectPutProperty
"Control",tag3
lU
End If

If sgx <> "" Then


na

gb.LibraryObjectPutProperty "X", sgx


End If

If sgy <> "" Then


r

gb.LibraryObjectPutProperty "Y", sgy


te

End If
End If
In

v. Save the module.


ct

Continued on next page


ite
C

7-16 CitectHMI/SCADA Version 6.00 August 2005


Using Genies, Continued

Exercise 7-4 (continued)

Step Action
2 Create a new worksheet for the genie definitions.
i. Return to the worksheet and open the second worksheet.
Name the worksheet Genies.
ii. Add these values to the worksheet.

LY
Note: Check your project name. If it is not Milk change the
name to whatever you have called it.

N
O
Project Library Object X Y Tag1
Milk training reccontroller 72 240 Rec_Milk
Milk
Milk
Milk
training
training
training
se
reccontroller
reccontroller
reccontroller
208
312
416
240
240
240
Rec_Sugar
Rec_Chocolate
Rec_Caramel
lU
Milk training reccontroller 520 240 Rec_Strawberry
Milk training reccontroller 624 240 Rec_Banana
Milk training reccontroller 728 240 Rec_Coffee
na

Milk training reccontroller 832 240 Rec_Malt


Milk training reccontroller 936 240 Rec_Vanilla
r

Tag2 Tag3 sgx sgy


te

Rec_Milk Milk_PV 72 338


Rec_Sugar Sugar_PV 208 338
In

Rec_Chocolate Chocolate_PV 312 338


Rec_Caramel Caramel_PV 416 338
Rec_Strawberry Strawberry_PV 520 338
ct

Rec_Banana Banana_PV 624 338


Rec_Coffee Coffee_PV 728 338
ite

Rec_Malt Malt_PV 730 338


Rec_Vanilla Vanilla_PV 732 338
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 7-17


Using Genies, Continued

Exercise 7-4 iii. Save the workbook.


(continued) iv. Open the page gr_Recipe in the Citect Graphics Builder.

9 Hints & Tips:


The automation functions apply to the current project and graphic page. If you wish
to draw objects on other pages you may do so by calling the functions
ProjectSelect() and PageOpen().

LY
v. Run the macro DrawGeniesOnPage.

N
vi. Open the Citect Graphics Builder. Open the genies to check that the genie
syntax has been inserted correctly.

O
se
lU
r na


te
In
ct
ite
C

7-18 CitectHMI/SCADA Version 6.00 August 2005


Drawing Objects on Pages

Exercise 7-5 The Graphics Builder Automation Interface gives you the flexibility to draw
objects and specify many of their attributes. Using the Object Drawing and
Attribute Functions you are able to pinpoint exactly where you would like to
place lines, pipes, polylines, ellipses and others. You can set attributes such
as fill colours, width, highlight colours and angles.

See Also:
For further information about Object Drawing and Attribute Functions, see

LY
Citect Help Topics - Graphics Builder Automation Interface functions: objects.

N
Step Action
1 Draw pipes on your Recipe page.

O
i. Create a new subroutine called DrawPipesOnPage().
ii. Declare these variables.

se
Public Sub DrawPipesOnPage()
lU
Dim gb As GraphicsBuilder.GraphicsBuilder
Dim startx As Integer
Dim starty As Integer
Dim sectionx As Integer
na

Dim sectiony As Integer


Dim hicol As Integer
Dim locol As Integer
r

Dim row As Integer


te

iii. Connect to the current instance of the Citect Graphics Builder.


In

Set gb = New GraphicsBuilder.GraphicsBuilder


gb.Visible = True
ct

iv. Turn off the attribute that opens the Properties dialog when a
ite

new object is drawn.

gb.OptionDisplayPropertiesOnNew = False
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 7-19


Drawing Objects on Pages, Continued

Exercise 7-5 (continued)

Step Action
1 v. Loop through the list of objects on the spreadsheet.
(cont.)

row = 2
While Cells(row, 1).Value <> ""
startx = CInt(Cells(row, 1).Value)

LY
starty = CInt(Cells(row, 2).Value)
sectionx = CInt(Cells(row, 3).Value)
sectiony = CInt(Cells(row, 4).Value)
hicol = CInt(Cells(row, 5).Value)

N
locol = CInt(Cells(row, 6).Value)

O
vi. Draw the start position, end of section position and end the
pipe.

se
gb.DrawPipeStart startx, starty
gb.DrawPipeSection sectionx, sectiony
gb.DrawPipeEnd
lU
vii. Set the highlight and lowlight colours

gb.AttributeHiLightColour = hicol
na

gb.AttributeLoLightColour = locol

viii. Move the pipe to the back of the other objects.


r
te

gb.PositionSendToBack
In

ix. Go to the next row then end the loop and the subroutine.
ct

row = row + 1
Wend
ite

x. Turn on the attribute that opens the Properties dialog when a


new object is drawn and end the subroutine.
C

gb.OptionDisplayPropertiesOnNew = True
End Sub

xi. Save the module.

Continued on next page

7-20 CitectHMI/SCADA Version 6.00 August 2005


Drawing Objects on Pages, Continued

Exercise 7-5 (continued)

Step Action
2 Define the pipes to be drawn in another worksheet.
i. Rename the third worksheet Pipes.
ii. Enter these values to draw your pipes

LY
startx starty sectionx sectiony hicol locol
112 312 972 312 7 8
112 194 112 312 7 8

N
249 194 249 312 7 8
353 194 353 312 7 8

O
457 194 457 312 7 8
561 194 561 312 7 8
665 194 665 312 7 8
769
873
194
194
769
873 se 312
312
7
7
8
8
lU
977 194 977 312 7 8
1081 194 1081 312 7 8
1185 194 1185 312 7 8
178 312 178 345 7 8
na

178 345 70 345 7 8


70 345 90 330 7 8
r

70 345 90 360 7 8
te

iii. Save the workbook.


In

iv. Run the macro DrawPipesOnPage.


v. Open the Citect Graphics Builder. Your page should now look
like this. (You may need to reposition your tanks)
ct
ite
C

 Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 7-21


Drawing Objects on Pages, Continued

Exercise 7-6

Step Action
1 Use the Graphics Builder Automation Interface to draw your
Silo Page.
i. Create a new Excel workbook called SiloPage.xls.
ii. Add a reference to the GraphicsBuilder 6.0 Type Library.
iii. Create a new module called DrawSilos.

LY
iv. Create a new subroutine called PutProperty(). This subroutine
will be used in your main function to help streamline the code.

N
Sub PutProperty(gb As
GraphicsBuilder.GraphicsBuilder, property

O
As String, value As String)
If value <> "" Then
gb.LibraryObjectPutProperty property,

End If
End Sub
value
se
lU
v. Create a new subroutine called DrawSilosOnPage().
vi. Declare these variables.
na

Public Sub DrawSilosOnPage()


Dim gb As GraphicsBuilder.GraphicsBuilder
r

Dim project As String


te

Dim library As String


Dim object As String
In

Dim xpos As Integer


Dim ypos As Integer
Dim tag1 As String
ct

Dim tag2 As String


Dim sgx As String
Dim sgy As String
ite

Dim row As Integer


C

Continued on next page

7-22 CitectHMI/SCADA Version 6.00 August 2005


Drawing Objects on Pages, Continued

Exercise 7-6 (continued)

Step Action
1 vii. Loop through the list of objects on the spreadsheet.
(cont.)

row = 2
While Cells(row, 1).Value <> ""
project = Cells(row, 1).Value

LY
library = Cells(row, 2).Value
object = Cells(row, 3).Value
xpos = CInt(Cells(row, 4).Value)
ypos = CInt(Cells(row, 5).Value)

N
tag1 = Cells(row, 6).Value
tag2 = Cells(row, 7).Value

O
sgx = Cells(row, 8).Value
sgy = Cells(row, 9).Value

viii. Connect to the current instance of the Citect Graphics Builder.

se
Set gb =New GraphicsBuilder.GraphicsBuilder
lU
gb.Visible = True

ix. Ask the Citect Graphics Builder to place the object on the
na

current page.

gb.LibraryObjectPlaceEx project, library,


r

object, 0, True, xpos, ypos


te

If object = "silo" Then


In

PutProperty gb, "Silo_No", tag1


End If
If object = "indcontroller" Then
PutProperty gb, "Valve", tag1
ct

PutProperty gb, "Control", tag2


PutProperty gb, "X", sgx
ite

PutProperty gb, "Y", sgy


End If
C

x. Go to the next row then end the While loop and the
subroutine.

row = row + 1
Wend
End Sub

xi. Save the module.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 7-23


Drawing Objects on Pages, Continued

Exercise 7-6 (continued)

Step Action
2 Return to the workbook.
i. Name one of your worksheets Symbols.
ii. List the symbols and genies that will be placed on your page
gr_Silos.
iii. Copy these values into the worksheet Symbols.

LY
N
O
iv. Save the workbook. se
lU
v. Return to the Citect Graphics Builder and open the page
gr_Silos.
vi. Return to the Excel worksheet and Run the macro
DrawSilosOnPage.
na

vii. Open the Citect Graphics Builder. The six objects will be
pasted onto the page. Open the genies to check that the genie
syntax is correct.
r
te
In
ct
ite
C

Continued on next page

7-24 CitectHMI/SCADA Version 6.00 August 2005


Drawing Objects on Pages, Continued

Exercise 7-6 (continued)

Step Action
3 Add pipes to your page gr_Silos.
i. Create a new subroutine called DrawPipesOnPage() and copy
the code on the following page.

Public Sub DrawPipesOnPage()

LY
Dim gb As GraphicsBuilder.GraphicsBuilder
Dim startx As Integer
Dim starty As Integer

N
Dim sectionx As Integer
Dim sectiony As Integer

O
Dim hicol As Integer
Dim locol As Integer
Dim colA As Integer
Dim ExpA As String
Dim row As Integer
se
Set gb =New GraphicsBuilder.GraphicsBuilder
lU
gb.Visible = True
gb.OptionDisplayPropertiesOnNew = False
row = 2
While Cells(row, 1).Value <> ""
na

' Get the data from the active row


startx = CInt(Cells(row, 1).Value)
starty = CInt(Cells(row, 2).Value)
r

sectionx = CInt(Cells(row, 3).Value)


te

sectiony = CInt(Cells(row, 4).Value)


hicol = CInt(Cells(row, 5).Value)
In

locol = CInt(Cells(row, 6).Value)


ExpA = Cells(row, 7).Value
colA = CInt(Cells(row, 8).Value)
gb.DrawPipeStart startx, starty
ct

gb.DrawPipeSection sectionx, sectiony


gb.DrawPipeEnd
ite

gb.AttributeHiLightColour = hicol
gb.AttributeLoLightColour = locol
gb.PropertiesFillColourPut 0, ExpA,
C

"", "", "", "", False, 0, 0


gb.PropertiesFillColourColourPut 0,
hicol, 0, 0
gb.PropertiesFillColourColourPut 1,
colA, 0, 0
gb.PositionSendToBack
row = row + 1
Wend
gb.OptionDisplayPropertiesOnNew = True
End Sub

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 7-25


Drawing Objects on Pages, Continued

Exercise 7-6 (continued)

Step Action
1 ii. Create a new worksheet called Pipes.
(cont.)
iii. Use these values to draw your pipes:

startx starty sectionx sectiony hicol locol ExpA ColA

LY
248 448 480 448 7 8 Silo_1_Valve_Open 15
480 448 720 448 7 8 Silo_3_Valve_Open 15
248 310 248 448 7 8 Silo_LI_1_PV > 0 15
480 310 480 448 7 8 Silo_LI_2_PV > 0 15

N
721 310 721 448 7 8 Silo_LI_3_PV > 0 15

O
480 448 480 540 7 8 Silo_1_Valve_Open or 15
Silo_2_Valve_Open or
Silo_3_Valve_Open
480 540 920 540 7
se
8 Silo_1_Valve_Open or
Silo_2_Valve_Open or
Silo_3_Valve_Open
15
lU
920 540 905 530 7 8 Silo_1_Valve_Open or 15
Silo_2_Valve_Open or
Silo_3_Valve_Open
na

920 540 905 550 7 8 Silo_1_Valve_Open or 15


Silo_2_Valve_Open or
Silo_3_Valve_Open
r
te

Continued on next page


In
ct
ite
C

7-26 CitectHMI/SCADA Version 6.00 August 2005


Drawing Objects on Pages, Continued

Exercise 7-6 (continued)

Step Action
1 iv. Save the workbook.
(cont.)
v. Run the macro DrawPipesOnPage.
vi. Your page should now look like this.

LY
N
O
se
lU
r na
te
In

vii. Save all your pages.


ct


ite
C

Advanced Configuration Concepts Manual Revision 2-INT 7-27


LY
N
O
se
lU
nar
te
In
ct
ite
C

7-28 CitectHMI/SCADA Version 6.00 August 2005


Chapter 8: CitectSCADA and Other Applications
Overview

Introduction You can transfer data between CitectSCADA and a wide range of software
applications for storage, analysis, and post processing, or to control and tune
your CitectSCADA system. In this chapter we will discuss methods for
exchanging data with CitectSCADA and other applications.

LY
Contents This chapter contains the following topics:

Topic See Page

N
¾ CitectSCADA and ODBC 8-2
¾ Data Source Names 8-3

O
¾ How CitectHMI/SCADA Uses ODBC 8-5
¾ CiRecipe Active X Control 8-14
¾
¾
se
Configuring the ActiveX Control
Editing the Database from CitectSCADA Runtime
8-16
8-24
lU
¾ Updating CitectSCADA Tags 8-26
¾ Active X and Citect 8-30
na

¾ ActiveX Objects Using Cicode 8-34


¾ Active X Methods 8-35
r

¾ Events 8-42
te
In
ct
ite
C
CitectSCADA and ODBC

Overview CitectSCADA supports the Open DataBase Connectivity (ODBC) standard.


Many manufacturers of database packages now also supply an ODBC
database driver for their software. As well as these there are independent
parties manufacturing ODBC database drivers for a wide variety of databases.
In most cases, however, any ODBC driver for your database will work.

CitectSCADA provides two methods of communicating with your database:


through Citect Devices and through the SQL class of Cicode functions.

LY
Devices are most useful when you wish to use the automatic reporting and
logging features of CitectSCADA. The SQL functions, on the other hand,
provide absolute control and flexibility over your connections and queries.

N
Querying a database via the Device system will be slower than constructing
your own query via an SQL function due to the generic nature of a device.

O
Data Source A Data Source Name or DSN is used to provide connectivity to a database
Names

se
through an ODBC driver. The DSN contains information such as the
database name, directory, database driver, User ID and password and more.
When a DSN is created for a particular database you can use the DSN in an
lU
application like CitectSCADA to call information from that database.

How to ¾ To create a new DSN:


na

Double click on the Data Sources (ODBC) icon in Control


Panel | Administrative Tools.
r
te
In
ct
ite
C

8-2 CitectHMI/SCADA Version 6.00 August 2005


Data Source Names

Exercise 8-1 Create a DSN called Alfast and select the Alfast.mdb.

Step Action
1 Create a DSN called Alfast and select the Alfast.mdb.
i. Go to the Windows Control Panel. Open Administrative
Tools then open the Data Sources (ODBC).
ii. Open the System DSN tab in the ODBC Data Source
Administrator then click Add…

LY
N
O
se
lU
r na
te

iii. Choose the Microsoft Access Driver (*.mdb) then click Finish.
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 8-3


Data Source Names, Continued

Exercise 8-1 (continued)

Step Action
1 iv. In the Data Source Name field type Alfast. Click the Select…
(cont.) button to choose the Database.

LY
N
O
se
lU
v. Find the Milk project in your User folder. It contains an
na

Access Database called Alfast.mdb. Select the database


then click the OK buttons to close all the ODBC dialogs.
r
te
In
ct
ite
C

Note: Check that your project is called Milk. If it is not look in


the folder that has the same name as your project.

8-4 CitectHMI/SCADA Version 6.00 August 2005


How CitectHMI/SCADA Uses ODBC

Overview CitectHMI/SCADA connects directly to the Microsoft Access ODBC driver,


which allows applications to access information stored in MDB (Microsoft
Access Database) files without actually running Microsoft Access.
(Microsoft Access uses the "Jet Engine" DLL to access information stored in
MDB files.)

ODBC normally implies heavy use of SQL statements to manipulate data.


SQL statements can become quite complex and verbose. To implement them

LY
in Cicode they often have to be broken into chunks so that the maximum
string length for Cicode variables is not exceeded.

N
With Access, it is possible to call queries that have been defined in Access so
that the SQL statements become quite simple and straight forward. The

O
Access tables & queries can be used to implement RELATIONSHIPS and
JOINS, to SORT & SELECT only those rows (records) and return only those
columns (fields) of particular interest at the time.

Note: se
Some query commands e.g. JOIN are not available in SQL. They
lU
may only be used in queries defined in Access.

Developing queries in Access also has an advantage that the resulting


na

Recordsets can be viewed in Access to make sure they contain the data that is
expected. The queries can incorporate SQL Functions (such as BETWEEN &
AND).
r
te

Continued on next page


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 8-5


How CitectHMI/SCADA Uses ODBC, Continued

Exercise 8-2

Step Action
1 Write a function that will connect to a Microsoft Access
database using ODBC.
i. Open the Cicode Editor and create a new Cicode file called
Alfast.ci.
ii. Start your function by declaring module arrays for all the

LY
elements of the recipe database.

STRING msRecipes[100];

N
STRING msName[100];
STRING msMilkFat[100];
STRING msProtein[100];

O
STRING msSNF[100];

iii.
se
Name your function and declare the local variables.
lU
INT
FUNCTION
AlfastRecipe()
na

INT hSQL;
INT hForm = -1;
INT iStatus;
r

INT iIndex;
te

INT i;
INT iOffset;
In

STRING sBuf;

Continued on next page


ct
ite
C

8-6 CitectHMI/SCADA Version 6.00 August 2005


How CitectHMI/SCADA Uses ODBC, Continued

Exercise 8-2 (continued)

Step Action
2 Define the database connection section of your function.
i. Connect to the Access database using the function
SQLConnect(). This function makes a connection to a
database system, and returns a handle to the connection for
use by the other SQL functions. Through this connection, you
can execute SQL statements in the specified database. You

LY
must call this function before any other SQL function.

hSQL = SQLConnect("DSN = Alfast");

N
IF hSQL <> -1 THEN

O
ii. Use the function SQLExec() to execute an SQL query on a
database. With this function, you can execute any SQL query
or command supported by the SQL database.

se
iStatus = SQLExec(hSQL, " SELECT * FROM
Alfast");
lU
iIndex = 0;
IF iStatus = 0 THEN
na

iii. The SQLNext() function gets the next database record from an
SQL query or the first record if no record is currently selected.
r

WHILE SQLNext(hSQL) = 0 DO
te

iv. The function SQLGetField() gets field or column data from a


database record. After you have used this function to extract
In

the data from each field save the data into an array for later
use.
ct

msName[iIndex] = SQLGetField(hSQL, "ALFNAME");


ite

msMilkFat[iIndex] =SQLGetField(hSQL, "MILKFAT");


msProtein[iIndex] =SQLGetField(hSQL, "PROTEIN");
msSNF[iIndex] = SQLGetField(hSQL, "SNF");
C

msRecipes[iIndex]=StrPad(IntToStr(iIndex)," ",4)
+ StrPad(msName[iIndex]," ",20);
iIndex = iIndex + 1;
END

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 8-7


How CitectHMI/SCADA Uses ODBC, Continued

Exercise 8-2 (continued)

Step Action
2 v. End the SQL query by using the function SQLEnd() and add an
(cont.) error message if the query was unsuccessful. If you have
called the SQLExec() function from within a database
connection, you should call SQLEnd() before you disconnect
from that database. When the SQLEnd() function ends the
execution of the current SQL query, it frees the memory that
was allocated for that query.

LY
SQLEnd(hSQL);
ELSE

N
Message("Error", SQLErrMsg(), 48);
END

O
vi. Close the database connection using the function
SQLDisconnect(). You should close all connections to

se
databases before you shut down CitectHMI/SCADA, to release
system resources. Add an error message if the SQL
connection has been unsuccessful.
lU
SQLDisconnect(hSQL);
ELSE
Message("Error", SQLErrMsg(), 48);
na

END
3 Using Cicode create a form to display your database
information during runtime. Append this code to the current
function.
r
te

i. Use this code to display your recipes. Notice that in this form
the combo box and a FormAddList() function for each recipe
name is not used as it was in the exercises in Chapter 4.
In

Instead the FormAddList() function receives the name of each


recipe from the array msRecipes[i].
ct

hForm = FormNew("Alfast Recipe", 50, 10,2);


FormListBox(2 ,2, 46, 7, sBuf, 1);
ite

FOR i = 0 TO iIndex DO
FormAddList(msRecipes[i]);
END
C

FormPrompt(6,1,"NAME");
FormButton(3,9 ," OK ", 0, 1);
FormButton(15 ,9 ," Cancel ", 0, 2);

IF FormRead(0) = 0 THEN

Continued on next page

8-8 CitectHMI/SCADA Version 6.00 August 2005


How CitectHMI/SCADA Uses ODBC, Continued

Exercise 8-2 (continued)

Step Action
4 Set the PLC Variables.
i. Strip the first 3 characters from the array to determine the
recipe number.

iOffset = StrToInt(StrLeft(sBuf,3));

LY
ii. Assign the variables.

N
AlfastRecPLC = msName[iOffset];
MilkFatPLC = msMilkFat[iOffset];
ProtPLC = msProtein[iOffset];

O
SNF_PLC = msSNF[iOffset];

iii. End the IF Formread() statement, RETURN 0 and END the


function.

END
se
lU
RETURN 0;
END

iv. Save your file and compile.


na

Continued on next page


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 8-9


How CitectHMI/SCADA Uses ODBC, Continued

Exercise 8-2 (continued)

Step Action
5 Test your new function.
i. Return to the Citect Graphics Builder and open the page
gr_Forms.
ii. Assign the AlfastRecipe() function to the Select/Edit button.
iii. Compile and run your project.

LY
iv. Select/Edit button and check that your form lists the recipes in
the Alfast database.

N
O
se
lU
r na
te

v. Select a recipe and click OK. The recipe you chose will be
transferred into the CitectSCADA system.
In
ct
ite
C

6 Shutdown the project.

 Continued on next page

8-10 CitectHMI/SCADA Version 6.00 August 2005


How CitectHMI/SCADA Uses ODBC, Continued

Exercise 8-3

Step Action
1 Modify the current application so that the Recipe selection list
is generated from a query.
i. Open the Alfast.mdb file in Access. Use either Access 2000
or Access XP. These screen shots are from Access XP.
ii. Go to Queries and open Create a Query in Design View.

LY
N
O
se
lU
iii. The Alfast table will be highlighted in the Show Table dialog.
Click Add then Close.
r na
te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 8-11


How CitectHMI/SCADA Uses ODBC, Continued

Exercise 8-3 (continued)

Step Action
1 iv. Highlight all the fields in the Alfast table then drag and drop
(cont.) the group into the first field.

LY
N
O
se
lU
v. All of the field names will be displayed in the query field
names. Close the query and save it as NewRecipe.
r na
te
In
ct
ite
C

Continued on next page

8-12 CitectHMI/SCADA Version 6.00 August 2005


How CitectHMI/SCADA Uses ODBC, Continued

Exercise 8-3 (continued)

Step Action
2 Modify the Alfast.ci file in the Milk project to call the new query.
i. Open the file Alfast.ci in the Cicode Editor.
ii. Find the line

iStatus = SQLExec(hSQL, "SELECT * FROM Alfast");

LY
iii. Change it to say

N
iStatus = SQLExec(hSQL, "{CALL NewRecipe}");

O
iv. Save the file


3

se
Compile and run the project.
lU
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 8-13


CiRecipe Active X Control

Overview The CiRecipe ActiveX control provides an easy method to connect to a data
source (for example a database), and extract, display, and edit recipe values.
The CiRecipe Control was developed for graphical representation in plant
SCADA applications. It visually presents database recipe data in a
customizable table grid. The control is inserted and configured on a graphics
page using the Citect Graphics Builder.

LY
N
O
se
The control features the following characteristics:
lU
¾ Recipes can be stored in any database that is running under Microsoft
Windows.
na

¾ Recipes can be downloaded to CitectHMI/SCADA tags.


¾ Add/Edit recipes.
r

¾ Easy to use with no coding required.


te

The new CiRecipe Control supports an extensible and rich range of properties
In

to manipulate its appearance and behaviour. It also generates events which


notify your application when the value of a property has changed, and for
mouse activities associated with the Control.
ct

Continued on next page


ite
C

8-14 CitectHMI/SCADA Version 6.00 August 2005


CiRecipe Active X Control, Continued

CiRecipe A help file is included with the control that explains its features and
ActiveX functionality. To keep the CiRecipe Control in line with the architecture used
Control Help for all ActiveX objects, the help file is accessible from the Appearance/Tag
Association tab of the Object Properties dialog, which appears when you
double click on the control within Graphics Builder.

LY
N
O
se
lU
na

Click the '?' button to the right of the tab to display the Help topic for the
r

currently selected property. Once the help file appears you can access further
te

information via the Contents button.


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 8-15


Configuring the ActiveX Control

Exercise 8-4 The CiRecipe ActiveX Control is designed to allow the user to display,
update and edit recipes stored in a variety of databases. The connection is
established through the use of Data Source Names. These are configurable
through the in-built dialogs of the control and require no Cicode
programming.

Step Action
1 Configure a CiRecipe ActiveX Control in your Milk project.

LY
i. Open the page gr_Recipe. The page has a table that in
runtime displays the currently loaded recipe for the milk
flavouring.

N
O
se
lU
r na
te

ii. Click the ActiveX button on the toolbar and select


In

CiRecipe.RecipMngr from the list.


ct
ite
C

iii. The ActiveX object will be placed on the page and the
CiRecipe.RecipeMngr Properties dialog will open.

Continued on next page

8-16 CitectHMI/SCADA Version 6.00 August 2005


Configuring the ActiveX Control, Continued

Exercise 8-4 (continued)

Step Action
2 Connect the ActiveX Control to the Data Source.
i. Select the tab Appearance (Connection).

LY
N
O
se
lU
na

ii. Click the Build button next to the Database Connection


String field. This will open the Data Link Properties dialog.
r
te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 8-17


Configuring the ActiveX Control, Continued

Exercise 8-4 (continued)

Step Action
2 iii. Go to the Provider tab and select Microsoft OLE Provider for
(cont.) ODBC Drivers. Click Next >> to continue.

LY
N
O
se
lU
r na
te
In

Continued on next page


ct
ite
C

8-18 CitectHMI/SCADA Version 6.00 August 2005


Configuring the ActiveX Control, Continued

Exercise 8-4 (continued)

Step Action
2 iv. In the Connection tab, click the Use Connection String radio
(cont.) button and then click Build.

LY
N
O
se
lU
r na
te

v. In the Select Data Source dialog click New… to create a new


Data Source Name.
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 8-19


Configuring the ActiveX Control, Continued

Exercise 8-4 (continued)

Step Action
2 vi. Select the Microsoft dBase Driver. Click Next > to continue.
(cont.)

LY
N
O
se
lU

vii. Name the Data Source Flavour_Recipe.


r na
te
In
ct
ite
C

Continued on next page

8-20 CitectHMI/SCADA Version 6.00 August 2005


Configuring the ActiveX Control, Continued

Exercise 8-4 (continued)

Step Action
2 viii. Name the Data Source Flavour_Recipe and click Save.
(cont.)

LY
N
O
ix.
se
Click Next in the Create New Data Source dialog. Then click
lU
Finish.
x. In the ODBC dBASE Setup dialog, select dBase IV from the
Version drop-down box and uncheck Use Current Directory.
r na
te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 8-21


Configuring the ActiveX Control, Continued

Exercise 8-4 (continued)

Step Action
2 xi. Click Select Directory… and browse to your Citect Milk folder.
(cont.) Click OK to continue.

LY
N
O
xii.
se
Keep clicking OK in each of the dialogs until you return to the
lU
Connection tab of the Data Link Properties dialog.
xiii. Click Test Connection. If the connection has been established
correctly you will see this message.
na

xiv. Click OK close the message box the OK again to close the
Data Link Properties dialog.
r
te
In
ct
ite

Continued on next page


C

8-22 CitectHMI/SCADA Version 6.00 August 2005


Configuring the ActiveX Control, Continued

Exercise 8-4 (continued)

Step Action
2 xv. You will be returned to the Appearance (Connection) tab in
(cont.) the CiRecipe.RecipMngr Properties dialog. The connection
string should now be displayed in the Database Connection
String field. Click the Unknown radio button and type
Flavour into the Record Source Information field. Click OK
to continue.

LY
N
O
se
lU
r na
te
In

xvi. The CiRecipe ActiveX control will display the current values in
the Flavour.dbf file.
ct
ite
C

xvii. Save the page and compile the project.

Advanced Configuration Concepts Manual Revision 2-INT 8-23


Editing the Database from CitectSCADA Runtime

Exercise 8-5 Once the connection between the CiRecipe ActiveX Control and the database
has been established it is possible to edit the data source from CitectSCADA
runtime. Also as this is a “live” connection the data displayed in the control
may be updated to reflect changes in the data source either manually or
automatically.

Step Action
1 Use the CiRecipe ActiveX Control to view, edit and update the

LY
data source.
i. Run the Milk project.
ii. Open the gr_Recipe page.

N
iii. Change some of the recipe values in the CiRecipe
control. Then click the Update button.

O
iv. Using Microsoft Excel open the Flavour.dbf file
located in the Milk directory. Check to see that the changes
made in CitectSCADA have been saved into the data source.

2 se
Make changes to the data source and refresh the data
displayed in the CiRecipe ActiveX Control.
lU
i. Open the file Save_dbf.xls located in the Citect\Bin directory.
This will make available an Excel macro that will allow you to
easily save dBase files in the correct format.
na

9 Hints & Tips:


r

If you are using Excel XP you may need to change the macro security
te

settings down to at least Medium level. You will find these settings in
the Tools | Macro | Security… menu.
In

ii. Add a new record to the data source then right-click on any
cell and choose Save/Close DBF from the menu. For example
ct
ite

Vanilla Caramel Really Sweet 1000 100 0 100 0 0 0 0 50

Continued on next page


C

8-24 CitectHMI/SCADA Version 6.00 August 2005


Editing the Database from CitectSCADA Runtime,
Continued

Exercise 8-5 (continued)

Step Action
2 iii. Return to the Recipe page and click the Refresh
(cont.) button.

LY
iv. The table will update and show the changes to the database.

N
O
se
lU

r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 8-25


Updating CitectSCADA Tags

Overview Every property in the CiRecipe ActiveX Control may be associated with a
CitectSCADA tag. This allows users to edit recipes and then send
information into your CitectSCADA tags directly from the runtime system.

The Columnxxx Properties correspond to the columns in your control. In this


example you can see that the first column corresponds to the Name column in
the dBase file. There are 999 possible columns to define in this control.

LY
N
O
se
lU
r na
te

When the Columnxxx Property is selected it may then be associated with a


STRING type tag. If the information is to be sent to the tags during runtime
In

then the Update Association on event must be RecipeSelected.

Continued on next page


ct
ite
C

8-26 CitectHMI/SCADA Version 6.00 August 2005


Updating CitectSCADA Tags, Continued

Exercise 8-6

Step Action
1 Assign CitectSCADA tags to each of the columns in the CiRecipe
ActiveX Control.
i. In the Citect Graphics Builder open the Recipe page and double
click the CiRecipe ActiveX Control.
ii. Select the Appearance (Tag Association) tab. Place a tick in

LY
the Column001 checkbox.

N
O
se
lU
r na
te
In

iii. Associate the property with the tag NamePLC tag.


iv. In the Update association on event choose RecipeSelected.
ct
ite

Continued on next page


C

Advanced Configuration Concepts Manual Revision 2-INT 8-27


Updating CitectSCADA Tags, Continued

Exercise 8-6 (continued)

Step Action
v. Add associations to the Properties as shown below.

Property Tag Update association on


Column002 DescPLC RecipeSelected

LY
Column003 MilkPLC RecipeSelected
Column004 SugarPLC RecipeSelected
Column005 ChocolatePLC RecipeSelected

N
Column006 CaramelPLC RecipeSelected

O
Column007 StrawberryPLC RecipeSelected
Column008 BananaPLC RecipeSelected
Column009
Column010
Column011
CoffeePLC
MaltPLC
VanillaPLC
se RecipeSelected
RecipeSelected
RecipeSelected
lU
vi. Click OK to close the Properties dialog.
na

vii. Save the page and compile.


2 Update the CitectSCADA tags using the CiRecipe ActiveX
Control.
r

i. Start the CitectSCADA runtime and open the gr_Recipe page.


te

ii. Select one of the records in the table by clicking on the grey
cell to the left of the row. The entire row will then be
In

highlighted.
ct
ite
C

iii.

Continued on next page

8-28 CitectHMI/SCADA Version 6.00 August 2005


Updating CitectSCADA Tags, Continued

Exercise 8-6 (continued)

Step Action
2 iv. Click the Select button to download the values
(cont.) into the tags.

v. Check the table to see if the recipe has been


uploaded.

LY
N
O
se
lU
r na

3 Shut down the project.


te


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 8-29


Active X and Citect

Overview CitectHMI/SCADA allows you to incorporate ActiveX objects into the


graphics pages of your CitectHMI/SCADA project, allowing you to make use
of tools and components that have been developed independently of
CitectHMI/SCADA. For example, you could incorporate a batch application
in a CitectHMI/SCADA graphics page, and use it to communicate directly
with your I/O Devices to control and monitor recipe levels, etc.

It is important to remember that the behaviour of an ActiveX object within

LY
CitectHMI/SCADA will be largely determined by the object itself. An
object's functionality, reliability and its suitability to CitectHMI/SCADA will
depend on the way the object has been developed by its creator.

N
O
Inserting The easiest way to insert an ActiveX object into your CitectHMI/SCADA
ActiveX project is via the Graphics Builder. Using the ActiveX tool from the Graphics
Objects via Builder toolbox, you can select and insert ActiveX objects in your graphics
Graphics
Builder
se
pages in much the same way conventional objects are inserted. Just like other
objects, they can also be moved, resized and copied.
lU
Continued on next page
r na
te
In
ct
ite
C

8-30 CitectHMI/SCADA Version 6.00 August 2005


Active X and Citect, Continued

Exercise 8-7

Step Action
1 Use the ActiveX tool from the Citect Graphics Builder Toolbox
to insert an ActiveX object into a page.
i. Create a new page called gr_WebBrowser.

ii. Use the ActiveX tool to insert a Microsoft Web Browser

LY
object into the page.

N
O
se
lU
na

iii. Open the Access (General) tab and note the AN number of
r

the object. You will be using this number as a reference in the


te

following exercises.
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 8-31


Active X and Citect, Continued

Exercise 8-7 (continued)

Step Action
1 iv. Enlarge the object so that it fills most of the page. Leave
(cont.) some room at the top of the page for navigation buttons.
v. Save the page.
2 Associate a STRING tag with the ActiveX object.
i. Open the properties of the ActiveX object.

LY
ii. Open the Appearance (Tag Association) tab and associate
the property LocationURL with the STRING tag URL. Make
sure that the Update association on Event is

N
NavigateComplete2.

O
se
lU
r na
te
In
ct

iii. Close the properties dialog and save the page.


ite

Continued on next page


C

8-32 CitectHMI/SCADA Version 6.00 August 2005


Active X and Citect, Continued

Exercise 8-7 (continued)

Step Action
3 Add a navigation button for this page to your menu system.
i. Open the popup page !UtilityMenu.
ii. Open the properties of the second button and add a command
to navigate to the page gr_WebBrowser. Use these settings
for the button.

LY
Appearance (General) Input (Touch) Access
Symbol Up Command (General)

N
Tool Tip
csv_icons.iexplorer_01_sml WinFree(); Web Browser

O
WinGoto(0);
PageDisplay
("gr_WebBrowser")

iii. Save the page. se


lU

r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 8-33


ActiveX Objects Using Cicode

Interacting Cicode has some ActiveX functions that enable you to create and interact
with 3rd Party with ActiveX objects. In order to use these functions you will need to find
Objects out the methods and properties of the particular ActiveX object. Methods are
functions in an object that can be called by CitectSCADA.

Most ActiveX objects come with some form of documentation to explain the
controls and functionality of the object. Some have a separate Help file
included, others may have simple text prompts that briefly explain each

LY
property. This depends entirely on what the creator of the object has
included. It is also possible to use other third party tools. For example, one
of these tools is OLE View. This tool comes with Microsoft Visual Basic.

N
O
se
lU
r na
te
In

Continued on next page


ct
ite
C

8-34 CitectHMI/SCADA Version 6.00 August 2005


ActiveX Objects Using Cicode, Continued

Active X This tool allows you to find information about ActiveX controls and the
Methods methods you will need to implement the Cicode functions.

LY
N
O
The screenshot shows the method Navigate2() and its parameters. This

se
method will allow your web browser to navigate to a specific URL. If you
are going to use 3rd party ActiveX objects you will need to use a resource
such as OLE View to find the necessary syntax to implement these methods
lU
within the control.
na

9 Hints & Tips:


The Cicode functions _ObjectGetProperty() and _ObjectSetProperty() allow you
to read and write to ActiveX properties. The Cicode function
r

ObjectAssociatePropertyWithTag() allows you to link variable tags to ActiveX


te

properties.
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 8-35


Using ActiveX Methods

Active X When you have found the methods you wish to use in your control you need
Cicode to use Cicode functions to initialise the methods in your project.
Functions

LY
N
O
se
The Cicode function _ObjectCallMethod(hObject, sMethod, vParameters)
allows you to use this functionality within your project. The first parameter
in this function is the handle of the object. The handle is returned by the
lU
function ObjectByName(sName). When you open the properties of an
ActiveX control in CitectSCADA the Appearance (Identification) tab will
display the Object Name and Event Class.
r na
te
In
ct
ite
C

Continued on next page

8-36 CitectHMI/SCADA Version 6.00 August 2005


Using ActiveX Methods, Continued

Active X When you use this with the function _ObjectCallMethod() the syntax will look
Cicode like this.
Functions
(continued) _ObjectCallMethod(ObjectByName("AN26"),

Next comes the method. If we were to use the method GoHome() it would
look like this.

LY
_ObjectCallMethod(ObjectByName("AN26"),”GoHome”)

The method Navigate2() has additional parameters so those must be added

N
into the function syntax.

O
_ObjectCallMethod(ObjectByName("An26"), "Navigate2",
sURL, "", "", "", "")

se
The four optional parameters are added in as empty strings.
lU
CitectSCADA can pass one or more variables as parameters to a method, and
the object may write back to those variables if it wishes. For that reason, the
parameters may not be the return value of other Cicode functions, arrays, or
hard-coded values.
na

Incorrect: _ObjectCallMethod(hObject, “Date”, Date(1));


r

Correct: _ObjectCallMethod(hObject, “Date”, sDate);


te

9 Hints & Tips:


In

You must specify all arguments, even optional ones, when calling ActiveX methods
from Cicode.
ct
ite

Continued on next page


C

Advanced Configuration Concepts Manual Revision 2-INT 8-37


Using ActiveX Methods, Continued

Exercise 8-8

Step Action
1 Use Cicode ActiveX functions to add navigation to your Web
Browser.
i. Open a new Cicode file and save it as Web_Browser.ci.
ii. Create a new function called WebInitialise().

LY
FUNCTION
WebInitialise()

N
iii. Use the Input() Cicode function to allow a user to input a web
address into the String tag URL.

O
URL=Input("URL ADDRESS","Type the Address"," ");

iv.

se
The Cicode function used to call a method is
_ObjectCallMethod(hObject, sMethod, vParameters). This
function requires the name of the Object (hObject) and the
Method (sMethod) that will be used. Return to the page
lU
gr_WebBrowser and open the properties of the Web Browser
object. Open the Access (Indentification) tab. There you will
find the Object Name. In this case it is AN26.
na

v. The method that is used to take your browser to a URL is


Navigate2. The tool OLE View will allow you to see the syntax
used in this method.
r
te
In
ct
ite
C

Continued on next page

8-38 CitectHMI/SCADA Version 6.00 August 2005


Using ActiveX Methods, Continued

Exercise 8-8 (continued)

Step Action
vi. Add the function _ObjectCallMethod() to the next line in your
function WebInitialise(). You will need to use the Cicode
function ObjectByName(sName) to pass the name of the
object to the function.

LY
_ObjectCallMethod(ObjectByName("AN26"),
"Navigate2", URL, "", "", "", "")

vii. END the function. The complete function should look like this.

N
O
FUNCTION
WebInitialise()
URL =Input("URL ADDRESS", "Type the
Address", " ");
se
_ObjectCallMethod(ObjectByName("An26"),
"Navigate2", URL, "", "", "", "")
lU
END

viii. Save your file and compile.


na

2 Add an Address Bar to your web browser.


i. Draw a rectangle above the Web Browser object.
ii. Add the WebInitialise() function to the Input (Touch) Up
r

command of the rectangle.


te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 8-39


Using ActiveX Methods, Continued

Exercise 8-8 (continued)

Step Action
iii. Add a text object inside the rectangle to display the URL.

LY
N
O
se
lU
na

iv. Save the page and compile.


r

v. Run the project and test your web browser.


te


In

Continued on next page


ct
ite
C

8-40 CitectHMI/SCADA Version 6.00 August 2005


Using ActiveX Methods, Continued

Exercise 8-9

Step Action
1 Add more navigation functionality to your web browser.
i. Return to your Cicode file Web_Browser.ci.
ii. Create these four new functions.

Function Command

LY
Name
GoBackward() _ObjectCallMethod(ObjectByName("AN26"),
"GoBack");

N
GoForward() _ObjectCallMethod(ObjectByName("AN26"),
"GoForward");

O
GoHome() _ObjectCallMethod(ObjectByName("AN26"),
"GoHome");
Refresh()

se
_ObjectCallMethod(ObjectByName("AN26"),
"Refresh");
lU
2 Add four navigation buttons to your web browser.
i. Add four buttons to your page gr_WebBrowser. Place the
buttons above the address bar.
na

Appearance Input (Touch) Access (General)


(General) Symbol Up Command Tool Tip
r

icons.back Back
te

GoBackward()
icons.forward GoForward() Forward
In

icons.home GoHome() Home Page


icons.refresh Refresh() Refresh
ct

ii. Save the page and compile your project.


ite

iii. Run the project and test your Web Browser.


C

Advanced Configuration Concepts Manual Revision 2-INT 8-41


Events

Calling Cicode Events define what Cicode functions an object may call. The object will have
Functions a set of predefined events such as the table below from the MS Calendar
Control.

Event Description
AfterUpdate Occurs after the user moves to a new date in the
Calendar control and after the calendar has been
refreshed.

LY
BeforeUpdate Occurs after the user moves to a new date in the
Calendar control but before the calendar has been
refreshed.

N
Click Occurs when the user clicks a date in the Calendar
control.

O
DblClick Occurs when the user double-clicks a date in the
Calendar control.
KeyDown Occurs when the user presses a key while the Calendar

KeyPress se
control has the focus.
Occurs when the user presses and releases an ANSI key
while the Calendar control has the focus.
lU
KeyUp Occurs when the user releases a key while the Calendar
control has the focus.
NewMonth Occurs when the Calendar control date changes to a new
na

month.
NewYear Occurs when the Calendar control date changes to a new
year.
r
te

Continued on next page


In
ct
ite
C

8-42 CitectHMI/SCADA Version 6.00 August 2005


Events, Continued

Event Class Since two different objects (or two instances of the same object) could have
events with the same name, every object has a unique Event Class name. This
is simply a prefix added to any events from that instance of the object.

Objects created in the Graphics Builder will have an event class name defined
automatically as shown below:

LY
N
O
When the user clicks on the calendar (activating the Click event), it would try
to call a Cicode function called Calendar_AN35_Click(). In this example,

se
“Calendar” is the page name. The last “_” is added automatically after the
event class name.
lU
When instantiating an object through Cicode, the event class must be
specified as an argument to the CreateControlObject() function.
na

9 Hints and Tips


All events pass the object’s handle as the first parameter to the Cicode function, for
r

example, Calendar_AN35_Click(OBJECT hThis). Additional parameters may be


te

passed after that.


The MS Calendar KeyDown event passes the parameters iKeyCode and
In

iShiftState after the object handle. This Cicode event function declaration would
be:
Calendar_AN35_KeyDown(OBJECT hThis, INT iKeyCode, INT
ct

iShiftState)

Check the object’s documentation for details.


ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 8-43


Events, Continued

Exercise 8-10

Step Action
1 Create a new event that will prevent users from navigating
away from the company website.
i. Check the Event Class of the ActiveX object on your Web
Browser page.

LY
N
O
ii.
se
Open the Cicode file Web_Browser.ci. Add a function for this
new event. The name of the function combines the event class
name, gr_WebBr_AN26, and the BeforeNavigate2 event.
lU
FUNCTION
gr_WebBr_AN26_BeforeNavigate2(OBJECT hThis,
na

OBJECT hDisp, STRING sURL, INT iFlags,


STRING sTargetFrameName, STRING sPostData,
STRING sHeaders, INT iCancel)
r
te

iii. Add an IF statement that will return to browser to the


company home page if the URL does not contain characters
from the company website.
In

IF (StrSearch(0, sURL, "citect.com") = -1) THEN


ct

_ObjectCallMethod(hThis, "Navigate2",
"www.citect.com", "", "", "", "");
ite

iv. Add a warning indicating that only the company website is


allowed. Then END the IF statement and the FUNCTION.
C

Message("Warning", "Only Citect.com is allowed",


16);
END
END

v. Save the file and compile your project.

Continued on next page

8-44 CitectHMI/SCADA Version 6.00 August 2005


Events, Continued

Exercise 8-10 (continued)

Step Action
2 Check that your new event will function as expected.
i. Run the project and type a URL into the browser that will take
you away from the company website.

LY
N
O
se
lU
r na
te
In


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 8-45


LY
N
O
se
lU
nar
te
In
ct
ite
C

8-46 CitectHMI/SCADA Version 6.00 August 2005


Chapter 9: Kernel and Debugging
Overview

Introduction As CitectSCADA was originally designed as a true Multi-Threaded, Multi-


Tasking system, it was found that as the system got more and more
complicated the programmers needed a way to observe what their changes
were actually doing within the program at run time without having any
performance impact on the running version of CitectSCADA. Since
CitectSCADA was handling all of the tasks it needed in order to operate, it

LY
was decided to build a window into the running instance of CitectSCADA.
This was how the Kernel was developed. It was called a Kernel because of the
similarities between CitectSCADA and a real operating system.

N
O
Contents This chapter contains the following topics:

Topic See Page


¾ The Citect Kernel
¾ Security and the Kernel se 9-2
9-5
lU
¾ Foreground and Background Tasks 9-8
¾ Tasks and 9-8
Pre-emption
na

9-12
¾ Performing Diagnostics 9-12
¾ Page Table Cicode 9-14
r

¾ Probe Command
te

9-18
¾ Page Table Stats 9-18
In

¾ Cycle and Execution Time 9-20


¾ The TaskNew() Function
9-23
ct

¾ Thread Window
9-25
¾ Global Variable Window
ite

9-27
¾ Stack Window
C
The Citect Kernel

Opening the To use the Kernel you must first have access to it. To do this there are a few
Kernel different ways. The two main ways are by editing your CITECT.INI file to
allow access to the Kernel. One can be done through the Computer Setup
Wizard and one must be done manually or through the help.

¾ To open the Citect kernel


Open the Citect.ini file and add this parameter:

LY
[DEBUG]
Menu=1

N
This will place an entry for the Kernel on the Control Menu that you get when
single clicking on the left of the title bar or by pressing Alt-Space.

O
or

Add this parameter

[Debug]
se
lU
Kernel=1

This will show the Kernel as you are compiling and also when you are
na

starting up CitectSCADA. As most problems with CitectSCADA are to do


with something not communicating or not connecting properly, the only way
to see exactly what happens and when is to be viewing the Kernel as
r

CitectSCADA starts up.


te

or
In

The third way to gain access to the Kernel is now available in projects that are
created using the new XP Style template. The Admin page in the
ct

CSV_Include project allows users with global privilege level 8 to open the
Kernel.
ite
C

Continued on next page

9-2 CitectHMI/SCADA Version 6.00 August 2005


The Citect Kernel, Continued

Exercise 9-1

Step Action
1 Start the Kernel by enabling the Kernel command on the
Control Menu.
i. Go to Citect Explorer and start the Computer Setup Wizard’s
custom setup.
ii. Click on Next to scroll through the pages until you reach the

LY
Security Setup.

N
O
se
lU
r na

Tick the Kernel on Menu box. Click Next.


te

iii. On the next page enable the Alt-Space command. Scroll


through to the end of the Custom Setup.
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 9-3


The Citect Kernel, Continued

Exercise 9-1 (continued)

Step Action
2 Enable the Kernel by using the [Debug] parameter.
i. Open the Citect.ini file
ii. Add this parameter

LY
[DEBUG]
Kernel = 1

N
2 View the Kernel using both of these methods.
i. Run your project. When the [Debug] Kernel=1 option is

O
enabled the Kernel will start as soon as the project goes into
runtime. This will allow you to see any communication
problems as the system is starting.
ii.
iii.
Close the Kernel

se
To start the Kernel using the Control Menu either
lU
Click on the top left hand corner of a CitectSCADA runtime
page
or
na

Press ALT - SPACE


r

iv. Select Kernel from the drop-down menu.


te


In
ct
ite
C

9-4 CitectHMI/SCADA Version 6.00 August 2005


Security and the Kernel

Kernel Access It is important to restrict access to the Kernel, because once you are in the
Kernel, you can execute any Cicode function with no privilege restrictions.
You (or anyone using the Kernel) have total control of CitectHMI/SCADA
(and subsequently your plant and equipment). Therefore in a normal runtime
environment you would not enable the Kernel menu command or configure
the Kernel to start up automatically.

If you are using a project that is based on the new XP_Style templates you

LY
may gain access to the Kernel through the Admin page. The Admin page in
the CSV_Include project allows users with global privilege level 8 to open the
Kernel.

N
O
se
lU
na

If you are not using the XP_Style templates the function DspKernel(1) will
open the Kernel from a button or system command.

Continued on next page


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 9-5


Security and the Kernel, Continued

Exercise 9-2

Step Action
1 Add a button to a new page to open the Kernel.
i. Open the page called gr_Debug.
ii. Open the page !UtilityMenu and change the properties of the
third button. Use these settings.

LY
Appearance Input (Touch) Access
(General) Up Command (General)
Symbol Tool Tip

N
icons.spanner WinFree(); Debug Page
WinGoto(0);

O
PageDisplay("gr_Debug")

iii. Return to your page gr_Debug and place a button on the page

se
to open the Kernel. Use these settings.
lU
Appearance (General) icons.Ctkernel
Symbol
Input (Touch) DspKernel(1)
na

Up Command
Access (General) Citect Kernel
Tool Tip
r

Access (General) 8
te

Privilege Level
Access (Disable) 9
Disable on insufficient area or privilege
In

Access (Disable) Embossed


Disable style
ct

iv. Save the page.


ite

Continued on next page


C

9-6 CitectHMI/SCADA Version 6.00 August 2005


Security and the Kernel, Continued

Exercise 9-2 (continued)

Step Action
2 Open the Citect Kernel from the page gr_Debug.
i. Run your project.
ii. Log in to your project as the user Engineer.
iii. Open the page gr_Debug.

LY
iv. Use the button to open the Citect Kernel.
v. The General Statistics page provides general operating
information about the current CitectSCADA Display Client.
Open this page by choosing View | General from the menu.

N
vi. Exact up time, CPU index and usage numbers, read and write
statistics, key information, error counts and more are found on

O
this page. Notice that the current CPU Usage displayed on this
screen is 0%.

se
lU
r na
te
In
ct
ite
C

vii. Shutdown your project.

Advanced Configuration Concepts Manual Revision 2-INT 9-7


Foreground and Background Tasks

Tasks and Cicode tasks (or threads) can be executing in either foreground or background
Pre-emption mode. A foreground task is one that displays and controls animations on your
graphics pages. Any expression (not a command) entered in a property field
(i.e. Text, Rectangle, Button, etc.) is executed as a foreground task. All other
commands and expressions are executed in background mode.

The difference between a background and foreground task is that a


background task can be pre-empted, that is, if system resources are limited,

LY
the task (e.g. the printing of a report) can pause to allow a more critical task to
be executed. When the critical task is completed (or when system resources
become available) the original task resumes. Foreground tasks are considered

N
critical and can never be pre-empted.

O
Continued on next page

se
lU
r na
te
In
ct
ite
C

9-8 CitectHMI/SCADA Version 6.00 August 2005


Foreground and Background Tasks, Continued

Exercise 9-3 Test the effects of using functions as foreground and background tasks.

Step Action
1 Create a function that will consume CPU resources.
i. Open the Cicode Editor and create a new Cicode file called
Debug.ci.
ii. Write this function.

LY
FUNCTION
MyBadTask()
WHILE TRUE DO

N
Counter = Counter + 1;
END

O
END

iii. Save the file and compile.


2
se
Call this function as a foreground task using a Cicode Object.
i. Return to your gr_Debug page.
lU
ii. Place a Cicode object on the page. Add the MyBadTask()
function to the Cicode (General) Command of the Cicode
Object.
r na
te
In
ct
ite
C

iii. Place a Numeric Object underneath the Kernel button to


display the value of the tag Counter.
iv. Save the page and compile.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 9-9


Foreground and Background Tasks, Continued

Exercise 9-3 (continued)

Step Action
3 Use the Kernel to view the effect of calling this function on
your system.
i. Run your project and open the page gr_Debug. The function
will be called as soon as you enter the page because it was
called from a Cicode Object.

LY
ii. As soon as the function is called the number will start
incrementing without a pause.

N
O
se
lU
As a result of this the CPU Usage will climb to 100%. You will
notice that your whole system will slow down as you try to
na

move the pointer and open windows.


r
te
In

A Hardware alarm will be triggered and eventually


CitectSCADA will kill the task because it never ends.
ct
ite

iii. Shutdown the project.


C

Continued on next page

9-10 CitectHMI/SCADA Version 6.00 August 2005


Foreground and Background Tasks, Continued

Exercise 9-3 (continued)

Step Action
4 Create a button to implement the function MyBadTask().
i. Delete the Cicode object from your page.
ii. Draw a button on the page. Use these settings.

LY
Appearance (General) Input (Touch)
Text Up Command
Start Bad Task (Direct) MyBadTask()

N
5 Run the function MyBadTask() as a background task.

O
i. Run the project and open the page gr_Debug.
ii. Start the Kernel and open Page General.
iii.

se
Start the task from the button Start Bad Task (Direct). Notice
that the CPU Usage immediately climbs to 100%. However,
you should notice that this time the system is not as sluggish
when you move the mouse around the screen and change
lU
windows. This is because it is not a foreground task as it was
when called from a Cicode object. Background tasks may be
pre-empted.
na


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 9-11


Page Table Cicode

Performing The CitectHMI/SCADA Kernel provides a window into the core of


Diagnostics CitectHMI/SCADA. By using the Kernel, you can perform low-level
diagnostic and debugging operations, for runtime analysis of your
CitectHMI/SCADA system. You can use it to display all the low level data
structures, run time databases, statistics, debug traces, network traffic, I/O
Device traffic and other useful information. You can also call any in-built
Cicode function or user-written Cicode function from the Kernel.

LY
Page Table Page Table Cicode is a window that contains a list of all Cicode tasks
Cicode currently running. It contains the task name, handle and running state, as well

N
as some statistics. CPU_Time is the total time that the task has run for - it is
incremented each time the task runs. The CPU is the percentage of total

O
available CPU that the task is using (fast tasks often have 00 CPU)

Continued on next page

se
lU
r na
te
In
ct
ite
C

9-12 CitectHMI/SCADA Version 6.00 August 2005


Page Table Cicode, Continued

Exercise 9-4

Step Action
1 Use the Kernel window Page Table Cicode to obtain information
about your running tasks.
i. Run your project and open the page gr_Debug.
ii. Execute the function MyBadTask() from the button.
iii. Start the Kernel then type this command into the Main

LY
window.

Page table cicode <enter>

N
iv. This is the window that will display all your current Cicode

O
tasks.

se
lU
na

v. This current task is labelled Command because it was called


r

from the Up command of a button.


te

vi. The Task Handle (HND) is 1. Knowing this we can kill the
task. Choose View | Cicode form the Kernel menu to open a
Cicode window. This window will allow you to execute any
In

Cicode function. Type this command into the Cicode window.


This will stop the task.
ct

TaskKill(1) <enter>
ite

vii. Return to the Page Table Cicode window. You will find that the
task is no longer running.
viii. Shutdown the project.
C

Advanced Configuration Concepts Manual Revision 2-INT 9-13


Probe Command

This command opens a child window that displays read and write requests to
all I/O Devices and displays the responses from the I/O Devices. The child
window displays exactly what CitectHMI/SCADA is requesting from the I/O
Devices and the speed of the response.

The child window shows each request that CitectHMI/SCADA is making to


the I/O Server. A request can be either for I/O Device data, or to write data to
the I/O Device. The response from the I/O Server is also shown. The

LY
displayed requests are from the local client to the I/O Server only. If this
CitectHMI/SCADA computer is an I/O Server, the Probe window only
displays the local Client’s requests, and not those from remote clients.

N
Continued on next page

O
se
lU
r na
te
In
ct
ite
C

9-14 CitectHMI/SCADA Version 6.00 August 2005


Probe Command, Continued

Exercise 9-5

Step Action
1 Create a new task that will increment the counter but will not
consume CPU resources.
i. Open your Cicode file Debug.ci.
ii. Make a copy your MyBadTask() function underneath the
original. Change the name of the function to MyGoodTask()

LY
and add a Sleep(1) command into the WHILE loop.

FUNCTION

N
MyGoodTask()
WHILE TRUE DO

O
Counter = Counter + 1;
Sleep(1);
END
END

9 Hints & Tips:


se
lU
If you want to pause for less than 1 second, use the SleepMS()
function and specify the time in milliseconds.
na

Note: Sleep() and SleepMS() are for reducing CPU usage. They
are not designed to be precise timers. Use SysTime() or
r

TimeCurrent() to check for elapsed time.


te
In

iii. Save the file and compile.


iv. Add a button to your page gr_Debug. Use these settings.
ct

Appearance (General) Input (Touch)


ite

Text Up Command
Start Good Task (Direct) MyGoodTask()
C

v. Save the page and compile.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 9-15


Probe Command, Continued

Exercise 9-5 (continued)

Step Action
2 Run your project to check the effect of the Sleep(1) command.
i. Run your project and execute the function MyBadTask().
ii. Start the Kernel and type this command into the Main window.

LY
Probe <enter>

This will open the Probe window.

N
O
se
lU
r na
te

You can see from this window that the function is only
In

displaying write requests as there is no time for read requests.


iii. Kill this task using the TaskKill() function in the Cicode
window.
ct
ite

Continued on next page


C

9-16 CitectHMI/SCADA Version 6.00 August 2005


Probe Command, Continued

Exercise 9-5 (continued)

Step Action
iv. Execute the function MyGoodTask().
v. Open Page General and look at the CPU Usage.

LY
N
The CPU Usage is down to 0% because the Sleep(1) command
allows time for other tasks.

O
vi. Open the Probe window. You can see that there is now time
for Read requests.

se
lU
r na
te
In
ct
ite


C

Advanced Configuration Concepts Manual Revision 2-INT 9-17


Page Table Stats

Cycle and This very useful table contains the cycle and execution times of every task
Execution Time that is running in CitectHMI/SCADA. The Execution Time is the time taken
for the entire task to run. The Cycle time is the time between when a task
starts and when it starts again. The CPU is the percentage of total available
CPU that the task is using (fast tasks often have 00 CPU).

The Citect 0 entry is the display task (graphics page updates). That is the
total time taken for the Client to request data from the I/O Server, the I/O

LY
Server to get the data and sent it back to the Client, and the Client to update
the display.

N
Note: Citect 0 corresponds to the display task for the main window.

O
Citect 1 for the first child window, Citect 2 for the third, and so on.

se
The CodeX entries correspond to Cicode tasks, where X is the handle of the
task. You can find out which task corresponds to which handle by viewing
Page Table Cicode.
lU
Continued on next page
r na
te
In
ct
ite
C

9-18 CitectHMI/SCADA Version 6.00 August 2005


Page Table Stats, Continued

Exercise 9-6

Step Action
1 View the Cicode tasks from the window Page Table Stats.
i. Run your project and open the page gr_Debug.
ii. Execute the function MyGoodTask() several times.
iii. Execute the function MyBadTask() once only.

LY
iv. Start the Kernel and use the Main window to open the window
Page Table Stats.

N
O
se
lU
r na
te
In

v. You can see from this window that the task Code 2 is the one
that is consuming CPU time.
ct

9 Hints & Tips:


ite

Hold down the spacebar in the kernel to force the statistics to update at
a much faster rate.
C

Advanced Configuration Concepts Manual Revision 2-INT 9-19


The TaskNew() Function

The The TaskNew() function creates a new Cicode task and returns the task
Advantages of handle. You pass the Name of the function (that creates the task) as a string,
TaskNew() not as the function tag, and pass all the arguments for that function as a string.
After the task is created, it runs in parallel to the calling task. The new task
will run forever unless it returns from the function or is killed by another task.

In terms of performance calling a function by using TaskNew() makes very


little difference. However, it has quite a few other advantages. TaskNew()

LY
gives you more control over how the task is run and for debugging your code
it will identify the function in the Kernel window Page Table Cicode instead
of using the generic label Command. TaskNew() allows one function to start

N
other lengthy functions or infinite loops without stopping the first function. It
is also used to call blocking functions from form callback functions and from

O
Alarm category actions.

Note: There is no way to get the return value from a function that is
started with TaskNew().
se
lU

¾ To use TaskNew()
na

How to

All arguments of the function must be combined into one string.


r
te

Example –
In

TaskNew("BackgroundMonitor", "1,5,28", 0);

If an argument is a string it must be enclosed in quotation marks. In order for


ct

the compiler to differentiate between those quotation marks and the beginning
and end quotes for sArg, prefix them with a carat symbol.
ite

Example –
C

The expression,

Message("Title", "Prompt", 0)

would become,

TaskNew("Message", "^"Title^", ^"Prompt^", 0", 0);

Continued on next page

9-20 CitectHMI/SCADA Version 6.00 August 2005


The TaskNew() Function, Continued

Passing It is possible to pass variable values to TaskNew() by converting them to


Variables in strings and concatenating them to sArg.
TaskNew()
Example –

TaskNew("LogValue", "27, " + IntToStr(Motor1_PV)


+ ", 0", 0);

LY
See Also:
For further information about the TaskNew() function, see Citect Help Topics -
TaskNew Cicode function. Using the Mode argument you can force tags to be
read before the function starts, only run one copy of the function, or force the

N
function to close when you change pages.

O
9 Hints & Tips:

se
Some functions in Citect, like DevOpen(), are actually labels defined in the Include
project. If TaskNew() returns -1 because it cannot find the function, use the actual
name as shown in the Label definition in the Include project.
lU
na

Note: TaskNew cannot be used to call PRIVATE functions.


r
te

Continued on next page


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 9-21


The TaskNew() Function, Continued

Exercise 9-7

Step Action
1 Call the two functions MyBadTask() and MyGoodTask() using
TaskNew().
i. Create two more buttons on your page. Use these settings.

LY
Appearance (General) Input (Touch)
Text Up Command
Start Bad Task (Task New) TaskNew("MyBadTask",
"",0)

N
Start Good Task (Task New) TaskNew("MyGoodTask",
"",0)

O
ii. Save the page and compile the project.
iii.
iv.
v.
se
Run the project and open the page gr_Debug.
Execute the functions using all four buttons.
Start the Kernel and open the Page Table Cicode window.
lU
r na
te
In

By using TaskNew() the name of the function is clearly


displayed in this window. The advantage of this is that you
can now know which function is causing a problem in your
ct

runtime system.
ite


C

9-22 CitectHMI/SCADA Version 6.00 August 2005


Thread Window

Debugging Some projects require the development of complex Cicode to implement


advanced custom functionality. One of the disadvantages of complex code is
that if not constructed properly, it is prone to errors. To help locate any
errors, the Cicode Editor can switch into debug mode. You can then use it to
analyse running Cicode. You can turn debugging on and off as required, but
CitectHMI/SCADA must be running for the debugger to work. During
debugging you can open several different windows to display information
about the Cicode system.

LY
Thread The information displayed in this window is very similar to the information in
Window

N
the Kernel Window Page Table Cicode.
Information

O
The Thread Window has the following fields:

¾ Name - The name of the Cicode thread.


¾
¾
Hnd - The Cicode thread handle.
se
CPU - The amount of CPU the Cicode thread is currently using.
lU
¾ State - The state of the Cicode thread.
¾ CPU_Time - The total amount of CPU time that the Cicode thread
has consumed.
na

Continued on next page


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 9-23


Thread Window, Continued

Exercise 9-8

Step Action
1 Use the Threads window in the Cicode Editor to identify your
functions.
i. Run your project and open the page gr_Debug.
ii. Start the functions from all four buttons.
iii. Open the Cicode Editor.

LY
iv. Start the Debugger by clicking on the Debug button or
choosing Debug | Start Debugging from the menu.

N
v. Choose View | Threads Window from the menu. The Threads
Window will open and display the running threads.

O
se
lU
vi. Notice that the threads that were not called by the function
TaskNew() are labelled Command just as they were in the
na

Kernel Window Page Table Cicode. However, the Threads


window has an advantage over the Kernel. Double click one of
the Command threads.
r
te
In
ct
ite

vii. The Debugger will halt the thread, open the Cicode file, and an
arrow will point to the next line in the code to be executed.
C

9-24 CitectHMI/SCADA Version 6.00 August 2005


Global Variable Window

Exercise 9-9 The Global Variable Window lists the names and values of all global
variables processed to date in the running project during debugging. A global
variable is added to the list when it is first assigned a value. Each time the
Global variable is processed, its value will be updated in the Global Variable
Window.

9 Hints & Tips:

LY
The Globals window also shows module variables and variable tags.

N
Step Action
1 Use the Globals window in the Cicode Editor to check that the

O
web page is being passed to the variables from your Input
window.
i. Go to the Cicode Editor and open the file Web_Browser.ci.
ii.
iii. se
Start the Debugger. This will start Citect Runtime.
Open the page gr_WebBrowser.
lU
iv. Left mouse click on the margin to place a Breakpoint on the
Input line.
r na
te

v. Choose View | Globals Window from the menu.


In

vi. Return to the page gr_WebBrowser and click on the address


bar to execute the WebInitialise() function.
vii. The Debugger will take you to the breakpoint and indicate the
line to be executed with a yellow arrow.
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 9-25


Global Variable Window, Continued

Exercise 9-9 (continued)

Step Action
1 viii. Click the Step Into button to advance one line of code.
(cont.)

LY
ix. The system is now waiting for some User input. Return to the
page gr_WebBrowser. Type an address into the Input box and

N
click OK.

O
se
lU
x. Return to the Debugger and step into the next line of code.
The Globals window will indicate that the value has been
na

passed to the variable tag URL.


r
te
In
ct


ite
C

9-26 CitectHMI/SCADA Version 6.00 August 2005


Stack Window

Debugging This window displays the Call Stack Window, which lists the stack values of
Using the Stack the current thread. The stack consists of the functions called (including the
Window arguments), any local variables used in the functions, and return values. This
is especially useful during debugging to trace the origin of the calling
procedures.

Note: A stack is a section of memory that is used to store temporary


information. For example, when you call a Cicode function, the

LY
variables used inside the function exist only as long as the function
runs.

N
To view the values of arguments and variables in a procedure, place a
breakpoint within the procedure under watch. When that breakpoint is

O
reached, the Stack Window will display the current call stack of the procedure
containing the breakpoint. The values of the stack are updated as the values
change.

se Continued on next page


lU
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 9-27


Stack Window, Continued

Exercise 9-10

Step Action
1 Change the function IndControl() so that it will cause a
Hardware alarm when executed.
i. Open the Cicode file Popup.ci.
ii. Go to the function IndControl() and remark the line of the
WinNewAt() function.

LY
iii. Replace the WinNewAt() function with AssWin() as shown
below.

N
O
iv.
v.
se
Save your page and compile then run your project.
Open the page gr_Past and click on the Past_Homog_Valve
lU
symbol set.
r na
te
In

vi. As soon as you click on the symbol set a Hardware alarm will
be triggered.
ct
ite
C

Continued on next page

9-28 CitectHMI/SCADA Version 6.00 August 2005


Stack Window, Continued

Exercise 9-10 (continued)

Step Action
2 Use the Stack window to find the cause of the Hardware alarm.
i. Place a Breakpoint at the first statement in the IndControl()
function.

LY
N
O
ii.
iii.
se
Start the Debugger and open the Stack Window.
Execute the function again. The Debugger will pause at the
Breakpoint and the Stack window will display the function, its
arguments and the three local variables that have been defined
lU
so far.
r na
te
In

iv. Step through the function line by line and watch as each line is
executed. The stack window will display the values as they are
added into the variables.
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 9-29


Stack Window, Continued

Exercise 9-10 (continued)

Step Action
2 v. When the AssWin() function is executed the Debugger will
(cont.) open the correct Cicode file and step into the AssWin()
function.

LY
N
O
As the AssWin() function is executed the Stacks Window
displays the function and its variables. You can see from this
window where the problem is located. The third tag name
does not exist.

se
lU
r na

vi. Next the Debugger steps into the function AssVarTags(). This
function assigns the variable tags to the popup page.
te
In
ct
ite
C

Continued on next page

9-30 CitectHMI/SCADA Version 6.00 August 2005


Stack Window, Continued

Exercise 9-10 (continued)

Step Action
2 The Stack window continues to display all the calling
(cont.) procedures and the variables.

LY
N
vii. When the Debugger calls the third argument for that function
an error is displayed because the variable tag name Past_

O
does not exist.

se
lU
na

viii. Change the code back to the original line using the function
WinNewAt().
r

ix. Restart your project and debug the function again.


te


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 9-31


LY
N
O
se
lU
nar
te
In
ct
ite
C

9-32 CitectHMI/SCADA Version 6.00 August 2005


Chapter 10: Process Analyst
Overview

Introduction The CitectSCADA Process Analyst is an ActiveX control designed to allow


operators to simultaneously view trend data from a CitectSCADA trend
server, and alarm tag data from a CitectSCADA alarm server. The Process
Analyst provides a visual means to analyse and compare trend data (real-time
and historical) in a more intuitive manner than CitectSCADA's trend
templates.

LY
N
O
se
lU
r na
te

Contents This chapter contains the following topics:


In

Topic See Page


¾ Process Analyst Active X Control 10-2
¾ Properties of the Process Analyst 10-5
ct

¾ Toolbars 10-6
ite

¾ Pens 10-8
¾ Interacting with the Process Analyst 10-18
C

¾ Configuring Pens 10-25


¾ Views 10-40
¾ Object View 10-45
¾ Customising Toolbars 10-49
¾ Cursor and Cursor Labels 10-53
¾ Security and Permissions 10-57
Process Analyst Active X Control

Overview The Process Analyst is an Active X control that may be placed onto any
CitectSCADA graphics page. In its simplest form, no other configuration is
needed than to add the Process Analyst Active X control to a CitectSCADA
graphics page.

Adding the ¾ To add a new Process Analyst Active X Control:


Process Analyst

LY
to a Page
Open the Citect Graphics Builder, choose Edit | Insert Process Analyst:
or

N
Click the Process Analyst button in the Graphics Builder Toolbox.

O
se
lU
r na
te

Continued on next page


In
ct
ite
C

10-2 CitectHMI/SCADA Version 6.00 August 2005


Process Analyst Active X Control, Continued

Exercise 10-1 Add a Process analyst Active X Control to a new page in your project to view
Trend and Alarm data.

Step Action
1 Create a new page in your project.
i. Return to the Citect Graphics Builder.
ii. Choose File | New… from the menu.
iii. Create a new page based on the Normal Training template.

LY
iv. Save the page as Analyst.
2 Add a Process Analyst Active X Control to the Page.

N
i. Click the Process Analyst button on the Graphics Builder
Toolbox.

O
se
lU
r na
te

Continued on next page


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-3


Process Analyst Active X Control, Continued

Exercise 10-1 (continued)

Step Action
ii. Use the resize handles to enlarge the object so that it fills the
page.

LY
N
O
se
lU
r na

3 Add an icon to the Normal template next to the Alarm icons to


te

display the Analyst page.


4 Save the page and compile your project.
In


ct
ite
C

10-4 CitectHMI/SCADA Version 6.00 August 2005


Properties of the Process Analyst

Process Analyst The Process Analyst is a new feature that is included from CitectSCADA
Display version 6.00 onwards. It is capable of displaying all trend types and alarm
data in the same window. Users can configure certain properties of the
Process Analyst control during design time.

The Process Analyst is a display tool. It uses the same information provided
by the existing trend and alarm servers that the trend and alarm pages use.
There is no extra trend or alarm configuration needed other than creating

LY
trend and alarm tags.

N
Cursor Labels

O
Main Toolbar Date/Time Axis Cursor

se
lU
na

Pens
r
te
In
ct
ite

Navigation Toolbar
C

Object Toolbar

Advanced Configuration Concepts Manual Revision 2-INT 10-5


Toolbars

Overview The Process Analyst has two toolbars, the Main Toolbar and the Navigation
Toolbar. Users may customise the toolbars to display their most commonly
used commands and controls.

Main Toolbar The Process Analyst Main Toolbar is located above the top pane. It contains
commands for performing general operations in the Process Analyst, such as
opening and saving views, printing reports, adding and deleting pens, and

LY
changing the cursor display.

N
O
Main Toolbar The table below describes the items that are included on the Main Toolbar by
Items default:

Item
Load View
se
Description
Loads a saved view from file.
lU
Save View Saves a view to file.
Print Displays the standard Windows Print dialog box
na

for printing trend reports.


Copy to Clipboard Copies visible pens to the Windows Clipboard.
r

Export to File Exports visible pens to an Excel-compatible file.


te

Add Pen Displays the Add New Pen(s) dialog box for
adding a pen.
In

Remove Pen Deletes the currently selected pen from the trend
display.
Lock/Unlock Pens Toggles the locking of pens.
ct

Show/Hide Points Toggles the display of points representing where


sample data was recorded in the archive.
ite

Show/Hide Toggles the display of cursors.


Cursors
C

Show/Hide Cursor Toggles the display of cursor labels.


Labels
Toggle Object Toggles the display of the Object View.
View
Show Properties Displays the Properties dialog box for configuring
the Process Analyst control.
Help Displays the Process Analyst online Help.

Continued on next page

10-6 CitectHMI/SCADA Version 6.00 August 2005


Toolbars, Continued

Navigation Contains commands to allow an Operator to travel forward or backward


Toolbar through trends, as well as other navigation-related tasks.

Navigation The table below describes the items that are included on the Navigation
Toolbar Items Toolbar by default:

LY
Item Description
Start Time Specifies a start time and an end

N
End Time time for the trend display by using
the date/time pickers. The start time

O
picker is located on the left-hand
side of the navigation toolbar, the
end time picker on the right.
Time Span
se The time span of the trend display is
the difference between the start time
lU
and the end time.
Toggle Maintains the current time span
SpanLock when the start time and/or end time
picker changed.
na

Navigation Allow an Operator to navigate


Controls backwards or forwards through time
Back One Moves back one time span
r

Span
te

Back Half a Moves back half a time span


Span
In

Forward Half Moves forward half a time span


a Span
Forward One Moves forward one time span
ct

Span
Toggle Auto- When Autoscroll is turned on, as
ite

Scrolling time passes the position in time of


all pens moves by the same amount
to keep pace
C

Advanced Configuration Concepts Manual Revision 2-INT 10-7


Pens

Overview Process Analyst pens are drawn against time. Each pen has its own coloured
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.

LY
N
O
Unlimited Pens
se
The Trend pages limit the number of pens that may be displayed to eight per
graph. In Process Analyst the number of pens in limited only by the power of
your graphics card.
lU
r na
te
In
ct
ite
C

10-8 CitectHMI/SCADA Version 6.00 August 2005


Displaying Pens in the Process Analyst

Overview Process Analyst pens are drawn against time. Each pen has its own coloured
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. The trend and alarm tags are
added to the Process Analyst during runtime. Pens can be added to (or
removed from) any pane.

LY
Adding Pens Pens are added by using the Add New Pen(s) dialog. This dialog allows the

N
operator to query trend and alarm servers for any trend or alarm matching
their specified filter. An operator can choose pens and configure their types

O
and names. The trends can then be added to the Process Control for analysis.

¾ To add new pens to the Process Analyst:

Click the Add Pen


Pen(s) dialog.
se
button on the Main Toolbar and use the Add New
lU
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-9


Displaying Pens in the Process Analyst, Continued

Exercise 10-2 Add a Trend pen and an Alarm pen to your Process Analyst.

Step Action
1 Run your project and open the page Analyst.
2 Click the Add Pens button.

LY
N
3 Search for the available Trends.
i. The search Type defaults to Trends. Click the Search button.

O
se
lU
ii. All available trends will populate the Search results window.
r na
te
In
ct

3 Change the Pen name: to Tag.


ite
C

Continued on next page

10-10 CitectHMI/SCADA Version 6.00 August 2005


Displaying Pens in the Process Analyst, Continued

Exercise 10-2 (continued)

Step Action
4 Select the trend tag that you wish to display.
i. Scroll to the end of the Search results and add the trend tag
P1_P displayed below to the Selected Items.

LY
N
O
se
lU
r na
te
In

Continued on next page


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-11


Displaying Pens in the Process Analyst, Continued

Exercise 10-2 (continued)

Step Action
5 Select the Alarm Tag that you wish to display
i. Change the search Type: to Alarms.
ii. Click the Search button.
iii. Add the alarm tag P1A to the Selected Items.

LY
N
O
se
lU
r na
te
In

6 Click OK to display the pens.


ct
ite
C

7 Shutdown the project.

10-12 CitectHMI/SCADA Version 6.00 August 2005


Pen Types

Overview A Process Analyst pen represents either trend 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 runtime.

Pen Function
Analog The Process Analyst control typically uses analog pens
to represent non-binary data. Only analog pens have a

LY
value (vertical) axis, which the data is plotted against, as
shown here:

N
O
See Also:
se
For further information about Analog Pens, see Citect
Process Analyst Help – Analog Pens.
lU
Digital The Process Analyst control typically uses digital pens to
represent binary data. Values on the pen are clamped to a
na

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
colour is used to indicate where the data is 1, as shown
r

here:
te
In

See Also:
For further information about Digital Pens, see Citect
ct

Process Analyst Help – Digital Pens.


ite

Continued on next page


C

Advanced Configuration Concepts Manual Revision 2-INT 10-13


Pen Types, Continued

Overview (continued)

Pen Function
Alarm The Process Analyst uses alarm pens to graphically
display the history of a CitectSCADA alarm over time.
The Process Analyst supports seven different types of
alarm pens.
The alarm's on/off transition state changes and

LY
acknowledgments 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

N
acknowledgment.
The diagram below illustrates how an alarm pen displays

O
the information of an alarm tag:

se
lU
1. The alarm is turned on in its initial state and is
unacknowledged.
na

2. The alarm changes to a different state, but is still


unacknowledged.
r
te

3. The alarm is acknowledged.


4. The alarm is turned off.
In

See Also:
For further information about Alarm Pens, see Citect
ct

Process Analyst Help – Alarm Pens.


ite

Continued on next page


C

10-14 CitectHMI/SCADA Version 6.00 August 2005


Pen Types, Continued

Exercise 10-3 Configure the Process Analyst to display the different pen types in runtime.

Step Action
1 Run your project and open the page Analyst.
2 Click the Add Pens button.

LY
N
3 Search for the available Trends.
i. The search Type defaults to Trends. Click the Search button.

O
se
lU
ii. All available trends will populate the Search results window.
r na
te
In
ct

4 Change the Pen Type: to Digital and the Pen name: to Tag.
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 10-15


Pen Types, Continued

Exercise 10-3 (continued)

Step Action
5 Select the trend tags that you wish to display.
i. Scroll to the end of the Search results and Add the trends
P1_P and P2_P to the Selected Items.

LY
N
O
se
lU
r na
te

ii. The pens may be selected by either double clicking the trend
or highlighting the trend and clicking the Add button.
In
ct

Continued on next page


ite
C

10-16 CitectHMI/SCADA Version 6.00 August 2005


Pen Types, Continued

Exercise 10-3 (continued)

Step Action
6 Click OK to continue. The two trend pens will be displayed in a
new pane.

LY
N
O
7
se
Add the trends P3_P and P4_P to the display. This time use
lU
Analog pens.
r na
te
In
ct
ite


C

Advanced Configuration Concepts Manual Revision 2-INT 10-17


Interacting with the Process Analyst

Pen Selection Each pane in the Process Analyst is able to have one selected pen. The axes
displayed on the pane are those of the selected pen. The selected pen is
indicated by a halo effect.

LY
Selected
Pen

N
O
¾ A pen is selected by:
− Clicking on the pen se
lU
− Clicking the background under the pen if the pens are stacked
− Selecting the pen in the Object View
na

Note: The halo does not appear if there is only one pen on the pane.
r

Selecting a pen on a pane also causes the same pen to be


te

highlighted in the Object View. Selecting a pen causes that pen to


be drawn in front of other pens on the pane.
In

Continued on next page


ct
ite
C

10-18 CitectHMI/SCADA Version 6.00 August 2005


Interacting with the Process Analyst, Continued

Locking and This is one of the most powerful features of the Process Analyst. In its
Unlocking Pens default state the Process Analyst synchronises all pens against one time span
but this can be changed by toggling the Lock/Unlock Pens button. Each
trend can then be moved around in time independently of the other pens. You
can even display the pens against each other in different time spans.

LY
N
O
se
lU
The Process Analyst also allows you to overlay your pens on top of each
na

other and/or stack them under each other, giving you great control and
superior visualisation.
r
te

Continued on next page


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-19


Interacting with the Process Analyst, Continued

Scrolling the The Process Analyst allows you to scroll through data in both the horizontal
Chart and vertical directions by dragging the mouse or spinning the mouse wheel.

¾ To scroll by dragging:
1. Click and hold down the left mouse button on the pen (or background)
that you want to scroll.

2. Drag the mouse in the direction you want to scroll:

LY
− Horizontal axis: drag right to move backward in time, drag left to move
forward.

N
O
se
lU
− Vertical axis: drag up to scroll down the axis, drag down to scroll up the
axis.
r na
te

3. Release the left mouse button to complete the scrolling.


In

¾ To scroll by using the mouse wheel:


ct

1. Click the pen or background that you want to scroll.

2. Spin the mouse wheel in the direction you want to scroll:


ite

− Horizontal axis: spin up to move backward, spin down to move forward.


C

− Vertical axis: spin up to scroll up the axis, spin down to scroll down.

Continued on next page

10-20 CitectHMI/SCADA Version 6.00 August 2005


Interacting with the Process Analyst, Continued

Scaling the The Process Analyst allows you to change the scale of the data in both the
Chart horizontal and vertical direction by dragging the mouse or spinning the mouse
wheel.

¾ To scale the data by dragging:


1. Click and hold down the left mouse button on the axis that you want
to scale.

LY
2. Drag the mouse in the direction you want to scale:

− Horizontal axis: drag left to expand the scale, drag right to shrink.

N
O
se
lU
− Vertical axis: drag up to expand the scale, drag down to shrink.
r na
te
In

3. Release the left mouse button to complete the scaling.


ct

¾ To scale by using the mouse wheel:


ite

1. Click the axis that you want to scale.

2. Spin the mouse wheel in the direction you want to scale:


C

− Horizontal axis: spin up to shrink the axis, spin down to expand.


− Vertical axis: spin up to expand the axis, spin down to shrink.

Advanced Configuration Concepts Manual Revision 2-INT 10-21


Interacting with the Process Analyst, Continued

Exercise 10-4 Unlock the pens to compare one trend at different times.

Step Action
1 Delete all the pens from the Process Analyst view except for
the pen P4_P.
2 Add the same pen to the Process Analyst in a new pane.

i. Click the Add Pen button.

LY
ii. Search for all trends and Add the pen P4_P to a New pane.

N
O
3
se
Click the Lock/Unlock Pens button on the toolbar.
lU
r na
te
In
ct

Continued on next page


ite
C

10-22 CitectHMI/SCADA Version 6.00 August 2005


Interacting with the Process Analyst, Continued

Exercise 10-4 (continued)

Step Action
4 Click and hold the pointer on one of the panes and drag the
pane horizontally to display a different time period.

LY
N
O
se
lU
5 Click and hold the pointer on the horizontal axis and drag the
na

pane to display a different time span.


r
te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 10-23


Interacting with the Process Analyst, Continued

Exercise 10-4 (continued)

Step Action
6 Scroll up and down the vertical axis.
i. The vertical scroll option is disabled by default so it is
necessary to enable the vertical scroll option. Right click the
vertical axis. Click the Scroll option on the menu.

LY
N
O
ii. Click and hold the pointer on the background and drag the
pane to scroll up and down the vertical axis.

se
lU
na


r
te
In
ct
ite
C

10-24 CitectHMI/SCADA Version 6.00 August 2005


Configuring Pens

Appearance Pen appearance may be configured during runtime and in design time. Each
pen may be changed individually by Operators and Designers during runtime.
The default settings for pen appearance may be configured in design time.

¾ To configure default pen appearance:


Open the Process Analyst Control Properties in the Citect Graphics Builder,
choose the pen type and then change the appearance using the property page.

LY
N
O
se
lU
r na

¾ To configure pens in runtime:


te

Open the properties in runtime choose the pen and change the appearance
In

using the Appearance tab.


ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 10-25


Configuring Pens, Continued

Exercise 10-5 Change the pen appearance in runtime.

Step Action
1 Add more trends to the page
i. Return to the Analyst page.
ii. Add the alarm P4A to the first pane.
2 Remove the 2nd pane.

LY
i. Click the Show Properties button.
nd
ii. Right click the 2 pane and choose delete.

N
O
se
lU
na

3 Change the appearance of the pens P4_P and P4A.


i. Select the pen P4_P.
r

ii. Change the Line color: of the pen.


te
In
ct
ite
C

Continued on next page

10-26 CitectHMI/SCADA Version 6.00 August 2005


Configuring Pens, Continued

Exercise 10-5 (continued)

Step Action
3 iii. Select the pen P4A and change the Fill colours.
(cont.)

LY
N
O
se
lU
na

4 Click OK to continue.
r


te
In

Continued on next page


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-27


Configuring Pens, Continued

Gridlines Gridlines may be configured during runtime and in design time. Each pen
gridline may be changed individually by Operators and Designers during
runtime. The default settings for gridlines may be configured in design time.

¾ To configure default pen gridline appearance:


Open the Process Analyst Control Properties in the Citect Graphics Builder,
choose All Pens and then change the Gridlines using the Gridlines tab.

LY
N
O
se
lU
r na

¾ To configure pen gridlines in runtime:


te

Open the properties in runtime choose the pen and change the Gridlines using
In

the Gridlines tab.


ct
ite
C

Continued on next page

10-28 CitectHMI/SCADA Version 6.00 August 2005


Configuring Pens, Continued

Exercise 10-6 Change the gridlines during runtime.

Step Action
1 Return to the Analyst page.
i. Add the trend pens P1_P, P2_P and P3_P to Pane1.

2 Click the Show Properties button.


3 Open the Gridlines tab.

LY
4 Change the properties of the Gridlines.
i. Select All Pens.

N
O
se
lU
r na
te
In

ii. Change some of the default settings.


3 Click OK to continue.
ct
ite


Continued on next page
C

Advanced Configuration Concepts Manual Revision 2-INT 10-29


Configuring Pens, Continued

Pen Axes The Axes may be configured during runtime and in design time. Each pen
axis may be changed individually by Operators and Designers during runtime.
The default settings for pen axes may be configured in design time.

You can configure the colour, 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.

LY
¾ To configure default pen axes appearance:
Open the Process Analyst Control Properties in the Citect Graphics Builder,
choose All Pens and then change the properties using the Axis tab.

N
O
se
lU
r na
te
In

Continued on next page


ct
ite
C

10-30 CitectHMI/SCADA Version 6.00 August 2005


Configuring Pens, Continued

Pen Axes ¾ To configure pen axes in runtime:


(continued)
Open the properties in runtime choose the pen and change the properties
using the Axis tab.

LY
N
O
se
lU
Continued on next page
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-31


Configuring Pens, Continued

Exercise 10-7 Change the axis during runtime.

Step Action
1 Return to the page Analyst
2 Click the Show Properties button.
3 Choose the pen P3_P.
4 Open the Axes tab.

LY
i. Change the Label type: of the Vertical axis and the
Background color: of the Horizontal Axis.

N
O
se
lU
r na
te
In

ii. Repeat for all the selected pens.


ct

Continued on next page


ite
C

10-32 CitectHMI/SCADA Version 6.00 August 2005


Configuring Pens, Continued

Exercise 10-7 (continued)

Step Action
5 Click OK to continue.

LY
N
O
se
lU


na

Continued on next page


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-33


Configuring Pens, Continued

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

¾ To configure default pen quality:


Open the Process Analyst Control Properties in the Citect Graphics Builder,
choose All Pens and then change the properties using the Quality tab.

LY
N
O
se
lU
r na
te

Continued on next page


In
ct
ite
C

10-34 CitectHMI/SCADA Version 6.00 August 2005


Configuring Pens, Continued

Pen Quality ¾ To configure pen quality in runtime:


(continued)
Open the properties in runtime choose the pen and change the properties
using the Quality tab.

LY
N
O
se
lU
na

Continued on next page


r
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-35


Configuring Pens, Continued

Exercise 10-8 Change the pen quality during runtime.

Step Action
1 Return to the page Analyst.

i. Display the data points by clicking the Show/Hide Points


button.

LY
N
O
ii.
iii. se
Click the Show Properties button.
Choose a pen then open the Quality tab.
lU
iv. Change the point style then click OK to continue.
r na
te
In
ct

v. Return to the page to view the changes.


ite


C

Continued on next page

10-36 CitectHMI/SCADA Version 6.00 August 2005


Configuring Pens, Continued

Pen Data You use the Process Analyst Properties dialog box to configure the pen data
Connection connection. Configuring the pen data connection allows you to define the
server, trend tag, and request mode for the selected pen.

Pen connection can be configured at run time by Operators and Users that
have the appropriate privileges.

¾ To configure pen data connection:

LY
Select the pen you want to configure and click the Connection tab to display
the connection property controls.

N
O
se
lU
r na
te
In
ct

Continued on next page


ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-37


Configuring Pens, Continued

Exercise 10-9 Create a new pen and use the Connection tab to configure the pen.

Step Action
1 Return to the page Analyst.
2 Click the Show Properties button.
3 Add a new pane to the view.
i. Right click the Process Analyst View button and choose Add
Pane from the menu.

LY
N
O
The new pane will be displayed like this.

se
lU
r na
te

Continued on next page


In
ct
ite
C

10-38 CitectHMI/SCADA Version 6.00 August 2005


Configuring Pens, Continued

Exercise 10-9 (continued)

Step Action
3 Add a new pen.
i. Right click Pane2 and choose Add Pen | Analog from the
menu.

LY
N
ii. Open the Connection tab and add the trend tag HT_P.

O
se
lU
4 Click OK to continue.
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-39


Views

Saving Views Once you have configured the Process Analyst to display the pens you want
you are able to save that configuration for later retrieval. Saving a view also
save the configuration of the toolbar settings, the columns in the Object View
and the “Look and Feel” of the view.

¾ To Open a View in the Process Analyst:

Click the Load View button on the Main Toolbar.

LY
¾ To save a View in the Process Analyst:

N
Click the Save View button on the Main Toolbar.

O
Continued on next page

se
lU
r na
te
In
ct
ite
C

10-40 CitectHMI/SCADA Version 6.00 August 2005


Views, Continued

Exercise 10-10 Save and Open a Process Analyst View.

Step Action
1 Save the current Process Analyst View.
i. Return to the Analyst page in your project runtime.

ii. Click the Save View button on the Main Toolbar.


iii. Name the view PastView.pav.

LY
N
O
se
lU
na

iv. Click the Save button.

2 Leave then reopen the Analyst page.


r
te

Continued on next page


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-41


Views, Continued

Exercise 10-10 (continued)

Step Action
3 Open the saved Process Analyst view.

i. Click the Load View button on the Main Toolbar.


ii. Select the saved view.

LY
N
O
se
lU
iii. Click the Open button. The view will be displayed as it was
na

saved. If the view had been saved with the Auto-scroll


feature turned on the pens will appear synchronised to “Now”.
r
te
In
ct
ite
C

 Continued on next page

10-42 CitectHMI/SCADA Version 6.00 August 2005


Views, Continued

Loading a Page It may be desirable to load predefined views into the Process Analyst as the
with a page starts. This may be achieved using some simple code.
Predefined
View

Exercise 10-11

LY
Step Action
1 Create a function to load a saved view.
i. Open the Cicode Editor and create a new file. Save the file as
Analyst.ci.

N
ii. Create a Global Variable to hold the name of the view outside
the function

O
GLOBAL STRING g_sView;

iii. se
Add this function. The first line names the function and name
which view is to be loaded from the button.
lU
FUNCTION
na

DisplayView(STRING sView)

iv. The first line passes the name of the view into the global
variable. The page Analyst is then displayed.
r
te

g_sView = sView;
In

PageDisplay("Analyst");
END
ct

2 Change the Object Name and Event Class of the Process


Analyst control.
ite

i. Return to the Graphics Builder and open the page Analyst.


ii. Double click the Process Analyst control and change these
properties:
C

Access Object Name PA


(Identification)
Event Class PA_E

iii. Click OK
3 Save the page and compile.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 10-43


Views, Continued

Exercise 10-11 (continued)

Step Action
4 Create a function to load the view into the Process Analyst
object.
i. Return to the Cicode Editor and add this function to the file
Analyst.ci.

LY
FUNCTION OnProcessEntry()

ii. The next line will identify the object to be used as the Process
Analyst named PA.

N
O
OBJECT hAnalyst = ObjectByName("PA");

iii. This line will load the view into the Process Analyst Object.

se
_ObjectCallMethod(hAnalyst,
"LoadFromFile", g_sView, 0);
lU
END

iv. Save the file and compile.


na

5 Add the command to the Analyst page.


i. Return to the Graphics Builder and open the page Analyst.
r

ii. Go to File | Properties | Events and add this command.


te

Event On page shown command


In

On page shown OnProcessEntry()


ct

6 Open the Process analyst from another page.


i. Open the page gr_Past.
ite

ii. Create a button near the Pasteuriser. Add these commands.


C

Appearance Input(Touch)
(General) Text Up command
Pasteuriser View DisplayView("PastView.pav")

7 Save the page and compile.


8 Run the project and test the new function.

10-44 CitectHMI/SCADA Version 6.00 August 2005


Object View

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

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.

LY
The Object View (as it appears in a default configuration) is shown below;

N
O
However, your Object View might look different depending on how it has
been customised in your system.
se
lU
Object View The Object View displays the following items:
Items
na

Icon Description
Analog Pen
r

Digital Pen
te

Alarm
In

Pane
ct

Object View The Object view provides dynamic legend like information including:
Information - Pen Colour
ite

- Pen Name
- Tag properties such as (Engineering Units, Scales etc)
- Current Cursor value
C

- Real time data averaging

The Object View also highlights the currently selected pen(s), so you always
know what you are looking at.

Advanced Configuration Concepts Manual Revision 2-INT 10-45


Object View, Continued

Exercise 10-12 Configure the Object View in runtime

Step Action
1 Open the saved view All Trends.
2 Show and Hide the Object View.

i. Click the Toggle Object View button. This will hide the
object View leaving more space to view the panes.
ii. Click the button again to show the Object View.

LY
3 Resize the Object View.
i. Hover your cursor over the splitter between the Object View
and the Navigation Toolbar.

N
ii. Click and hold the mouse button then drag the mouse up and

O
down to resize the Object View.

se
lU
na

4 Expand and collapse branches.


i. Click the minus sign next to the Pane1 branch to collapse the
branch.
r
te
In
ct

ii. Click the plus sign to expand the branch.


ite

Continued on next page


C

10-46 CitectHMI/SCADA Version 6.00 August 2005


Object View, Continued

Exercise 10-12 (continued)

Step Action
5 Select, display and hide pens.
i. Click one of the pens in the object View. Notice that it will
become the selected pen.
ii. If you have difficulty seeing the pen you want you can
temporarily remove pens from the display. Click the check
boxes to remove the ticks from the pens you wish to hide.

LY
N
O
se
lU
r na
te
In

iii. Show all pens by clicking the check boxes.

Continued on next page


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-47


Object View, Continued

Exercise 10-12 (continued)

Step Action
6 Change the properties of the Object View to show and hide
information.

i. Click the Show Properties button.


ii. Choose the Object View tab.
iii. Remove the tick from the Engineering Units check box.

LY
iv. Add ticks to the Maximum, Minimum and Average check
boxes.

N
O
se
lU
r na
te
In

v. Click OK to continue. These properties will be added to the


ct

display.
ite
C

See Also:
For more information about Additional Pen Information, see the
CitectSCADA Help topic, Configuring the Object View.


10-48 CitectHMI/SCADA Version 6.00 August 2005
Customising Toolbars

Overview Toolbars provide access to the rich command system, allowing the user to add
only the functions they want to use. The Process Analyst provides a
comprehensive set of pre-defined commands to control many common tasks,
but there is always room for one more function and so the Process Analyst
allows you to create your own customised toolbar buttons, complete with
icon. You can then implement the button’s functionality in Cicode.

LY
The Properties ¾ The toolbars may be customised by either:
Dialog

N
Clicking the Show Properties button in runtime. This will change the
properties of the toolbar for this view only.

O
or

se
Changing the properties in the Citect Graphics Builder. This will change the
default view whenever the Process Analyst is opened unless it has been
changed in a saved view.
lU
r na
te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 10-49


Customising Toolbars, Continued

Exercise 10-13 Change the toolbar commands in design time and runtime.

Step Action
1 Return to Citect Graphics Builder and open the page Analyst.
2 Customise the Main Toolbar in design time.
i. Double click the Process Analyst Active X Control.
ii. Open the Appearance | Toolbars tab.

LY
N
O
se
lU
r na
te

iii. Highlight the Add Pane option in the Available toolbar


buttons: list. Click the Add >> button to add this button to
the Current toolbar buttons: list.
In
ct
ite
C

Continued on next page

10-50 CitectHMI/SCADA Version 6.00 August 2005


Customising Toolbars, Continued

Exercise 10-13 (continued)

Step Action
iv. Click the Move Up button to move the Add Pane button
between the Separator and the Add Pens button.

LY
N
O
v.
se
Click OK to close the properties. Note that the Add Pane
lU
button has been added to the Main Toolbar.
na

2 Save the page and compile your project.


r

3 Run your project and open the page Analyst.


te

4 Add a new pane to the Process Analyst.


In

i. Click the New Pane button on the Main Toolbar. The new
pane will appear in the Object Tree.
ct
ite

ii. Click the Add Pens button and add trend pen P2_P to Pane1.
C

iii. Add another Pane to the Process Analyst and add trend pen
P2_P to Pane2.

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 10-51


Customising Toolbars, Continued

Exercise 10-13 (continued)

Step Action
5 Unlock pens and compare the trend to a different time period.
i. Click the Lock/Unlock Pens button on the Main Toolbar.

LY
N
O
se
lU
na

ii. Drag the top pane back to compare the trend with its activity
in the previous hour.
r
te
In
ct
ite
C

6 Save the View as P2_P Comparison.pav.


7 Refresh the page and open the new View.


10-52 CitectHMI/SCADA Version 6.00 August 2005
Cursor and Cursor Labels

Overview 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. 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 the Cursor:

LY
Click the Show/Hide Cursor button

¾ To display the Cursor Labels:

N
O
Click the Show/Hide Cursor Labels button

se Continued on next page


lU
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-53


Cursor and Cursor Labels, Continued

Exercise 10-14 Display the Cursor and Cursor Labels in the Process Analyst.

Step Action
1 Display the Cursor
i. Return to the Analyst page in runtime.
ii. Open the saved view HT_P Comparison.pav.
iii. Click the Show/Hide Cursor button. The Show/Hide Cursor
Labels button will also toggle ON.

LY
N
O
se
lU
r na
te

2 i. Add another cursor to the Process Analyst.

ii. Click the Show Properties button.


In

iii. Right click the Process Analyst View node in the Main Page
tree. Choose Add Cursor from the menu.
ct
ite
C

Continued on next page

10-54 CitectHMI/SCADA Version 6.00 August 2005


Cursor and Cursor Labels, Continued

Exercise 10-14 (continued)

Step Action
iv. A new cursor will appear as one of the nodes in the Process
Analyst View tree.

LY
N
O
se
lU
na

3 Change the Properties of the new cursor.


i. Click the Color: indicator and choose a different colour from
r

the options. Click OK.


te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 10-55


Cursor and Cursor Labels, Continued

Exercise 10-14 (continued)

Step Action
4 Click OK to close the Properties.
5 Use the pointer to drag the new cursor to a new location.

LY
N
O
6 Shut down your runtime.
se
lU

r na
te
In
ct
ite
C

10-56 CitectHMI/SCADA Version 6.00 August 2005


Security and Permissions

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

Privilege Levels The Process Analyst has nine privilege levels. Privilege level zero (0)
indicates there is no security and any user can perform the function.

LY
Levels 1-8 map directly to the eight (8) privilege levels of security provided
by Citect. The Process Analyst, by default, assumes the area of the page that
it is situated on; this can be changed in the Graphics Builder. So if an operator

N
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

O
level 2, the function would then become available. The Process Analyst also
supports the CitectSCADA Hierarchical Privilege security option.

Administration
Privilege se
The Process Analyst also uses an Administration privilege level to disable
engineer-oriented features at run time. For example, the ability to add new
lU
custom commands and so on is disabled if the Operator does not meet the
required privilege level. The Administration privilege level should never be
zero on a running system as this would expose properties to an Operator,
which could adversely affect the performance of the client and/or server (e.g.,
na

Number Of Samples property).


r

See Also:
te

For more information about Administration Privilege, see Citect Process Analyst
Help topic, Administration privilege.
In

Continued on next page


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-57


Security and Permissions, Continued

Exercise 10-15 Change the Administrator Privilege Level.

Step Action
1 In the Citect Graphics Builder open the page Analyst.
2 Change the Security Properties.
i. Double click the Process Analyst ActiveX Control.
ii. Choose Appearance | General.

LY
iii. Set the Privilege Level to 8. Click OK.

N
O
se
lU
r na
te
In

Continued on next page


ct
ite
C

10-58 CitectHMI/SCADA Version 6.00 August 2005


Security and Permissions, Continued

Exercise 10-15 (continued)

Step Action
3 Compare the view when Administration Privilege is
implemented.
i. Run your project.
ii. Log in as the user Operator with the password opr.
iii. Open the Analyst page.

LY
iv. Click the Show Properties button. Compare the settings that
are available to this user with either the Designer or the
Engineer who both have global privilege of 8.

N
O
se
lU
r na
te
In
ct


ite
C

Advanced Configuration Concepts Manual Revision 2-INT 10-59


LY
N
O
se
lU
na
r
te
In
ct
ite
C

10-60 CitectHMI/SCADA Version 6.00 August 2005


Chapter 11: OPC
Overview

Introduction This section deals with OPC – OLE for Process Control. OPC stands for
OLE for Process Control and is designed to allow business applications to
gain access to plant floor data in a consistent manner.
The OPC standard is defined by the OPC Foundation, and is documented in
the OPC Specification Version 1.0a. To become OPC compliant, an
application is required to implement the COM interfaces documented in the

LY
OPC Specification.
Citect can implement OPC as either/both an OPC Server or/and an OPC

N
Client.

O
Contents This chapter contains the following topics:

Topic
¾ What is OPC?
se See Page
11-2
lU
¾ Citect OPC Server 11-3
¾ Citect OPC Client 11-9
r na
te
In
ct
ite
C
What is OPC?

Overview OPC provides a common interface for communicating with diverse process-
control devices, regardless of the controlling software or devices in the
process.
OPC (OLE for Process Control) is an industry standard created with the
collaboration of a number a leading worldwide automation, hardware and
software suppliers working in cooperation with Microsoft. The organization
that manages this standard is the OPC Foundation.

LY
Based on Microsoft's OLE (now Active X), COM (component object model)
and DCOM (distributed component object model) technologies, OPC consists
of a standard set of interfaces, properties, and methods for use in process-
control and manufacturing-automation applications. The Active X/COM

N
technologies define how individual software components can interact and
share data.

O
To put it simply OPC is used to obtain plant floor data from one program into
another program written by someone else. CitectSCADA is able to hold data

se
that can be used by another application (Citect OPC Server) or it is able to
extract data from another application (Citect OPC Client).
lU
r na
te
In
ct
ite
C

11-2 CitectHMI/SCADA Version 6.00 August 2005


Citect OPC Server

When you want to extract data from CitectSCADA into another application
CitectSCADA is acting as the OPC Server.

LY
I/O Device
OPC Client

N
O
Citect OPC

se
In the COM architecture, each variety of Server is allocated a unique
lU
identifier, known as a Class ID. These 128 bit numbers, frequently displayed
in the form 6B29FC40-CA47-1067-B31D-00DD010662DA, are passed to
COM by OPC clients in order to access the particular vendor’s OPC server.
As we discussed in Chapter 1 these types of numbers are extremely difficult
na

to work with and remember. To remove the need for users to have to deal
with these numbers, they are often referred to by a more manageable string
identifier, called a ProgID (Program Identifier). These usually take the form
r
te

Vendor.Application with an optional version number appended. The ProgID


for the Citect OPC Server is Citect.OPC.
In

Each client that connects to the Citect OPC server will require a Connectivity
license because Citect’s OPC server connects to CitectSCADA through the
CTAPI.
ct

Continued on next page


ite
C

Advanced Configuration Concepts Manual Revision 2-INT 11-3


Citect OPC Server, Continued

Exercise 11-1

Step Action
1 Use CitectSCADA as an OPC Server and extract data using a
third party OPC Client. The third party OPC client we will be
using in this exercise is the FactorySoft OPC Client.
i. Using the Computer Setup Wizard set up your computer as a
stand alone server.

LY
ii. Start the FactorySoft OPC Client software.

N
O
iii. From the Menu choose OPC | Connect…

se
lU
r na
te
In
ct

Continued on next page


ite
C

11-4 CitectHMI/SCADA Version 6.00 August 2005


Citect OPC Server, Continued

Exercise 11-1 (continued)

Step Action
1 iv. The next dialog will be displayed. Choose Citect.OPC. Click
(cont.) OK.

LY
N
O
se
lU
v. Go to OPC | Add Item…
r na
te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 11-5


Citect OPC Server, Continued

Exercise 11-1 (continued)

Step Action
1 vi. Highlight the tag you wish to display and click Add Item.
(cont.)

LY
N
O
se
lU
na

vii. Keep adding each tag individually then click Done when
finished. The tags and their values will be displayed.
r
te
In
ct
ite
C

Continued on next page

11-6 CitectHMI/SCADA Version 6.00 August 2005


Citect OPC Server, Continued

Exercise 11-1 (continued)

Step Action
2 Use the OPC client to change the tag values in your
CitectSCADA project.
i. Right click on one of the tags to display this menu. Choose
Write Value to Item…

LY
N
O
ii.
se
Change the value of the tag.
lU
r na
te

Continued on next page


In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 11-7


Citect OPC Server, Continued

Exercise 11-1 (continued)

Step Action
2 iii. The change will be displayed in the OPC client and in
(cont.) CitectSCADA.

LY
N
O
se
lU
na

iv. Disconnect the client from the Citect OPC Server.


v. Shutdown the project.
r
te


In
ct
ite
C

11-8 CitectHMI/SCADA Version 6.00 August 2005


Citect OPC Client

Overview CitectSCADA may also be an OPC Client connecting to a third party OPC
Server or to a Citect OPC Server.

LY
I/O
OPC Server
DEVICE

N
Citect OPC
Client

O
Continued on next page

se
lU
r na
te
In
ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 11-9


Citect OPC Client, Continued

Exercise 11-2

Step Action
1 Use the FactorySoft OPC Server (or any other third party OPC
Server) and CitectSCADA as the Client.
i. Install and run the FactorySoft OPC Server provided by your
Instructor.
ii. Highlight Simulation then choose View | Monitor from the

LY
menu.

N
O
se
lU
iii. Run the FactorySoft OPC Client and Connect to
na

FactorySoft.Sample.
iv. Choose OPC | Add Item… from the menu.
r
te
In
ct
ite
C

Continued on next page

11-10 CitectHMI/SCADA Version 6.00 August 2005


Citect OPC Client, Continued

Exercise 11-2 (continued)

Step Action
1 v. Highlight the items you wish to add then click the Add Item
(cont.) button. Click Done when you are finished. The items and
their values will be displayed in the client window.

LY
N
O
2 Configure CitectSCADA to be an OPC client.
i.
se
Create a new I/O Device to connect to the Factorysoft OPC
Server. Open the Citect Project Editor and choose
Communication | Express Wizard from the menu.
lU
ii. Use the existing I/O Server.
r na
te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 11-11


Citect OPC Client, Continued

Exercise 11-2 (continued)

Step Action
2 iii. Create a new I/O Device called OPCDev.
(cont.)

LY
N
O
se
lU
iv. Choose External I/O Device.
r na
te
In
ct
ite
C

Continued on next page

11-12 CitectHMI/SCADA Version 6.00 August 2005


Citect OPC Client, Continued

Exercise 11-2 (continued)

Step Action
2 v. The next dialog allows you to choose the driver. Select the
(cont.) OPC driver from OPC Foundation.

LY
N
O
se
lU
vi. Enter the name Factorysoft.Sample as the Address.
na

Continue to the end of the Express Communications Wizard.


r
te
In
ct
ite
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 11-13


Citect OPC Client, Continued

Exercise 11-2 (continued)

Step Action
2 vii. Return to the Citect Project Editor and check the settings for
(cont.) the I/O Server, Boards, Ports and I/O Devices forms. There
are some values that you will need to adjust manually. Your
settings should look like this.

LY
I/O Server Server Name MilkServer
Boards Board Name Board2
Board Type OPC

N
Address 250 (See note below)

O
Special Opt Computer Name of the
Server e.g. Training01
Ports Port Name Port1_Board2

I/O Devices
Board Name
Name se Board2
OPCDev
lU
Number 2
Address FactorySoft.Sample
Protocol OPC1
na

Port Name Port1_Board2


r
te

Note: This value is the ScanRate in milliseconds. The


ScanRate is the rate at which the OPC Server will notify
In

CitectSCADA of changes to the value of your variable


tags. Enter 0 to use the OPC Server’s default scanrate.
ct
ite

Continued on next page


C

11-14 CitectHMI/SCADA Version 6.00 August 2005


Citect OPC Client, Continued

Exercise 11-2 (continued)

Step Action
3 Create Variable Tags to match the items in the FactorySoft
Server
i. Go to Variable Tags in the Project Editor and add the tags.

LY
N
O
se
lU
ii. The FactorySoft Client will give you the addresses for the
tags. Add the other two tags with the settings in the table
below.
na

Item Random Sine


r

Variable Tag Name Random Sine


te

Data Type Real Real


In

I/O Device Name OPCDev OPCDev


Address Simulation.Random Simulation.Sine
ct

Continued on next page


ite
C

Advanced Configuration Concepts Manual Revision 2-INT 11-15


Citect OPC Client, Continued

Exercise 11-2 (continued)

Step Action
4 Use the page gr_Debug to display the tag values.
i. Go to the Graphics Builder and open the page called gr_Debug.
ii. Put three Numeric objects on the page to display the data from
those tags.

LY
N
O
se
lU
iii. You may also wish to add Text objects to label the tags.
r na
te
In
ct

iv. Compile and Run the project. CitectSCADA will display the
ite

data from the FactorySoft OPC Server.


C

11-16 CitectHMI/SCADA Version 6.00 August 2005


Chapter 12: Alarms and Trends
Overview

Introduction Alarms and Trends allow you to gather an abundance of raw data.
CitectSCADA has some inbuilt functions that allow you to manipulate the
data in runtime. In a large system the number of alarms displayed on the
pages can run into thousands. Alarm pages may be filtered to show specified
types of alarms.

LY
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

N
operators to identify and display active alarms of interest.

O
CitectSCADA also has inbuilt trend functions to extract samples from a
specified time periods. Mathematical functions may then be used to turn the
data into meaningful information.

Contents
se
This chapter contains the following topics:
lU
Topic See Page
¾ Alarm Filtering 12-2
na

¾ Custom Alarm Filters 12-2


¾ Table Maths 12-7
r
te
In
ct
ite
C
Alarm Filtering

Overview Alarms may be grouped into categories but you may need to display alarms in
ways that fall outside the categories that have been defined. Alarm filtering
functions allow you the flexibility to filter your alarm display using any of the
fields in any of the alarm databases.

There is an in-built filter function run by an icon on the standard


CitectSCADA Alarm page. This displays a form allowing the user to set a
number of filter criteria. For more customised filtering you can write your

LY
own filter function.

N
Custom Alarm CitectSCADA allows you to define keywords for your alarm tags that you can
Filters then use to perform customised queries on your alarm data.

O
The Alarm Properties dialog allows you to define up to eight custom filters
for each of the alarms in your system, allowing you to generate queries that

se
filter your alarm data for specific information.
lU
r na
te
In
ct
ite
C

Continued on next page

12-2 CitectHMI/SCADA Version 6.00 August 2005


Alarm Filtering, Continued

Exercise 12-1 You may want to pay careful attention to all alarms that represent a potential
fire hazard. You could set Custom Filter 1 for each relevant tag to "fire
hazard". You could then call a Cicode function that requests all alarms with a
"custom filter 1" field equal to "fire hazard". The end result would be a list of
alarms notifying an operator of any potentially flammable circumstances.

You could also set aside Custom Filter 2 to define the type of equipment the
alarm is associated with, and label each alarm accordingly (e.g. "pump",

LY
"conveyor", etc.). Queries could then be created to list all the alarms related to
a particular type of machinery; for example, all alarms associated with
pumps.

N
Step Action
1 Create an alarm filter form.

O
i. Open the Cicode Editor and create a new Cicode file called
Alarm.ci.
ii.

se
Start with a module variable that will pass the filter information
from the form to the alarm query.
lU
STRING msEquipment;

iii. Create a new function called AlarmFilter().


na

FUNCTION
r

AlarmFilter()
te

INT iForm;

iv. Define your form.


In

FormNew("Alarm Filter",20,3,0);
ct

FormPrompt(0,0,"Select Equipment Type");


FormComboBox(0,1,12,4,msEquipment,0);
ite

FormAddList("PUMP");
FormAddList("PAST");
FormAddList("SILO");
FormButton(0,2," OK ",0,1);
C

FormButton(12,2," CANCEL ",0,2);

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 12-3


Alarm Filtering, Continued

Custom Alarm Filters (continued)

Step Action
1 v. Add error checking to the form then END the function.
(cont.)

iForm = FormRead(0);

IF iForm <> 299 THEN

LY
AlarmSetQuery(21,"QueryFunction",
msEquipment);
END
END

N
O
Note: The number 21 in the example shown above refers to the
Animation Number of the first f(x) object on the Alarm
page.
se
lU
Note: AlarmSetQuery() tells Citect the name of your custom
query function.
r na

Continued on next page


te
In
ct
ite
C

12-4 CitectHMI/SCADA Version 6.00 August 2005


Alarm Filtering, Continued

Custom Alarm Filters (continued)

Step Action
2 Create a function that will filter an alarm list based on a
custom alarm filter.
i. Go to the Cicode Editor and open the Cicode file Alarm.ci.
ii. Create a new function called QueryFunction().

LY
INT
FUNCTION
QueryFunction(INT nRID, INT nVer=0)

N
STRING sCustom1;

O
Note: Your query function must have these exact arguments.
Citect will pass an alarm record number and version

se
when it calls the function. The function must return
TRUE or FALSE to indicate whether the alarm will
display
lU
iii. Use the function AlarmGetFieldRec() to find the contents of
na

the CUSTOM1 field in the alarm record.

sCustom1 = AlarmGetFieldRec(nRid,"CUSTOM1",0);
r
te

iv. Search the alarm tag name for the equipment type that was
selected from the filter form then END the function.
In

IF StrSearch(0,StrUpper(sCustom1),msEquipment) =
ct

-1 THEN
RETURN FALSE;
ELSE
ite

RETURN TRUE;
END
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 12-5


Alarm Filtering, Continued

Custom Alarm Filters (continued)

Step Action
3 Add a button to your alarm pages to filter your alarms.
i. Open your Alarm template.
ii. Add two buttons to the side toolbar. Use these settings.

LY
Appearance Input (Touch) Access
(General) Up command (General)
Symbol Tool tip:

N
icons.AlmFilter1 AlarmFilter() Alarm
Filter

O
icons.AlmFilter2 AlarmSetQuery( -1,"","" ) Remove
Filter

iii.
iv. se
Save the template and update your pages.
Compile and run your project to test your alarm filter
functionality.
lU

r na
te
In
ct
ite
C

12-6 CitectHMI/SCADA Version 6.00 August 2005


Table Maths

Exercise 12-2 Cicode functions are able to perform mathematical operations on a table of
real (floating-point) numbers. The TableMath() function supports minimum,
maximum, average, standard deviation, and total operations on a table of
values. This is especially suitable for operating on tables returned from the
trend system with the TrnGetTable() function.

Step Action
1 Create a function that will calculate the maximum, minimum,

LY
average and total values trend sample taken from a specified
period.
i. Create a new Cicode file called Trend.ci.
ii. Start with your module variables.

N
O
REAL rMilkFlowTable[5000];
REAL mrMax,mrMin,mrAvg,mrTotal;
INT miSamples;

Note:
se
TrnGetTable() requires a REAL array for the data.
lU
iii. Create a new function called GetTrendsEx().
na

FUNCTION
GetTrendsEx()
r

STRING sTime,sDate,sDateTime,sSamples;
te

iv. Use an Input() function to allow the user to enter the end date
In

and time of the trend data.


ct

sDateTime = Input("Enter End Date and


Time","(eg. 25/12/2004 13:00)",Date(2) + " " +
Time(0));
ite

Note: The date and time format depends on Windows' locale


C

settings.

v. Use an Input() function to allow the user to enter the number


of samples to collect.

sSamples = Input("Number of Samples","Enter


Number of Samples to collect","");

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 12-7


Table Maths, Continued

Exercise 12-2 (continued)

Step Action
1 vi. Convert the String variable sSamples into an integer so that it
(cont.) may be used in the TrnGetTable() function.

miSamples = StrToInt(sSamples);

LY
vii. Extract the date and time values.

IF sDateTime <> "" AND sSamples <> "" THEN

N
sDate = StrLeft(sDateTime,10);
sTime = StrRight(sDateTime,5);

O
9 Hints & Tips:

se
If the day, month, or minutes have only one digit this will not work. Use
StrSearch() to find the space in the string. Then, everything to the left
will be the date and everything to the right will be the time.
lU
viii. Put the trend data into an array.
na

TrnGetTable("milkflow",StrToDate(sDate) +
StrToTime(sTime),1,miSamples,
r

rMilkFlowTable[0],0);
te

ix. Use the TableMath() function to calculate the values from the
In

trend sample.

mrMin = TableMath(rMilkFlowTable,miSamples,0,1);
ct

mrMax = TableMath(rMilkFlowTable,miSamples,1,1);
mrAvg = TableMath(rMilkFlowTable,miSamples,2,1);
ite

mrTotal =
TableMath(rMilkFlowTable,miSamples,4,1);
C

See Also:
For further information about how to handle <N/A> and <Gated>
samples, see Citect Help Topics - TableMath Cicode function - Mode.

Continued on next page

12-8 CitectHMI/SCADA Version 6.00 August 2005


Table Maths, Continued

Exercise 12-2 (continued)

Step Action
1 x. Display the results in a message box then end the function.
(cont.)

Message("Minimum","Minimum Milk Flow = " +


RealToStr(mrMin,5,2) + "lt/h" + "^nMaximum Milk
Flow = " + RealToStr(mrMax,5,2) + "lt/h" +

LY
"^nAverage Milk Flow = " + RealToStr(mrAvg,5,2)
+ "lt/h" + "^nTotal Milk Flow = " +
RealToStr(mrTotal,5,2) + "lt/h",64);
END

N
END

O
9 Hints & Tips:
^n creates a new line.

2
se
Display all the array values in the kernel.
lU
i. Create a function called ViewTable().
na

FUNCTION
ViewTable()
INT iIndex=0;
r
te

ii. Use a FOR loop to display the array values then END the
function.
In

DspKernel(1);
FOR iIndex = 0 TO miSamples-1 DO
ct

TraceMsg("rMilkFlowTable Array Value " +


IntToStr(iIndex) + " - " +
RealToStr(rMilkFlowTable[iIndex],5,2));
ite

SleepMS(20);
END
END
C

Continued on next page

Advanced Configuration Concepts Manual Revision 2-INT 12-9


Table Maths, Continued

Exercise 12-2 (continued)

Step Action
3 Add button to one of your pages to call the two functions.
i. Open the page gr_Debug().
ii. Add two buttons to the page. Use these settings.

LY
Appearance (General) Input (Touch)
Text Up command
Get Trend Samples GetTrendsEx()

N
View Kernel ViewTable()

O
iii. Save your page and compile your project.
iv. Test your new functions.

Note:
se
When entering the time make sure it is in 24 hour format
lU
and that there is no AM or PM in the time string.
na

 Continued on next page


r
te
In
ct
ite
C

12-10 CitectHMI/SCADA Version 6.00 August 2005


Table Maths, Continued

Exercise 12-3

Step Action
1 Create a report to display the trend maths.
i. Add this function to your file Trend.ci.

FUNCTION

LY
ShowReport()
INT hFile;

hFile = FileOpen("C:\FlowRates.txt","w+");

N
FileWriteLn(hFile,"Milk Flow Report -
Date:" + Date(2) + " Time:" + Time(0));

O
FileWriteLn(hFile,"");
FileWriteLn(hFile,"Minimum Milk Flow = " +
RealToStr(mrMin,5,2) + "lt/h");

se
FileWriteLn(hFile,"Maximum Milk Flow = " +
RealToStr(mrMax,5,2) + "lt/h");
FileWriteLn(hFile,"Average Milk Flow = " +
RealToStr(mrAvg,5,2) + "lt/h");
lU
FileWriteLn(hFile,"Total Milk Flow = " +
RealToStr(mrTotal,5,2) + "lt/h");
FileWriteLn(hFile,"Report End");
na

FileClose(hFile);

PageFile("C:\FlowRates.txt");
r

END
te

ii. Create a page called !File based on the file template.


In

iii. Add a button to your page gr_Debug to call the function


ShowReport().
iv. Save the page and compile your project.
ct

v. Run your project and view the report.


ite


C

Advanced Configuration Concepts Manual Revision 2-INT 12-11


LY
N
O
se
lU
na
r
te
In
ct
ite
C

12-12 CitectHMI/SCADA Version 6.00 August 2005


Chapter 13: Course Summary

Introduction This chapter covers the course summary and next steps available through
Citect Education Services.

Course As you have completed the CitectSCADA Advanced Configuration Concepts


Summary course, you should:

¾ Understand how to create and use Custom Templates

LY
¾ Create and use Smart Genies and Smart Popups
¾ Write Forms and Genie Forms

N
¾ Learn about True Color and the new Color Tools
¾ Use VBA to use the Graphics Builder Automation Interface

O
¾ Connect CitectSCADA to other Applications
¾ Learn to use the Process Analyst
¾
¾
se
Connect to other SCADA software using OPC
Use Alarm Filtering and Table Maths
lU
r na
te
In
ct
ite
C
Course Evaluation

Evaluation At the end of each training course, we ask that you complete the Course
Form Evaluation Form.

The Evaluation Form is used by Citect Educational Services to constantly


improve the quality of our courseware and services.

Training Training Certificates are sent to customers who have completed one of the

LY
Certificates courses in the Citect Curriculum (excluding Overview). The completion of
the Course Evaluation Form is mandatory if you wish to receive a Training
Certificate.

N
O
Please Fill Out If you have just completed your Citect course and would like a certificate to
Evaluation be sent to you please go to this site.

se
http://www.citect.com/exams/home/course_eval

You will need your Training Manual Licence Number. This is located on the
lU
inside of the front cover.

Citect Educational Services


na

This is your official Citect Training Licence Number:


r
te

12345_67
In
ct
ite

If there is no Licence Number inside the front cover of your manual please
contact Citect Educational Services at training@citect.com.
C

13-2 CitectHMI/SCADA Version 6.00 August 2005


Further Training

Next Steps in Citect offers a variety of technical training courses to meet your specific
Training training requirements. Instructor-led courses provide you with hands-on
experience, leaving you feeling confident to design and configure your own
systems.

Citect training services include configuration and programming courses,


update courses, and introductory courses for both CitectHMI/SCADA and
Citect Plant2Business solutions.

LY
We have developed unique, step-by-step training that has proven highly
effective, and our curriculum is continually updated, enabling you to stay in

N
step with rapidly changing technology.

O
se
lU
r na
te
In

Continued on next page


ct
ite
C

Advanced Configuration Concepts Manual Revision 2-INT 13-3


Further Training, Continued

Course Citect Education Services offer the following courses:


Offerings
¾ CitectHMI/SCADA Configuration Course : Gain insight into
CitectSCADA project design and become familiar with configuration
techniques. Learn about plant control, data collection, trending and
reporting in this “hands-on” course.
¾ CitectIIM Performance Course : This course applies to people who are
required to develop the skills needed to be able to build, maintain and use

LY
an IIM system. The course will teach the skills required to build and
modify an IIM Performance system and to provide an understanding of
the purpose behind IIM. The CitectIIM Performance Course will

N
encourage users to achieve the maximum benefit out of their IIM system.
¾ CitectHMI/SCADA Upgrade Course : Receive an update to

O
CitectSCADA project design and configuration techniques, and view the
newest product features.
¾
se
Cicode Fundamentals Course : Learn about basic programming
techniques using the Cicode programming language in this “hands-on”
course. This course is aimed at the user who has had no programming
lU
experience. It is also useful for the experienced user who wishes to
become familiar with Cicode.
¾ CitectHMI/SCADA Intermediate Course : Gain advanced skills
na

including knowledge of the principles behind networking in


CitectSCADA, such as how CitectSCADA uses a network, redundancy,
distributed servers and RAS. Learn more about the Citect Kernel and
r

exchanging data between CitectSCADA and other applications such as


te

Microsoft Access and Excel.


¾ CitectSCADA Advanced Configuration Concepts Course : This course
In

will provide you with more advanced skills customising your pages,
exchanging data between CitectSCADA and other applications such as
Microsoft Access, configuring Alarm queries using the Kernel,
ct

Debugging and using Table Maths.


ite

¾ Citect Plant2Business Course : Upon completing this course you will be


able to develop customised plant information portals that aggregate and
share information between all types of plant control systems, MES/ ERP
C

application databases and users throughout your enterprise.

Full course descriptions are available on the website


http://www.citect.com/training/courses

13-4 CitectHMI/SCADA Version 6.00 August 2005


Online Course Quizzes

Quick Quizzes When you enrol in a training course run at a Citect Authorised Training
Centre you will receive a training manual with a licence number on the inside
cover.

Citect Educational Services


This is your official Citect Training Licence Number:

LY
12345_67

N
O
se
lU
This licence number is used to create an Exam User ID and Password. This is
the ID that you will use for all Citect Quizzes and CCE Exams.
r na
te
In
ct
ite
C

The quiz system is designed to give the student instant feedback regarding
their progress through the course. Ask your instructor to organise a user ID
and Password for you if you would like to use the Quiz system.

Advanced Configuration Concepts Manual Revision 2-INT 13-5


Citect Examinations

Citect Certified The CCE program distinguishes and recognizes engineers skilled in the
Engineer integration of Citect-based automation projects, and encourages other
engineers to move in this direction. At the heart of the CCE program is the
CCE exam, which provides a means of testing experienced systems engineers.
It encompasses tests for both CitectSCADA knowledge as well as a range of
related topics such as PLC communications, Windows OS and networking.

LY
N
O
se
lU
na

These web pages contain more information on the CCE program


r
te

http://www.citect.com/partners/home/cce
In

http://www.citect.com/exams/home
ct
ite
C

13-6 CitectHMI/SCADA Version 6.00 August 2005