v7.

20

CitectSCADA User Guide

October 2010
Legal Notice
DISCLAIMER
Schneider Electric (Australia) Pty. Ltd. makes no representations or warranties with respect to this manual and, to the max-
imum extent permitted by law, expressly limits its liability for breach of any warranty that may be implied to the replacement
of this manual with another. Further, Schneider Electric (Australia) Pty. Ltd. reserves the right to revise this publication at any
time without incurring an obligation to notify any person of the revision.

COPYRIGHT
© Copyright 2010 Schneider Electric (Australia) Pty. Ltd. All rights reserved.

TRADEMARKS
Schneider Electric (Australia) Pty. Ltd. has made every effort to supply trademark information about company names, products
and services mentioned in this manual.
Citect, CitectHMI, and CitectSCADA are registered trademarks of Schneider Electric (Australia) Pty. Ltd.
IBM, IBM PC and IBM PC AT are registered trademarks of International Business Machines Corporation.
MS-DOS, Windows, Windows NT, Microsoft, and Excel are either registered trademarks or trademarks of Microsoft Cor-
poration in the United States and/or other countries.
DigiBoard, PC/Xi and Com/Xi are trademarks of Digi International Inc.
Novell, Netware and Netware Lite are either registered trademarks or trademarks of Novell, Inc. in the United States and other
countries..
dBASE is a trademark of dataBased Intelligence, Inc.
All other brands and products referenced in this document are acknowledged to be the trademarks or registered trademarks of
their respective holders.

GENERAL NOTICE
Some product names used in this manual are used for identification purposes only and may be trademarks of their respective
companies.
October 2010 edition for CitectSCADA Version v7.20
Manual Revision Version v7.20.

Contact Schneider Electric (Australia) Pty. Ltd. today at www.Citect.com/citectscada

Contents

Legal Notice 2

Contents 3

Getting Started 23

Safety Information 25

Chapter: 1 Getting Technical Support 27

CitectSCADA Technical Support 27
Training 28
Contact information 28

Chapter: 2 What's New in CitectSCADA v7.x 29

What's New in CitectSCADA v7.0 29
The Migration Tool 30
Clustering 30
Local Variables 30
Publish Alarm Property 31
Memory Mode 31
Client-side Online Changes 31
Publisher-Subscriber Model 32
Dual Network Support 32
Project-Based Network Configuration 32
Citect.ini Parameters in version 7.0 32
New Parameters 33
Obsolete Parameters 36
Cicode Functions in v7.0 40
CtAPI Functions in v7.0 49
What's New in CitectSCADA v7.10 50

3
Contents

CitectSCADA Security Enhancements 51

Windows Integrated Security 52
Multi-Signature Support 52
Edit .dbf Files in Microsoft® Excel 52
Enhanced Driver Installation 53
New Font Selection for Graphics Button 53
Microsoft Windows Vista Support 54
New Locations for Configuration and Project Files 54
Alarm Field Enhancements 55
New Time Synchronization Service 57
New Equipment Database Functions and Forms 57
Citect.ini Parameters in v7.10 57
Cicode Functions in v7.10 60
What's New in CitectSCADA v7.20 61
Control SCADA Client Connections 62
Dynamically Optimized Writes 63
Environment variables in 7.20 63
Graphic Enhancements 64
Improved Installation Process 64
Improved CitectSCADA Security 65
Multi-process Support in Demo Mode 65
New Example Project 65
Web-based Help 66
OFSOPC Driver 66
Pelco Camera Support 67
Performance Enhancements 67
Persisted I/O Memory Mode 68
Post Compile Commands 68
Improved Client Side Online Changes 68
Server Side Online Changes 69
Microsoft Windows 7 Support 69
Supportability Enhancements 69
New Tab Menu Templates 70
Tag Extensions 70
Time Scheduler 71
Citect.ini Parameters in v7.20 71
CtAPI Functions in v7.20 78
Cicode Functions in v7.20 79
Kernel Commands in Version 7.0 86

Chapter: 3 Upgrading to CitectSCADA v7.20 87

Upgrade CTAPI Applications 88
Configure I/O Devices 88
Run the Citect Installer 89
Launch CitectSCADA 90
Migration Tool 90
Creation of roles for existing users 95
Define Clusters 97

4
 Contents

Configure Network Addresses 97

Configure Servers 97
Configure Tags to Use Clustering 99
Configuring Multiple Monitor Support 101
Compile the Project 101
Run Computer Setup Wizard 101
Troubleshooting 101

Chapter: 4 About CitectSCADA 103

Dynamic-point count licensing 103
Configuring a CitectSCADA project 104
Deploying CitectSCADA 105
Running a project 105

Chapter: 5 Tools 107

Configuration Tools 107
Runtime Tools 108
Drivers 109

Chapter: 6 Components of a project 111

Graphics components 111
Tags 112
Alarms 113
System components 113
Communications components 115
I/O Server components 115
Cicode / CitectVBA 116

Chapter: 7 Typical system scenarios 117

Standalone system 118
Distributed I/O system 118
Client-Server system 120
Redundant server system 121
Clustered control system 122
Redundant and distributed control system 123
Load sharing system 125

Using CitectSCADA 127

Chapter: 8 Planning a Project 129

The Physical Layout of a Plant 129
Operational Requirements 130
Architecture 130
Security 131

5
Contents

Reliability 131
Monitoring 131
Data collection 131
Project Design 132
Naming Standards 132
Page Templates 133
Genies and Super Genies 133
Clustering 133
Included projects 135
Redundancy 136
Building Your Project 136
Projects 137
Setting up I/O Device Communication 137
Graphics Components 137
Alarms 138
Data Collection 138
Users and Areas 139
System Components 139
Setting up Your Computers 140
Setting up CitectSCADA as an OPC data source 140

Chapter: 9 Administering Projects 143

Managing your projects 143
Creating a project 143
Editing the properties of an existing project 146
Copying projects 149
Printing project details 151
Deleting a project 152
Linking projects 152
Time Synchronization 153
Time Synchronization Dialog 154
Archiving projects 155
Backing up a project 156
Backing up INI files 157
Configuring a backup with password encryption 158
Running a backup from the command line 158
Restoring a project 160
Including projects 161
Including a project in the current project 163
Included projects 164
Working with the Project Editor 164
Setting the Project Editor options 165
Paste Tag dialog box 168
Paste Function dialog box 168
Find User Function dialog box 168
Using Find and Replace in a project 169
The Find and Replace dialog 169
Specifying search coverage 170

6
 Contents

Using the results list 171

Removing results 172
Exporting results 172
Jumping to a result (Go To) 173
Replacing results 174
Find and Replace alert messages 175
Troubleshooting Searches 178

Chapter: 10 Securing Projects 179

Overview 179
Securing a Top-level Project 180
Securing an Include Project 182
Making a Project Read-Only 183
Read-Only Privileges on Projects 184
Securing Runtime Computers 189
Client Start up Restrictions 189
Running a client as a shell 190
Disabling Windows keyboard commands 190
Disabling control menu commands 190
Removing the Cancel button 190

Chapter: 11 Using CitectSCADA Security 193

Areas 193
Privileges 195
Roles 197
Users 198
Configuring CitectSCADA Security 199
Configuring Areas 199
Using labels to name areas 199
Using groups of areas 200
Groups properties 201
Viewing areas of the plant 202
Adding Roles 203
Additional Fields 204
Configuring Privileges 205
Using hierarchical privilege 205
Implementing System Security 206
Privilege and Area combinations 206
Using multiple areas with privileges 208
Adding users 210
User records and project restoration 212
Using CitectSCADA integrated with Windows Security 212
Adding Groups and Users 213
Scenarios and Usage 214
Authenticating a Trusted Network 215
Setting the Super User Password 216

Chapter: 12 Configuring Your System 217

7
Contents

Running the Computer Setup Wizard 217

Project Configuration 218
Runtime only environment 219
Computer Role Configuration 220
Network Model 221
Configure Server Password 221
Configure Server User 222
Internet Server Configuration 222
Alarm Configuration 223
Reports Configuration 224
Trends Configuration 225
CPU Configuration 225
Events Configuration 226
Startup Functions Configuration 227
Cluster Connections Configuration 228
Control Menu Security Configuration 229
Keyboard Security Configuration 230
Miscellaneous Security Configuration 230
General Options Setup 231
Finish 231

Chapter: 13 Implementing Clustering 233

Rules of Clustering 233
Cluster Definitions 235
Network Address Definitions 236
Alarm Server Definitions 236
Reports Server Definitions 238
Trends Server Definitions 239
I/O Server Definitions 240
Assigning tags to a cluster at Runtime 241

Chapter: 14 Building Redundancy Into Your System 245

I/O Server Redundancy 246
I/O Device promotion 247
Redundancy and Persistence 249
Data Path Redundancy 250
Multiple Device Redundancy (Standby Data Paths) 252
Network Redundancy 254
Configuring network redundancy 255
Alarms, Reports and Trends Server Redundancy 255
Alarms server redundancy 258
Reports server redundancy 259
Trends server redundancy 259
File server redundancy 260
FTP server redundancy 261
Redundancy of Standalone Systems 261

Chapter: 15 Communicating with I/O Devices 263

8
 Contents

The Role of the I/O Server 264

The Role of the I/O Device 264
The Role of the Transport Medium 265
The Role of the Protocol 266
Communication Configuration 267
Retrieving time-stamped data from field devices 270
Setting Up Communications 271
Preparing a Device 272
Preparing the I/O Server for Communication 272
Creating a communications test project 279
Using the Communications Express Wizard 281
Express Communications Wizard - introduction 282
Express Communications Wizard - Server selection 282
Express Communications Wizard - Device selection 282
Express Communications Wizard - I/O Device type 282
Express Communications Wizard - I/O Device communications selection 283
Express Communications Wizard - TCP/IP address 283
Express Communications Wizard - I/O Device address 283
Express Communications Wizard - I/O Device connection schedule 284
Express Communications Wizard - Link to external database 286
Express Communications Wizard - Serial device 288
Express Communications Wizard - Summary 288
Manually Configuring Communications 288
I/O Server Properties 289
Boards Properties 290
Ports Properties 291
I/O Devices Properties 292
I/O Devices Properties Extended 295
Working With Device Drivers 300
Determining Which Driver to Use 301
Installing a Driver Pack 301
The Driver Update Utility 302
Using the Driver Reference Help 303
Customizing Communication Using Citect.ini Parameters 304
Using a Disk I/O Device 304
Disk I/O Device setup 305
Redundant Disk I/O Devices 307
Disk I/O Device Errors 308
Using Memory Mode 309
Using Persisted I/O Memory Mode 310
Troubleshooting Device Communications 311
Gathering information about device communication 311
Debugging I/O Devices and Protocols 313
Debugging a COMx driver 313
Debugging a TCP/IP driver 317
Debugging a protocol driver using serial communications 319
Debugging proprietary board drivers 321
Serial Port Loop-Back Test 321
Contacting Technical Support 323

9
Contents

Performance Considerations 324

Caching data 324
Grouping registers 326
Remapping variables in an I/O Device 327
Remapping example 331
Advanced Driver Information 332
Variable (digital) limitations 332
Validating distributed project data for tag-based drivers 334
Write delay effects 334
Communicating with Remote Devices via Modems 336
Modems at the I/O Server 337
Modems at the I/O Device 338
Example configurations for modems at the I/O Server 338
I/O Device constraints for multi-dropping 343
Configuring multidrop remote I/O Devices 345
I/O Server redundancy for dial-up remote I/O Devices 349
Troubleshooting dial-up remote I/O Device communications 349
Alternative (backward compatibility) method of persistent connection 350
Scheduled Communications 351
Specifying a schedule 351
Writing to the scheduled I/O Device 352
Reading from the scheduled I/O Device 353

Chapter: 16 Tagging Process Variables 355

Tag Naming 356
Tag name syntax 356
Using structured tag names 357
Tag Extensions 362
The Quality Tag Element 364
Reading and Writing Tags 369
XML DataSource Schema 371
Tag Data Types 381
Configuring Variable Tags 382
Variable Tag Properties 383
Defining Variable Tag Names 387
Formatting numeric variables 389
Using arrays 392
Configuring Local Variables 395

Chapter: 17 Linking, Importing, and Exporting Tags 399

Linking tags 399
Breaking the link to the external data source 401
Deleting the I/O Device 401
Importing tags 402
Import variable tags properties 404
FastLinx for Mitsubishi Tag Import 405
Defining Variable Tag Names for Mitsubishi FastLinx 406
Unity Link Tag Import 409

10
 Contents

OPC Data Access Server Tag Browser 410

Exporting tags 410
Export Variable Tags properties 411
External data source 412
Format file 414
Format file layout 415
Field conversion 419
Recognizing format files 425
Unity Support Matrixes 427
Imported Tags 427
Exported Tags 429
Linked Tags 430

Chapter: 18 Defining and Drawing Graphics Pages 433

Creating a New Graphics Page 433
Animation points 434
New Dialog Box 434
Working with pages 434
Use Template (new page/template) dialog box 436
Open/Save As dialog box 437
Using Page Templates 438
Choosing a page style 439
Linking templates 439
Creating your own templates 439
New Style dialog box 441
Using a Browse Sequence 441
Specifying a Startup or Splash Page 442
Sizing the Page 443
Page (screen) resolution 443
Screen examples 444
Page size at runtime 450
Securing the window title bar 451
Defining Page Properties 451
Page Properties - General 452
Page Properties - Appearance 453
Page properties - Keyboard Commands 455
Page Properties - Events 457
Page Properties - Environment 459
Page Properties - Associations 459
Setting Default Page Settings 461
Page defaults 461
Understanding the Drawing Environment 462
Grids 463
Grid Setup dialog box 463
Guidelines 464
Guidelines Setup dialog box 465
Options 465
Colors 467

11
Contents

Edit Favorite Colors dialog box 468

Swap Color dialog box 471
Adjust colors dialog box 472
Zooming 473
Using libraries 474
Using symbols 476
Bitmaps 477
Import dialog box 479

Chapter: 19 Using Objects 481

Using groups 482
Reshaping objects 482
Reshaping a line object 483
Using bitmaps 483
Importing graphics 483
Object Properties 484
Appearance 484
Movement 485
Scaling 485
Fill 485
Input 486
Slider 486
Access 487
Metadata 487
Using Metadata 488
Passing Animation Point Metadata as Super Genie Associations 494
Manipulating Objects 495
Selecting objects 495
Moving objects 496
Resizing objects 496
Deleting objects 498
Locking/unlocking objects 498
Grouping objects 499
Copying and pasting objects 499
Changing the Overlap of Objects 500
Aligning objects 501
Rotating objects 502
Mirroring objects 503
Locate an object 503

Chapter: 20 Understanding Object Types 505

Free Hand Line Objects 505
Freehand Line Properties - Appearance (General) 506
Straight Line Objects 507
Straight Line Properties - Appearance (General) 507
Rectangle Objects 508
Rectangle Properties - Appearance (General) 509
Ellipse Objects 512

12
 Contents

Ellipse Properties - Appearance (General) 512

Polygon Objects 517
Polygon Properties - Appearance (General) 518
Pipe Objects 521
Pipe Properties - Appearance (General) 522
Text Objects 522
Text Properties - Appearance (General) 523
Text Properties - Appearance (Display Value) 524
Number Objects 529
Button Objects 529
Button Properties - Appearance (General) 530
Symbol Set Objects 532
Symbol Set Properties - Appearance General (On/Off) 533
Symbol Set Properties - Appearance General (Multi-state) 534
Symbol Set Properties - Appearance General (Array) 535
Symbol Set Properties - Appearance General (Animated) 537
Trend Objects 538
Trend properties 538
Insert Trend dialog box 541
Cicode Objects 541
Cicode Object Properties - Cicode (General) 542
Pasted Symbol Objects 542
Paste Symbol dialog box 543
Symbol Properties - Appearance (General) 544
Pasted Genie Objects 544
ActiveX Objects 545
Managing associated data sources 545
ActiveX Object Properties 546
Tag Association 546
ActiveX Object Properties - Appearance (Tag Association) 546
Object Identification 548
Object Properties - Access (Identification) 549
Database Exchange Control Objects 550

Chapter: 21 Defining Common Object Properties 551

3D Effects 551
Object Properties - Appearance (3D Effects) 552
Visibility 555
Object Properties - Appearance (Visibility) 555
Movement 556
Object Properties - Movement (Horizontal) 556
Object Properties - Movement (Vertical) 558
Object Properties - Movement (Rotational) 559
Group and object movement - examples 561
Scaling 564
Object Properties - Scaling (Horizontal) 564
Object Properties - Scaling (Vertical) 567
Fill Color 570

13
Contents

Object Properties - Fill Color (On/Off) 571

Object Properties - Fill Color (Multi-state) 572
Object Properties - Fill Color (Array) 574
Object Properties - Fill Color (Threshold) 576
Object Properties - Fill Color (Gradient) 578
Fill Level 580
Object Properties - Fill (Level) 581
Touch Commands 584
Object Properties - Input (Touch) 585
Keyboard Commands 587
Object Properties - Input (Keyboard Commands) 587
Sliders 590
Object Properties - Slider (Horizontal) 590
Object Properties - Slider (Vertical) 592
Object Properties - Slider (Rotational) 593
Access 595
General Access to Objects 595
Object Properties - Access (General) 595
Disable Access to Objects 597
Object Properties - Access (Disable) 598

Chapter: 22 Defining Commands and Controls 599

Touch commands 599
Keyboard commands 600
Slider controls 600
System Keyboard Commands 600
System keyboard command properties 601
Keyboard Keys 602
Keyboard keys properties 602
Keyboards 603
Defining Key Sequences for Commands 604
Using a hot key 605
Using variable data input 606
Passing multiple arguments 608
Passing keyboard arguments to functions 609
Configuring Page Menus 609
Menu Configuration Properties 610
Displaying Tags 612

Chapter: 23 Configuring and Processing Alarms 613

Configured alarms 613
Using alarm delay 614
Using custom alarm filters 614
Implementing queries that use custom alarm filters 615
Efficiency considerations 616
Alarm Categories 617
Alarm Category Properties 617
Digital Alarms 623

14
 Contents

Digital Alarm Properties 624

Multi-digital Alarms 627
Multi-digital Alarm Properties 628
Time-stamped Alarms 633
Time-stamped Alarm Properties 634
Analog Alarms 637
Analog Alarm Properties 638
Advanced Alarms 643
Advanced Alarm Properties 643
Time-stamped Digital Alarms 646
Time-stamped Digital Alarm Properties 647
Time-stamped Analog Alarms 650
Time-stamped Analog Alarm Properties 651
Formatting an Alarm Display 656
Including CitectSCADA data 656
Including fixed text 657
Displaying lists and tables 657
Variable data in alarm messages 657
Alarm display fields 658
Alarm summary fields 662
Changing the Order of the Alarm Summary Display 664
Using Alarm Properties as Tags 664
Supported alarm properties 665
Writing to alarm properties 670
Setting up alarm properties 671
Handling Alarms at Runtime 672
Using System Fonts 673
Fonts properties 674
Configuring Custom Color Fonts 676

Chapter: 24 Configuring Events 677

Events Properties 677
Running Events 679
Specifying times and periods 679
Using triggers 680

Chapter: 25 Using Accumulators 683

Accumulator Properties 683

Chapter: 26 Logging and Trending Data 687

Trending Data 687
Configuring trend tags 688
Trend Tag Properties 688
Trend Graphs 696
Creating trend pages 697
Trend interpolation 697
Printing Trend Data 698

15
Contents

Exporting Trend Data 699

Using Trend History Files 700
Storage method 701
Calculating disk storage 701
Reconfiguring history files 703
Using Path Substitution 703
Default path definitions 704
Debugging Trending 705

Chapter: 27 Understanding Statistical Process Control 707

Process Variation 708
Statistical Control 709
Process Capability 709
XRS Control Charts 710
CL, UCL and LCL 710
Interpreting the chart 711
Capability Charts 711
USL and LSL 712
Cp index 712
Cpk Index 712
Pareto Charts 712
Using Statistical Process Control (SPC) 713
SPC Tags 713
SPC tag properties 714
SPC Control Charts 721
XRS control chart 721
Configuring XRS charts 721
Capability charts 722
Configuring capability charts 722
Pareto Charts 722
Configuring Pareto charts 722
SPC Alarms 723
SPC Formulas and Constants 725
Control Chart Line Constants 729

Chapter: 28 Reporting Information 733

Configuring reports 733
Reports dialog box 734
Running Reports 736
Running a report on startup 736
Specifying times and periods 736
Using triggers 737
Using commands 738
Report Format File 738
Report example 740
Handling Communication Errors in Reports 741
Reporting errors in I/O Device data 742
Suppressing reports 743

16
 Contents

Chapter: 29 Using Labels 745

Using Arguments in Labels 747
Converting Values into Strings 748
Substituting Strings 749
Defining Labels 750

Chapter: 30 Using Devices 751

Using groups of devices 753
Using devices to read data 753
Configuring Devices 754
Formatting Data in the Device 758
Printer and ASCII devices format 759
dBASE and SQL database devices format 760
Using a database device 762
Using Device History Files 765
Using Command Fields 767
About Print Management 768
Using Equipment 769
Equipment Properties 769

Chapter: 31 Exchanging Data with Other Applications 771

Using DDE (Dynamic Data Exchange) 771
DDE conversations and client syntax 772
Setting up DDE conversations 773
DDE function types 775
Exchanging data via DDE 776
Connecting to the tag database using DDE 776
Posting select data using DDE 777
Writing values to a DDE application 778
Reading values from a DDE application 779
Using DDE with Microsoft Office applications 780
Network DDE 781
Starting network DDE services 781
Setting up network DDE shares 783
DDE Shares 784
Using DDE Trusted Shares 784
Using network DDE 785
Connecting to a network DDE shared application 786
Using the Citect Tags Excel macros 787
Using External Databases 788
dBASE databases 788
SQL databases 789
Using Structured Query Language 790
Connecting to an SQL database 791
Executing SQL commands 791
Using a transaction 793
Expressing dates and times in SQL 793

17
Contents

Using ODBC drivers 794

Installing the ODBC driver 794
About the ODBC driver 795
Setting up ODBC 796
Getting the correct syntax with ODBC 797
Programming style with ODBC 797
Comparing DDE with ODBC 798
ODBC compatibility 799
Using CitectSCADA as an ODBC server 801
Reading data from an access table with ODBC 803
Appending data with ODBC 804
Editing data with ODBC 805
Deleting rows from an Access table 805
Calling action queries with ODBC 806
Parameter queries 806
Access and Cicode date/time conversions 808
Using Microsoft Excel to Edit .dbf Tables 808
Functionality 810

Chapter: 32 Genies and Super Genies 813

Genies 813
Defining Substitutions for Genies 814
Configuring Genies 814
Using Genies 816
Maintaining a Genie 818
Using Genie Substitutions in Templates 819
Using structured tags with Genies 819
Super Genies 820
Defining Substitutions for Super Genies 821
Defining Associations for Super Genies 822
Configuring a Super Genie 822
Configuring a Super Genie as a Page 822
Configuring a Super Genie as a Library Object 824
Using a Super Genie Page 826
Using a Super Genie Library Object 827
Maintaining a Super Genie Page 831
Maintaining a Super Genie Library Object 832
Using Constants and Arrays with Super Genies 832
Nesting Super Genies 835
Super Genie areas 835
Super Genie Library Objects and Associations 835
Using structured tags with Super Genies 836
Hiding Graphics Objects 837
IFDEF macro 838

Chapter: 33 Working with Multi-Language Projects 839

Changing Languages 839
Marking text for language change 840

18
 Contents

Language databases 841

Multiple languages 842
Multiple projects 843
Changing languages at runtime 843
Logging data in different languages 843
ASCII and ANSI character sets 844
OEM character sets 844

Chapter: 34 Working with Multiple Monitors 847

Configuring Startup Pages for Multiple Monitors 847

Chapter: 35 Using OPC Server DA2.0 849

OPC Overview 849
CitectSCADA OPC Server 850
CitectSCADA OPC Server Installation 850
Configuring Remote Access to the OPC Server 853
Configure the OPC Server 853
Configure the OPC Client 858
Create a data group 863
Add data items to the group 863
Troubleshooting 863

Chapter: 36 Compiling and Running a Project 865

Compiling a Project 865
Incremental compilation 867
Debugging the compilation 867
Compilation options 868
Compile Error Properties 869
Compile Error Messages 870
Distributing the Project 879
Example of Using Run/Copy to Distribute Project Runtime Files 880
Running the System 882
Startup and runtime configuration 883
Running servers independently 884
Server Redirection Using Address Forwarding 884
Using an Alternative INI File 885
System tuning 886
Client Side Online Changes 888
Server Side Online Changes 889
Restarting the System Online 895
Restarting a networked system online 896
Running Your System Over the Internet 899
The Internet Display Client 900
The Internet server 900
Startup and runtime configuration 901
Server - client file updates 901
Software Protection 904

19
Contents

CiUSAFE dialog properties 904

Demo mode 905
Monitoring and Debugging the Runtime System 905
Gathering Runtime Information 906
Hardware alarms 906
Log Files 907
Configuring Logging 909
Adjusting Logging During Runtime 910
The Crash Handler 911
Using the Kernel 912
Displaying the kernel window 914
Inside the kernel 915
Using Kernel Commands 918
Kernel commands 919

Using the Web Client 953

Chapter: 37 The Web Client 955

System architecture 955
Getting Started 957
Preparing a Project for Deployment 957
Functionality limitations of the Web Client platform 958
Preparing a project's user files for delivery 960
Running the Web Deployment Preparation tool 961
Configuring a deployment 962
Creating a new deployment 963
Deploying a project from within CitectSCADA 965
Displaying a deployment 968
Editing an existing deployment 968
Updating a deployment to reflect project changes 969
Deleting a deployment 970
Implementing Multiple Language Support 970
How default languages are implemented 971
Using a language different to the current system locale setting 972
Implementing a non-default language 972
Web Client Upgrade Considerations 974
Frequently Asked Questions 975

Chapter: 38 Windows Language Codes 983

Using the Tab Style Page Templates 987

Chapter: 39 Introducing Tab Style Page Templates 989

Where to Find Information 989

Chapter: 40 Using Pages and Templates 991

20
 Contents

Common Navigation Functionality 991

Custom Tabbed Menus Toolbar 992
Navigation Toolbar 993
Alarm Toolbar 995
Normal Page Template 996
Blank Page Template 996
Alarm Page Templates 997
Common Functionality 997
Process Analyst Page Templates 1000
Statistical Process Control Trend Page Templates 1001
File Page Templates 1001

Chapter: 41 Creating a New Project 1003

Creating a Privileged User 1004
Running the Computer Setup Wizard 1005
Security Setup - Control Menu page 1005
Using Instant Trending 1005
Displaying a Project on Multiple Monitors 1006
Implementing Audible Alarms 1006
Creating Pages 1007
Creating new pages 1008
Creating Custom Menus 1008
Defining page menus 1009
Defining template popup menus 1011
Using Environment Variables in Tab Style Templates 1011

Using the CSV_Include Project 1013

Chapter: 42 Introducing CSV_Include 1015

Where to Find Information 1015

Chapter: 43 Using Pages and Templates 1017

Normal Page Template 1018
Alarm Page Templates 1018
Common functionality 1019
Trend Page Templates 1019
Common functionality 1020
File Page Templates 1024
Admin Tools Page Template 1024
Common Toolbars 1025
Navigation Toolbar 1026
Alarms Toolbar 1028

Chapter: 44 Creating a New Project 1031

Creating a Privileged User 1031

21
Contents

Running the Computer Setup Wizard 1032

Events Setup page 1032
Security Setup - Control Menu page 1033
Setting Up Instant Trending 1033
Displaying a Project on Multiple Monitors 1034
Implementing Audible Alarms 1034
Creating Pages 1035
Creating new pages 1036
Adding user assistance to a page 1036
Creating Custom Menus 1038
Menu Configuration tool 1038
Building custom menus 1039
Editing an item 1040
Creating an Alarms Group 1041
Creating a Trends Group 1042
Using Environment Variables 1043

Glossary 1045

Index 1069

22
Getting Started

This section contains information on CitectSCADA v7.20 and

describes the following:
Getting Technical Support
Upgrading to CitectSCADA v7.20
About CitectSCADA
Tools
Components of a project
Typical system scenarios

23
24
 Safety Information

Safety Information
Hazard categories and special symbols
The following symbols and special messages may appear in this manual or on the prod-
uct to warn of potential hazards or to call attention to information that clarifies or sim-
plifies a procedure.
A lightning bolt or ANSI man symbol in a "Danger" or "Warning" safety label on the
product indicates an electrical hazard which, as indicated below, can or will result in
personal injury if the instructions are not followed.
The exclamation point symbol in a safety message in a manual indicates potential per-
sonal injury hazards. Obey all safety messages introduced by this symbol to avoid pos-
sible injury or death.

Symbol Name

Lightning Bolt

ANSI man

Exclamation Point

DANGER indicates an imminently hazardous situation, which, if not avoided, will result in
death or serious injury.

WARNING indicates a potentially hazardous situation, which, if not avoided, can result in
death or serious injury.

CAUTION indicates a potentially hazardous situation which, if not avoided, can result in
minor or moderate injury.

25
Safety Information

CAUTION
CAUTION used without the safety alert symbol, indicates a potentially hazardous situation
which, if not avoided, can result in property damage.

Please Note
Electrical equipment should be installed, operated, serviced, and maintained only by
qualified personnel. No responsibility is assumed by Schneider Electric (Australia) Pty.
Ltd. for any consequences arising out of the use of this material.

Before You Begin

CitectSCADA is a Supervisory Control and Data Acquisition (SCADA) solution. It facil-
itates the creation of software to manage and monitor industrial systems and processes.
Due to CitectSCADA's central role in controlling systems and processes, you must appro-
priately design, commission, and test your CitectSCADA project before implementing it
in an operational setting. Observe the following:

UNINTENDED EQUIPMENT OPERATION

Do not use CitectSCADA or other SCADA software as a replacement for PLC-based control pro-
grams. SCADA software is not designed for direct, high-speed system control.

Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

LOSS OF CONTROL

l The designer of any control scheme must consider the potential failure modes of control
paths and, for certain critical control functions, provide a means to achieve a safe state
during and after a path failure. Examples of critical control functions are emergency
stop and overtravel stop.
l Separate or redundant control paths must be provided for critical control functions.
l System control paths may include communication links. Consideration must be given to
the implications of unanticipated transmission delays or failures of the link.*
l Each implementation of a control system created using CitectSCADA must be individ-
ually and thoroughly tested for proper operation before being placed into service.
Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

* For additional information, refer to NEMA ICS 1.1 (latest edition), "Safety Guidelines
for the Application, Installation, and Maintenance of Solid State Control".

26
Chapter: 1 Getting Technical Support
There are various support options to help you get the most from this product.
l If you have questions about using CitectSCADA, consult the extensive online Help to
answer your questions. You can use the Contents list to find the section you're inter-
ested in, enter an item into the Index, or enter an item using the Search tab.
l If you seek more technical information than is provided in the online Help, check the
knowledge base.
If you cannot find the information you need, you can obtain technical support and Train-
ing. Consulting services are also available upon request.
See Also
Technical Support
Contact information

CitectSCADA Technical Support

Please note the following about technical support for your CitectSCADA product.
Technical Support
Citect Maintenance and Support Agreements are available for purchase. To purchase a
Maintenance and Support Agreement, price of which is determined by the list price of
your system, you need to contact your local Schneider Electric (Australia) Pty. Ltd. rep-
resentative.
Schneider Electric (Australia) Pty. Ltd. offers a range of Support services; for further infor-
mation visit http://www.citect.com/support. Upon receipt of your order for a Main-
tenance and Support Agreement, you will receive a site number and a list of dongle
serial numbers, which you need to quote when you contact Support. A site or dongle
serial number enables the Customer Support team to provide quality service product by
logging and tracking your Customer Service Requests (CSRs).
Before Calling Customer Support
Fill out the online CitectSCADA CitectHMI Support Request form, found at the web site
http://www.citect.com/support.
If you are unsure of which contact details to use, email: [email protected].

27
Chapter: 1 Getting Technical Support

Training
Various training facilities are also available. Contact your local Citect distributor for
more information.
See Also
Contact information

Contact information
For contact information in your region, consult the support web site at:
http://www.Citect.com/support

28
Chapter: 2 What's New in CitectSCADA v7.x
This section describes new CitectSCADA features and enhancements for v7.20. For the
purposes of continuity, this section also describes the features that were added for the
CitectSCADA v7.0 and v7.10 releases.
Introduced in v7.0
Introduced in v7.10
Introduced in v7.20
For details on how to upgrade an existing project to run in v7.20, refer to Upgrading to
V7.20.

What's New in CitectSCADA v7.0

CitectSCADA v7.0 incorporates the following new features.
Introduced in v7.0:
l The Migration Tool
l Clustering
l Local Variables
l Publish Alarm Property
l Memory Mode
l Client-side Online Changes
l Publisher-Subscriber Model
l Dual Network Support
l Project-Based Network Configuration
For changes to:
l Citect.ini parameters, see Citect.ini Parameters in Version 7.0.
l Cicode functions, see Cicode Functions in Version 7.0.
l CtAPI functions, see CtAPI Functions in Version 7.0.
l Kernel commands, see Kernel Commands in Version 7.0.
For details on how to configure an existing project to run in v7.20, refer to Upgrading.

29
Chapter: 2 What's New in CitectSCADA v7.x

See Also

What's New in CitectSCADA v7.x

The Migration Tool

The Migration Tool is a separate application which has to be manually run after the
automatic upgrade has been executed, and initiated by you after you have prepared the
project for final migration. This tool will accommodate the important changes in project
functionality which are incorporated in version 7.0.
See Also
Migration Tool

Clustering
Clustering allows you to group different sets of the runtime components within a single
project, allowing multiple independent systems to be monitored and controlled.
There are countless variations in how a clustered system can be configured. The most
appropriate configuration will depend on the requirements for the solution to be
deployed and the environment in which it is being deployed. For more information see
Typical system scenarios.
See Also
Included projects
Implementing Clustering

Local Variables
Local variables allow you to store data in memory when you start your runtime system.
They are created each time the system starts, and therefore do not retain their values
when you shut down.
Local variables are useful when you need each process to have a separate copy of the
data. Each process has its own copy of each local variable configured in the project, and
the values in a local variable are available only to the process that wrote them.
See Also
Configuring Local Variables

30
 Chapter: 2 What's New in CitectSCADA v7.x

Publish Alarm Property

Alarm devices were defined as devices with their Protocol field set to "Alarm". The func-
tion of these devices are now configured on an Alarm Server by setting the "Publish
Alarm Properties" property to True.
See Also
Alarm Server Definitions

Memory Mode
I/O Devices can now be configured to run in memory mode:
l An I/O Device running in memory mode is created in memory and its values stored
in memory at runtime.
l Devices using memory mode are not connected to any hardware, and write their
values to a cache. Memory mode is useful when you are configuring a system for the
first time, as you can design and test your system before connecting a physical I/O
Device.

Note: Memory mode replaces Memory I/O Devices, which are no longer supported.
Devices configured as Memory I/O Devices will be converted to local variables dur-
ing the upgrade to v7.20.

See Also
Using Memory Mode

Client-side Online Changes

The following live changes can now be made to the project without restarting clients:
l I/O Devices (restart the I/O Server)
l Tags (restart the I/O Server)
l Alarms (restart the Alarm Server)
l Trends (restart the Trends Server)
l Reports (restart the Reports Server)
l Accumulators (restart the Reports Server)
Clients only require that graphics, code and communications configurations are
deployed to them. Other configuration information is deployed to the appropriate server.

Project changes are still deployed as before

31
Chapter: 2 What's New in CitectSCADA v7.x

l Manually
l Run/Backup Run/Copy
l FTP (IDC)
l HTTP (Web Client)
See Also
Improved Client Side Online Changes

Publisher-Subscriber Model
CitectSCADA now uses a Publisher-Subscriber data acquisition model. Client computers
subscribe to configured tags and receive notification when the tag values change. Cicode
functions can also be triggered by the change of a tag, removing the need to poll, and
improving the efficiency of the system.
See Also
TagSubscribe
TagUnsubscribe

Dual Network Support

Previous CitectSCADA versions have been able to support redundant networks via Net-
BIOS. From version 7.0 users can only use TCP/IP for network configuration and can
specify multiple IP addresses for each server, providing native support for network
redundancy.

Project-Based Network Configuration

In version 7.0, the project topology is embedded in the project, and network con-
figuration can be performed from within the Project Editor. Servers and their IP
addresses are set up in the Network Addresses dialog in the Project Editor.
This means that physical computers in the system can easily be changed. As long as the
IP address or computer name of the new machine is the same as the one being replaced,
the new computer will be able to immediately take the same role.

Citect.ini Parameters in version 7.0

The following sections detail the changes made to Citect.ini parameters in Citect-
SCADAversion 7.0:

32
 Chapter: 2 What's New in CitectSCADA v7.x

l New Parameters
l Obsolete Parameters

New Parameters
The following parameters are new in version 7.0. For a complete list of the system
parameters, refer to the Parameters help file.
Alarm Parameters:

[Alarm.ClusterName.ServerName]Clusters Sets which clusters this Alarm Server

process connects to at startup

[Alarm.ClusterName.ServerName]CPU Sets the CPU that the Alarm Server

process is assigned to

[Alarm.ClusterName.ServerName]Events The list of events that this Alarm

Server process enables

[Alarm.Clu- Determines the Cicode function to run

sterName.ServerName]ShutdownCode when Alarm Server process shuts
down

[Alarm.Clu- Determines the Cicode function to run

sterName.ServerName]StartupCode when Alarm Server process starts up

Note: The default alarm property write behavior was to write the new value to
DBF/RDB. This has changed in version 7.0 onwards. Refer to the parameter [Alarm]Us-
eConfigLimits.
Backup Parameters:

[Backup]SaveiniFiles Determines whether the "Save ini files" checkbox is checked by

default during Backup.

Client Parameters:

[Client]Clusters Selects which clusters the client is connected to at

startup.

[Client]ComputerRole Specifies the role of the computer

[Client]Events Sets the events to be enabled on the client.

[Client]ForceClient Starts only the client process, and connects to a con-

figured Citect servers using a network connection.

33
Chapter: 2 What's New in CitectSCADA v7.x

[Client]FullLicense Specifies that a Control Client will use a full license

[Client]ShutdownCode Determines the Cicode function to run when Dis-

playClient component shuts down.

[Client]StartupCode Determines the Cicode function to run when Dis-

playClient component starts up.

[Client]Wai- Specifies that connection to a server will wait until it

tForConnectAtStartup can establish a connection to the server processes
before starting up.

CtCicode Parameters:

[CtCicode]FastFormat Controls whether fast formatting is used in the Cicode Editor

CtEdit Parameters:

[CtEdit]Config The directory where the CitectSCADA configuration files such as

citect.ini are located.

[CtEdit]Logs The directory where the CitectSCADA log files are located.

Dial Parameters:

[Dial]Mi- Specifies how many consecutive scheduled dial attempts

ssedScheduleTolerance can be missed before the cache becomes stale

Driver Parameters:

[<DriverName>]Ove- Determines whether to override the protection mechanism

rriderOSProtection built-in to the I/O Server for drivers that may not be compatible
with Windows Vista.

General Parameters:

[Gen- Determines whether CitectSCADA runs as a multi-process or sin-

eral]Multiprocess gle-process application.

IOServer Parameters:

[IOServer.ClusterName.ServerName]Clusters Sets the clusters that the I/O Server

process will connect to at startup

[IOServer.ClusterName.ServerName]CPU Sets the CPU that the I/O Server

process is assigned to

34
 Chapter: 2 What's New in CitectSCADA v7.x

[IOServer.ClusterName.ServerName ]Events The list of events that this I/O

Server process enables

[IOServer.Clu- Determines the Cicode function to

sterName.ServerName]ShutdownCode run when I/O Server process shuts
down

[IOServer.Clu- Determines the Cicode function to

sterName.ServerName]StartupCode run when I/O Server process starts
up

Report Parameters:

[Report.ClusterName.ServerName]Clusters Sets the clusters this Reports Server

process will connect to at startup

[Report.ClusterName.ServerName]CPU Sets the CPU that this Reports Server

process is assigned to

[Report.ClusterName.ServerName]Events The list of events that this Reports

Server process enables

[Report.Clu- Determines the Cicode function to run

sterName.ServerName]ShutdownCode when this Reports Server process
shuts down

[Report.Clu- Determines the Cicode function to run

sterName.ServerName]StartupCode when this Reports Server process
starts up

Trend Parameters:

[Trend.ClusterName.ServerName]Clusters Sets the clusters this Trends Server

process will connect to at startup

[Trend.ClusterName.ServerName]CPU Sets the CPU that the Trends Server

process is assigned to

[Trend.ClusterName.ServerName]Events The list of events that this Trends

Server process enables

[Trend.Clu- Determines the Cicode function to run

sterName.ServerName]ShutdownCode when Trends Server process shuts
down

[Trend.Clu- Determines the Cicode function to run

sterName.ServerName]StartupCode when Trends Server process starts up

35
Chapter: 2 What's New in CitectSCADA v7.x

Obsolete Parameters
The following parameters are no longer supported in version 7.0:
Alarm Parameters:

[Alarm]CPU Sets the CPU that the Alarm Server component is assigned to

[Alarm]Primary Determines if this Alarm Server is the Primary Alarm Server

[Alarm]Process Sets the CitectSCADA process the Alarm Server component is

assigned to

[Alarm]Server Determines whether this computer is an Alarm Server

Client Parameters:

[Client]Display Sets the CitectSCADA computer as a Control Client

[Client]Manager Sets the CitectSCADA computer as a View-only Client

[Client]Primary The name of the primary CitectSCADA server

[Client]Process Sets the CitectSCADA process the Control Client component is

assigned to

[Client]Standby The name of the standby CitectSCADA server

Code Parameters:

[Code]AlarmShutdown Determines the Cicode function to run when Alarm Server com-
ponent shuts down

[Code]AlarmStartup Determines the Cicode function to run when Alarm Server com-
ponent starts up

[Code]AutoReRead Controls whether the ReRead() function is automatically called

[Code]I- Determines the Cicode function to run when I/O Server com-
OServerShutdown ponent shuts down

[Code]IOServerStartup Determines the Cicode function to run when I/O Server com-
ponent starts up

[Code]Process Sets the process a code component is assigned to

36
 Chapter: 2 What's New in CitectSCADA v7.x

[Code]ReportShutdown Determines the Cicode function to run when Reports Server

component shuts down

[Code]ReportStartup Determines the Cicode function to run when Reports Server

component starts up

[Code]Shutdown Determines the Cicode function to run when Control Client

component shuts down

[Code]Startup Determines the Cicode function to run when Control Client

component starts up

[Code]TrendShutdown Determines the Cicode function to run when Trends Server

component shuts down

[Code]TrendStartup Determines the Cicode function to run when Trends Server

component starts up

DNS Parameters:

[DNS]<Server name> Determines the IP address (or fully qualified host name) of the
primary I/O Server

Event Parameters:

[Event]Alarm The classes of events to be enabled by the Alarm Server

[Event]IOServer The classes of events to be enabled by the I/O Server

[Event]Name The classes of events assigned to the Name entry to be ena-

bled

[Event]Report The classes of events to be enabled by the Reports Server

[Event]Trend The classes of events to be enabled by the Trends Server

General Parameters:

[General]BadOptimise Determines whether certain strings are replaced with

labels on compile

[Gen- Checks if a project is currently running on the local

eral]CitectRunningCheck machine when a compile is triggered

IOServer Parameters:

37
Chapter: 2 What's New in CitectSCADA v7.x

[IOServer]BlockWrites Determines whether CitectSCADA will try to block optimize

writes to I/O Devices. The IOserver will not block writes

[IOServer]CPU Sets the CPU that the I/O Server component is assigned to

[IOServer]Name The name of the default I/O Server

[IOServer]Process Sets the CitectSCADA process the I/O Server component is

assigned to

[IOServer]SaveBackup This parameter has been superseded by SaveNetwork

[IOServer]Server Determines whether this computer is an I/O Server

LAN Parameters:

[LAN]Bridge Determines the bridge level

[LAN]CancelOnClose For users with Novell NetBIOS emulator issues

[LAN]Disable Enables/disables CitectSCADA from the LAN

[LAN]GroupName Determines whether CitectSCADA uses the group name

'CITECT STATION50' or the computer name specified by the
[Lan]Node parameter.

[LAN]KillPiggyBackAck Controls whether CitectSCADA will try to optimize network pro-

tocols which support piggyback ACK

[LAN]LanA Defines the protocol stack that CitectSCADA uses for NetBIOS
communication

[LAN]NetBIOS Enables/disables NetBIOS

[LAN]NetTrace Determines whether the NetBIOS window is enabled on

startup

[LAN]NetTraceBuff Sets the number of trace buffers.

[LAN]NetTraceErr Enables the error mode of the NetBIOS window

[LAN]NetTraceLog Enables the logging mode of the NetBIOS window

[LAN]Poll Puts CitectSCADA LAN communications into polled mode

38
 Chapter: 2 What's New in CitectSCADA v7.x

[LAN]RemoteTimeOut The timeout period for remote I/O Device write requests from
a Control Client to the I/O Server

[LAN]Retry The number of times to retry establishing communications

after a timeout - before an alert message is generated

[LAN]SendTimeOut The timeout to send a network packet across the network

[LAN]SesRecBuf The number of receive NetBIOS Control Blocks (NCBs) that

CitectSCADA uses for every session

[LAN]SesSendBuf The number of send NetBIOS control blocks that CitectSCADA

uses for every session

[LAN]TimeOut The timeout to send a network packet across the network

Proxi Parameters:

[Proxi]<I/O Server Defines a list of proxy server associations

name>

Report Parameters:

[Report]Primary Determines if this Reports Server is the Primary Reports

Server

[Report]Process Sets the CitectSCADA process the Reports Server component

is assigned to

[Report]Server Determines whether this computer is a Reports Server

Server Parameters:

[Server]Name The name of the CitectSCADA server

Trend Parameters:

[Trend]BlockByIODevice Verifies that I/O problems causing gaps for a trend

tag do not cause gaps for every trend tag

[Trend]CPU Sets the CPU that the Trends Server component is

assigned to

[Trend]Process Sets the CitectSCADA process the Trends Server com-

ponent is assigned to

39
Chapter: 2 What's New in CitectSCADA v7.x

[Trend]Redundancy Enables/disables trend redundancy action

[Trend]Server Determines whether this computer is a Trends

Server

[Trend]Sta- Reduces network traffic by spacing out trend sample

ggerRequestSubgroups requests

Cicode Functions in v7.0

Some Cicode functions have been introduced, modified, deprecated or removed. The fol-
lowing sections detail the changes made to these functions:

New Functions
Miscellaneous Functions

AccControl Controls accumulators for example motor run hours.

AccumBrowseClose Closes an accumulator browse session.

AccumBrowseFirst Gets the oldest accumulator entry.

AccumBrowseGetField Gets the field indicated by the cursor position in the browse
session.

AccumBrowseNext Gets the next accumulator entry in the browse session.

Accum- Returns the number of records in the current browse ses-

BrowseNumRecords sion.

AccumBrowseOpen Opens an accumulator browse session.

AccumBrowsePrev Gets the previous accumulator entry in the browse session.

ProcessIsClient Determines if the currently executing process contains a

Client component

ProcessIsServer Determines if the currently executing process contains a par-

ticular server component.

ServiceGetList Gets information about services running in the component

40
 Chapter: 2 What's New in CitectSCADA v7.x

calling this function.

Alarm Functions:

AlarmDspLast Displays the latest unacknowledged alarms.

AlmSummaryAck Acknowledges the alarm at the current cursor position in an

active data browse session.

AlmSummaryClear Clears the alarm at the current cursor position in an active

data browse session.

AlmSummaryClose Closes an alarm summary browse session.

AlmSummaryCommit Commits the alarm summary record to the alarm summary

device.

AlmSummaryDelete Deletes alarm summary entries from the browse session.

AlmSummaryDeleteAll Deletes alarm summary entries from the browse session.

AlmSummaryDisable Disables the alarm at the current cursor position in an active

data browse session.

AlmSummaryEnable Enables the alarm at the current cursor position in an active

data browse session.

AlmSummaryFirst Gets the oldest alarm summary entry.

AlmSummaryGetField Gets the field indicated by the cursor position in the browse
session.

AlmSummaryLast Places the data browse cursor at the latest summary record
from the last cluster of the available browsing cluster list.

AlmSummaryNext Gets the next alarm summary entry in the browse session.

AlmSummaryOpen Opens an alarm summary browse session.

AlmSummaryPrev Gets the previous alarm summary entry in the browse ses-
sion.

Alm- Sets the value of the field indicated by the cursor position in
SummarySetFieldValue the browse session.

AlmTagsAck Acknowledges the alarm tag at the current cursor position in

an active data browse session.

41
Chapter: 2 What's New in CitectSCADA v7.x

AlmTagsClear Clears the alarm tag at the current cursor position in an active
data browse session.

AlmTagsDisable Disables the alarm tag at the current cursor position in an

active data browse session.

AlmTagsEnable Enables the alarm tag at the current cursor position in an

active data browse session.

AlmTagsFirst Gets the oldest alarm tags entry.

AlmTagsGetField Gets the field indicated by the cursor position in the browse
session.

AlmTagsNext Gets the next alarm tags entry in the browse session.

AlmTagsNumRecords Returns the number of records in the current browse ses-

sion.

AlmTagsOpen Opens an alarm tags browse session.

AlmTagsPrev Gets the previous alarm tags entry in the browse session.

Super Genie Functions

Ass- Gets association information about the current Super Genie from the
GetProperty datasource

AssGetScale Gets scale information about the associations of the current Super
Genie from the datasource

AssInfoEx Replaces the AssInfo function and supports online changes.

Cluster Functions

ClusterActivate Allows the user to activate an inactive cluster.

Clus- Allows the user to deactivate an active cluster.

terDeactivate

ClusterFirst Allows the user to retrieve the first configured cluster in the project.

ClusterIsActive Allows the user to determine if a cluster is active.

ClusterNext Allows the user to retrieve the next configured cluster in the project.

42
 Chapter: 2 What's New in CitectSCADA v7.x

Clus- Allows the user to determine which servers are defined for a given
terServerTypes cluster.

ClusterStatus Allows the user to determine the connection status from the client to
a server on a cluster.

Clus- Allows the user to deactivate an active cluster at the same time as
terSwapActive activating an inactive cluster.

I/O Device Functions

SubscriptionAddCallback Adds a callback function to a tag subscription.

SubscriptionGetAttribute Reads an attribute value of a tag subscription.

Sub- Removes a callback function from a tag subscription

scriptionRemoveCallback

TagGetProperty Gets a property for a variable tag from the datasource.

TagGetScale Gets the value of a tag at a specified scale from the data-
source

TagSubscribe Subscribes a tag for periodic monitoring and event han-

dling.

TagUnsubscribe Unsubscribes a tag for periodic monitoring and event han-

dling.

Tag Functions

TagInfoEx Supports online changes.

TagWri- Opens the tag write event queue.

teEventQue

Task Functions

TaskCluster Gets the name of the cluster context in which the current task is execut-
ing

Trend Functions

TrnBrowseClose Closes a trend browse session.

43
Chapter: 2 What's New in CitectSCADA v7.x

TrnBrowseFirst Gets the oldest trend entry.

TrnBrowseGetField Gets the field indicated by the cursor position in the browse ses-
sion.

TrnBrowseNext Gets the next trend entry in the browse session.

TrnBrow- Returns the number of records in the current browse session.

seNumRecords

TrnBrowseOpen Opens a trend browse session.

TrnBrowsePrev Gets the previous trend entry in the browse session.

TrnGetCluster Gets the name of the cluster the trend graph is associated with.

TrnGetPenComment Gets the comment of a trend pen.

Report Functions

Rep- Retrieves the name of the cluster the report is running on.
GetCluster

ModifiedFunctions
Alarm Functions

AlarmAck Acknowledges alarms.

AlarmAckRec Acknowledges alarms by record number

AlarmActive Determines if any alarms are active in the user's area.

AlarmClear Clears acknowledged, inactive alarms from the active alarm list.

AlarmClearRec Clear an alarm by its record number

AlarmDelete Deletes alarm summary entries.

AlarmDisable Disables alarms.

AlarmDisableRec Disables alarms by record number

AlarmDsp Displays alarms.

44
 Chapter: 2 What's New in CitectSCADA v7.x

AlarmDspLast Displays the latest unacknowledged alarms.

AlarmEnable Enables alarms.

AlarmEnableRec Enables alarms by record number

AlarmFirstTagRec Searches for the first occurrence of an alarm tag, name, and
description

AlarmGetDelayRec Gets the delay setting for an alarm via the alarm record number

AlarmGetFieldRec Gets alarm field data from the alarm record number

Alarm- Gets the thresholds of analog alarms by the alarm record number
GetThresholdRec

AlarmNextTagRec Searches for the next occurrence of an alarm tag, name, and
description.

Alarm- Activates a time-stamped digital or time-stamped analog alarm

NotifyVarChange

AlarmSumAppend Appends a new blank record to the alarm summary.

AlarmSumCommit Commits the alarm summary record to the alarm summary

device.

AlarmSumDelete Deletes alarm summary entries.

AlarmSumFind Finds an alarm summary index for an alarm record and alarm on
time.

AlarmSumFirst Gets the oldest alarm summary entry.

AlarmSumGet Gets field information from an alarm summary entry.

AlarmSumLast Gets the latest alarm summary entry.

AlarmSumNext Gets the next alarm summary entry.

AlarmSumPrev Gets the previous alarm summary entry.

AlarmSumSet Sets field information in an alarm summary entry.

AlarmSumSplit Duplicates an alarm summary entry.

45
Chapter: 2 What's New in CitectSCADA v7.x

AlarmSumType Retrieves a value that indicates a specified alarm's type.

I/O Device Functions

DriverInfo Provides information about the driver for a particular I/O Device.

IODe- Provides control of individual I/O Devices.

viceControl

IODeviceInfo Gets information on an I/O Device.

Miscellaneous Functions

AccControl Controls accumulators for example motor run hours.

ServerInfo Gets client and server information.

ServerInfoEx Gets client and server information from a specified process in a mul-
tiprocessor environment.

Shutdown Ends CitectSCADA's operation.

Report Functions

Rep- Gets report control information.

GetControl

Report Runs a report.

Rep- Sets report control information.

SetControl

SPC Functions

SPCAlarms Returns the status of the specified SPC alarm.

SPCPro- Gets the process mean, range and standard deviation overrides.
cessXRSGet

SPCPro- Sets the process mean, range and standard deviation overrides.
cessXRSSet

SPCSpecLimitGet Gets the specification limits (USL and LSL) for the specified tag.

46
 Chapter: 2 What's New in CitectSCADA v7.x

SPCSpecLimitSet Sets the specification limits (USL and LSL) for the specified tag.

SPCSub- Gets the size of a subgroup for the specified SPC tag.
groupSizeGet

SPCSub- Sets the subgroup size for the specified SPC tag.
groupSizeSet

Super Genie Functions

Ass Associates a variable tag with a Super Genie.

AssPage Associates up to eight variable tags with a Super Genie and displays the
Super Genie in the current window.

AssPopUp Associates up to eight variable tags with a Super Genie and displays the
Super Genie in a popup window.

AssTag Associates a variable tag with the current Super Genie. The association
will be created for the current Super Genie only, and will only come into
effect after you re-display the Super Genie.

AssVarTags Associates up to eight variable tags with a Super Genie. This asso-
ciation is only made for the next Super Genie you display (either in the
current window or in a new window). You can use this function repeat-
edly to associate more than 8 variable tags to a Super Genie.

AssWin Associates up to eight variable tags with a Super Genie, and displays
the Super Genie in a new window.

Tag Functions

Tag- This function reads a property of a variable tag from the datasource
GetProperty

TagGetScale Gets the value of a tag at a specified scale from the datasource

TagRamp This function will increment a Tag by the amount defined by iPercentInc

TagRead Reads a variable from the I/O Device

TagScaleStr Gets the value of a tag at a specified scale

TagWrite Writes to an I/O Device variable by specifying the variable tag.

Task Functions

47
Chapter: 2 What's New in CitectSCADA v7.x

MsgOpen Opens a message session with a CitectSCADA server or client.

Trend Functions

TrendDsp- Displays the tag name of the current pen.

CursorTag

TrnAddHistory Restores an old history file to the trend system.

TrnDelHistory Deletes an old history file from the trend system.

TrnEventSetTable Sets trend data from a table, for a specified trend tag.

TrnE- Sets event trend data and time data (including milliseconds) for a
ventSetTableMS specified trend tag.

TrnFlush Flushes the trend to disk.

TrnGetDefScale Gets the default engineering zero and full scales of a trend tag.

TrnGetPen Gets the trend tag of a pen.

TrnGetTable Stores trend data in an array.

TrnInfo Gets the configured values of a trend tag.

TrnNew Creates a new trend at run time.

TrnSelect Sets up a page for a trend.

Window Functions

WinCopy Copies the active window to the Windows clipboard.

WinFile Writes the active window to a file.

WinNewAt Opens a new display window at a specified location, with a selected

page displayed.

WinPrint Prints the active window.

Osolete Functions
Cluster Functions

48
 Chapter: 2 What's New in CitectSCADA v7.x

Clus- Returns the names of the primary and standby cluster servers.
terGetName

Clus- Connects to a specific cluster server.

terSetName

Display Functions

DspCol Displays a color at an AN.

Task Functions

ReRead Causes CitectSCADA to re-read the I/O Device data associated with the
current Cicode task.

Tags are now subscribed at the start of a function and updated tag
values are sent to the subscribing function.

Tag subscriptions are made at the update rate of:

l the graphics page if called from a page

l the default subscription rate as determined by [Code]TimeData in
the Parameters online help if called from Cicode (default 250 ms)
l the update rate requested of a task created using TaskNewEx
l the update rate requested of a subscription created using Tag-
Subscribe
Verify that the subscription update rate matches the requirements of
your function.

After removing ReRead from looping code you may need to extend the
period of the Sleep function.

This is to replace the pause ReRead created while it read the tag values.

CtAPI Functions in v7.0

The following section details the changes made to CtAPI functions in CitectSCADA v7.0.

Obsolete Functions
Previously available "Point" related functions are now no longer available, and if used
will detect and return an error indicating that they are not supported. In order to obtain
the same result as was previously invoked by those function, replace them with the Tag
based equivalent using the appropriate Tag arguments and conditions.
The "point" functions that are no longer available are listed below along with their
replacement functions:

49
Chapter: 2 What's New in CitectSCADA v7.x

Function Replacement

ctPointGetProperty ctTagGetProperty

ctPointNew ctListNew or ctTagWrite and ctTagRead

ctPointRead ctTagRead or ctListRead with ctListData

ctPointWrite ctTagWrite or ctListWrite

If you are using the point functions on single tags, use the ctTagRead, ctTagWrite func-
tions instead. If you are building up multiple tags into one point, use ctListNew and add
tags to the list through ctListAdd. Then use ctListWrite, ctListRead and ctListData to
write and read from the tags.
The following functions are not relevant to tag based operations. They are obsolete and
there is no replacement function.
l ctPointBitShift
l ctPointClose
l ctPointCopy
l ctPointDataSize
l ctPointToStr
l ctStrToPoint
l ctTagToPoint

What's New in CitectSCADA v7.10

CitectSCADA v7.10 incorporates the following new features.
Introduced in v7.10:
l Windows® Integrated Security
l CitectSCADA Security Enhancements
l Multi-Signature Support
l Edit DBF Files in Microsoft® Excel
l Enhanced Driver Installation
l New Font Selection for Graphics Button
l Microsoft® Windows VistaTM Support
l New Location for Configuration and Project Files

50
 Chapter: 2 What's New in CitectSCADA v7.x

l New Alarm Field Enhancements

l New Time Synchronization Service
For changes to:
l Citect.ini parameters, see Citect.ini Parameters in Version 7.10.
l Cicode functions, see Cicode Functions in Version 7.10.
See Also
What's new in CitectSCADA v7.x

CitectSCADA Security Enhancements

The CitectSCADA v7.20 release includes changes that are designed to reduce the secu-
rity exposure of the product from external threats via the network. The product features
that have been affected are detailed below. Please review the list to understand what
effect they may have on your system with regards to the upgrade and design process.
Managing surface area

A set of new configuration parameters have been added to provide control over the
CitectSCADA network interfaces. These parameters help you protect your system by
allowing control over unused features of the product. The following services can be ena-
bled / disabled: DDE, Remote CTAPI, ODBC, OLEDB and FTP.These services are dis-
abled by default.
User login necessary for control actions

A user is now necessary to be configured and logged in to CitectSCADA to allow the dis-
play process to perform a tag write (control) action. Design CitectSCADA projects to
avoid Cicode task that perform tag writes that are not issued by a user.
We advise that projects be configured to take advantage of the change to provide
increased system security protection. If your system has existing network security pro-
tection in place and does not require the additional security protection, it can be turned
off using the following parameters to avoid the impact of the changes:
Parameter for the client/display node: See [LAN] SecureLogin in the Parameters help file
for more information.
Parameter for the server node: See [LAN] AllowLegacyConnections in the Parameters
help file for more information. (As part of CitectSCADA7.20 this parameter was made
obsolete)
These parameters may be necessary during an upgrade process when there is a mix of
old and new version CitectSCADA nodes in a running system.
See Also
System Parameters

51
Chapter: 2 What's New in CitectSCADA v7.x

Windows Integrated Security

In CitectSCADA you now have the ability to incorporate CitectSCADA users and secu-
rity options with the standard Windows security system. Of course you can still use the
CitectSCADA native security if you prefer to define users in the project and logon to
CitectSCADA runtime.
Using the integrated Windows security feature, the Windows user can logon to Citect-
SCADA runtime with runtime privileges configured within the project.
See Also
Using Windows Security

Multi-Signature Support
CitectSCADA now provides the facility for up to four users to approve an action or tag
write operation using the new Cicode functions MultiSignatureForm and Mul-
tiSignatureTagWrite.
Two further Cicode functions, VerifyPrivilegeForm and VerifyPrivilegeTagWrite, enable
you to restrict access to a specific action or tag write for a user with a specific set of priv-
ileges.

Edit .dbf Files in Microsoft® Excel

CitectSCADA allows you to edit and save .dbf files (tables) used in CitectSCADA by
opening them in Microsoft® Office Excel®.
Microsoft Office Excel® 2007 does not allow you to save files in .dbf format though you
may open and edit them using the File > Open command. In order to overcome this lim-
itation CitectSCADA includes an Add-In for Microsoft Excel called ProjectDBFAddIn.
When this Add-In is loaded into Excel, it allows you to browse, open, edit and save
CitectSCADA .dbf files in the correct format.
See Also

Using Microsoft Excel to Edit .dbf Tables

52
 Chapter: 2 What's New in CitectSCADA v7.x

Enhanced Driver Installation

The installation of CitectSCADA prior to v7.10 installed the communication drivers auto-
matically with the product. From v7.10, the installation of these drivers is performed at
the final stage of the product installation using a separate installation process. This
installation process allows you to select individual drivers that you want to install, spe-
cific to your system and its I/O Devices.
There are certain drivers that the product installation will install that are necessary for
CitectSCADA to function correctly. These will be installed automatically as in previous
releases.
If you are using the Microsoft® Windows Vista™ operating system verify that any driv-
ers which you select to install are identified as being compatible with that operating sys-
tem. If you select any driver that is not yet identified as being compatible, or is
specifically identified as not compatible, the installation process will provide an alert to
that effect, and will allow you to deselect the driver prior to continuing with the instal-
lation.

Note: If you choose to ignore any alert, the driver will be installed but the driver may
not operate correctly.

UNINTENDED EQUIPMENT OPERATION

l Do not ignore alerts during driver installation.

l If alerts are preventing the installation of a driver, contact Technical Support of this
product.
Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

The communication driver installation can also be invoked individually at any time
after the product installation to install additional drivers.

New Font Selection for Graphics Button

In previous releases of CitectSCADA, you were not able to change the properties of text
such as font, size, style on buttons in the Graphics Editor. This inability to configure the
button text properties led to graphics with text from different source objects having dif-
ferent font settings on the same page, which appears aesthetically untidy and incon-
sistent on the runtime displays.

53
Chapter: 2 What's New in CitectSCADA v7.x

From v7.10, the text displayed on a button object can be configured in the same manner
as other CitectSCADAtext objects within the Graphics Editor and the automation inter-
face. This will allow you to present a more polished and consistent GUI to meet individ-
ual project runtime presentation requirements.
When migrating from a previous release, button object text properties are preserved and
converted to the new button object text properties with the appropriate default property
values automatically placed in the new configuration such as Font=Arial, Size=12, Align-
ment=centre, style=regular, etc.
See Also
Button Properties - Appearance

Microsoft Windows Vista Support

CitectSCADA V7.10 has achieved the Microsoft® "Works with Windows Vista™" cer-
tification. However, merely meeting the requirements of this certification was not suf-
ficient to make CitectSCADA fully functional on Vista. A number of other changes were
necessary to achieve satisfactory functionality on the Vista operating system.
Version 7.10 also satisfies many of the requirements of the "Certified for Windows Vis-
ta™" certification, and by having this level of qualification we are confident that our
users will find minimal differences when running the product on the Vista operating sys-
tem compared to previous operating systems.

New Locations for Configuration and Project Files

Due to security changes in Windows Vista, some modifications to the location of con-
figuration and user files used by CitectSCADA have been made.
When installed on Windows XP or earlier, configuration and project files are by default
stored in the Documents and Settings/All Users/Application Data/Citect/CitectSCADA
7.xx/ folder. When installed on Windows Vista, configuration and project files are by
default stored in the ProgramData/Citect/CitectSCADA 7.xx/ folder. Install locations are
as follows:

File type Platform Install Path

Configuration Pre-Vista Documents and Settings/All Users/Application Data/Ci-

files such as tect/CitectSCADA 7.xx/Config
the citect.ini
file Vista ProgramData/Citect/CitectSCADA 7.xx/Config

54
 Chapter: 2 What's New in CitectSCADA v7.x

File type Platform Install Path

User direc- Pre-Vista Documents and Settings/All Users/Application Data/Ci-

tory tect/CitectSCADA 7.xx/User

Vista ProgramData/Citect/CitectSCADA 7.xx/User

Data direc- Pre-Vista Documents and Settings/All Users/Application Data/Ci-

tory tect/CitectSCADA 7.xx/Data

Vista ProgramData/Citect/CitectSCADA 7.xx/Data

Log files Pre-Vista Documents and Settings/All Users/Application Data/Ci-

tect/CitectSCADA 7.xx/Logs
All log files
produced by
drivers are
written to a
sub-folder Vista
called 'Driv- ProgramData/Citect/CitectSCADA 7.xx/Logs
ers'.

Alarm Field Enhancements

There are four enhancements to alarm fields:
l Runtime writes to custom alarm fields
l Alarm summary field changes
l Alarm display field changes
l Alarm paging

Runtime writes to custom alarm fields

It is now possible to write to the eight custom alarm fields during runtime. In previous
releases these fields could really only be used for alarm filtering.

Alarm summary field changes

Alarm Summary Fields can now be used to format an alarm display or alarm log
device. In addition any Alarm Display Field can be used in your alarm summary, apart
from State.
New Alarm Summary Fields

Field Name Description

{SumType,n} Type of alarm summary (similar to alarm display "Type").

55
Chapter: 2 What's New in CitectSCADA v7.x

Alarm display field changes

Now any alarm display field can be used for any type of alarm. Where not applicable for
a particular alarm type, zero or an empty string will be displayed.
New Alarm Display Fields

Field Name Description

{TagEx,n} Alarm Tag with Cluster Name prefix

{AlarmType,n} Alarm type (string), not localized.

{TypeNum,n} Alarm type number (use AlarmType to get string value instead).
V

{AlmComment,n} The text entered into the Comment field of the alarm properties
dialog.

{Cluster,n} Cluster Name

{CUSTOM1,n} Alarm custom fields as configured.

{CUSTOM2,n}
{CUSTOM3,n}
{CUSTOM4,n}
{CUSTOM5,n}
{CUSTOM6,n}
{CUSTOM7,n}
{CUSTOM8,n}

{LocalTimeDate,n} Alarm date and time.

{Paging,n} Indicates whether the alarm has to be paged.

{PagingGroup, n} Indicates the paging group to which the alarm belongs.

Alarm paging
The CitectSCADA alarm facility constantly monitors equipment data and alerts oper-
ators of any equipment error or alarm condition. When an alarm is triggered it is dis-
played on the standard alarm display page. The operator has to be continuously sitting
in front of an HMI monitoring the system. CitectSCADA v7.20 provides the facility to
link alarms with a remote paging system for operators.

56
 Chapter: 2 What's New in CitectSCADA v7.x

Two Alarm Properties have been added to enable CitectSCADA to interface with any
third-party paging system. The Paging property is a flag to indicate that the alarm is
going to be paged, the PagingGroup property is a freeform text field indicating the
sequence of people to notify in the event the alarm occurred.
See your third-party paging system documentation for information on how to interface
with CitectSCADA.

New Time Synchronization Service

In order to maintain time synchronization CitectSCADA now installs a Windows service
called TimeSyncService, which runs under the built-in LocalSystem account. This
replaces the existing time synchronization server which is not compatible with Win-
dows Vista. This purpose of this service is to maintain the time on the local computer
against one or more time sources.
A Time synchronization utility is provided by CitectSCADA to assist you to configure
time synchronization, and control the service as part of your administration envi-
ronment. This utility requires administrator rights as it configures and controls a win-
dows service. When run on Windows Vista with User Access Control (UAC) on, you
will be prompted to elevate to an administrator. When run on earlier operating systems,
the utility will exit after displaying an error if the current user is not an administrator on
the local machine.
See Also
Time Synchronization

New Equipment Database Functions and Forms

An equipment database form is provided by the CitectSCADA Project Editor to assist in

the configuration of system equipment. In addition, several Cicode functions have been
added to allow you to programmatically load, search and edit the database at runtime.
See Also
Using Equipment
Equipment Database Functions

Citect.ini Parameters in v7.10

This topic lists the parameters that have been added or changed in version 7.10 of Citect-
SCADA.
It includes:

57
Chapter: 2 What's New in CitectSCADA v7.x

l New parameters
l Obsolete parameters

New Parameters
The following parameters are new in version 7.10 . For an entire list of the system param-
eters, refer to theParameters documentation.
Alarm Parameters:

[Alarm]A- Defines the length of time that the alarm server will wait
rgyleTagValueTimeout for argyle tag values to become available (without error)
before starting to scan for argyle alarms.

Code Parameters:

[Code]Ha- When enabled will cause the cicode to halt when any tag
ltOnInvalidTagData read returns invalid data.

Client Parameters:

[Client]A- Set to enable auto login. Users can select one of seven modes.
utoLoginMode

CtApi Parameters:

[CtAPI]A- When enabled current version of CTAPI server can

llowLegacyConnections accept connections from previous versions of CTAPI
client.

[CtAPI]AllowLegacyServices When enabled the Citect Web Service and the Citect
OLEDB Provider can connect to the CTAPI server.

DDE Parameters:

[DDE]A- Allows Cicode to be run on the Citect server via the DDE Execute com-
llowCicode mand.

[DDE]A- Allows tag writes to the Citect server via the DDE Poke command.
llowWrites

Kernel Parameters:

[Ker- The total number of error buffers available for logging to the sys-
nel]ErrorBuffers log.dat file.

Lan Parameters:

58
 Chapter: 2 What's New in CitectSCADA v7.x

[LAN]A- Set to allow previous versions of client to connect to the

llowLegacyConnections server.

[LAN]Anon- The name of the default identifier to allow ‘view-only’ data

ymousLoginName access for a client process to the SCADA server(s).

[LAN]SecureLogin When set to 0 security measures are disabled and the sys-
tem acts as it did in versions prior to 7.10.

[LAN]ServerLoginEnabled Set to disable default server login.

[LAN]ServerLoginName The name of the default identifier to allow data access for
a server process to another SCADA server process(es).

ODBC Parameters:

[ODBC]Server Set to enable ODBC connections.

Page Parameters:

[Page]AllowHScroll Defines the default behavior for horizontal scrolling.

[Page]A- Defines the default behavior when displaying horizontal scroll

llowHScrollBar bars.

[Page]AllowVScroll Defines the default behavior for vertical scrolling.

[Page]A- Defines the default behavior when displaying vertical scroll bars.
llowVScrollBar

Obsolete Parameters
Win Parameters:

[Win]CtrlEsc Determines whether the Windows key command [Ctrl]+[Esc] can be

used in the runtime system (to display the start menu).

Com Parameters:

[Com]Star- Determines the period to wait for I/O Devices to come online before
tTimeout displaying any data.

59
Chapter: 2 What's New in CitectSCADA v7.x

Cicode Functions in v7.10

Some Cicode functions have been introduced, modified, deprecated or removed. The fol-
lowing sections detail the changes made to these functions:

New Functions
Security Functions

Form- Adds both a password prompt and edit field to the current form.
SecurePassword

MultiSignatureForm Displays a form that allows up for 4 users to have their cre-
dentials verified in order to approve an operation.

Mul- Displays a form that allows up for 4 users to have their cre-
tiSignatureTagWrite dentials verified in order to approve a write of a specific value to
a specific tag.

UserLogin Logs an operator into the CitectSCADA system using a secure

password string.

UserVerify Uses the authentication functionality in the user login system

VerifyPrivilegeForm Displays a form that allows a single user to enter their cre-
dentials.

Ver- Displays a form that allows any single user to enter their cre-
ifyPrivilegeTagWrite dentials in order to approve a write of a specific value to a spe-
cific tag.

Miscellaneous Functions

Ker- Obtains the number of rows in a queue.

nelQueueLength

KernelTableInfo Provides a consistent method of accessing items within Kernel

Table.

Ker- Obtains the number of rows in a Kernel Table

nelTableItemCount

ProcessRestart Restarts the current process in which Cicode is running.

ServerRestart Restart any alarm, report, trend or I/O server from any Cicode
node in system, without affecting other server processes running
on same machine.

60
 Chapter: 2 What's New in CitectSCADA v7.x

Tag Functions

TagRD- Works in conjunction with the TagInfo function. Reloads the variable
BReload tag database so when TagInfo is called it picks up online changes to the
tag database.

Windows Functions

WinStyle Switches on and off scrolling and scrollbar features for existing win-
dows.

Modified Functions
None

Obsolete Functions
Window Functions

WndGetProfile Gets the value of a WIN.INI parameter. If called it will return 0.

WndPutProfile Updates a parameter in WIN.INI. If called it will return 0.

Time and Date Functions

TimeSet Sets the new system time

What's New in CitectSCADA v7.20

CitectSCADA v7.20 incorporates the following new features.
Introduced in v7.20:
l Control SCADA Client Connections
l Dynamically Optimized Writes
l Environment Variable changes
l Graphics Enhancements
l Improved Client Side Online Changes
l Improved Installation Process
l Improved CitectSCADA Security
l Multi-process Support in Demo Mode
l New Example Project

61
Chapter: 2 What's New in CitectSCADA v7.x

l New Web-based Help

l OPC Factory Server (OFS) Driver
l Pelco Camera Support
l Performance Improvements
l Persisted I/O Memory Mode
l Post Compile Commands
l Server Side Online Changes
l Microsoft® Windows 7 Support
l Supportability Enhancements
l Tab Menu Templates
l Tag Extensions
l Time Scheduler
For changes to:
l Citect.ini parameters, see Citect.ini Parameters in Version 7.20.
l Cicode functions, see Cicode Functions in Version 7.20.
l CtAPI functions, see CtAPI Functions in Version 7.20.
For details on how to configure an existing project to run in v7.20, refer to Upgrading to
V7.20.
See Also
What's New in CitectSCADA v7.x

Control SCADA Client Connections

Two Citect.ini parameters determine how a client will behave if it is unable to maintain
a connection with a primary Alarms, Reports or Trends server. Each server type has
access to these parameters [Type.ClusterName.ServerName]Priority and [Type.Clu-
sterName.ServerName]DisableConnection, where Type is the relevant server type
(Report, Trend or Alarm).
See Also
Connectivity Parameters

62
 Chapter: 2 What's New in CitectSCADA v7.x

Dynamically Optimized Writes

Following the move to the new Publish-Subscribe infrastructure with Version 7.0, a
number of customers were adversely affected by a change in the way the product
behaves in respect to Block Writes. This change was generic to the driver interface and
specific issues have been raised with in regard to HITACHI, MODBUS and OPC, how-
ever other drivers may also have been affected.
In Version 7.20 changes have been made to the way that writes are performed at the I/O
Server in order to restore the pre-V7.0 behavior.
These changes will result in a similar level of blocking as occurred in previous versions.
It does not confirm that writes will be blocked, but it is more than likely that they will be
if they are initiated close enough together.
This will also allow use of the re-instated Citect.ini parameter [IOServer]BlockWrites in
order to choose whether to use the Block Writes functionality.
See Also
[IOServer]BlockWrites in the Parameters on line help

Environment variables in 7.20

When you define a Super Genie, you are creating a Super Genie template, similar to a
page template. When a Genie calls the Super Genie, this template is used to create a new
Super Genie page. Environment variables saved with the template are now propagated
to the Super Genie page. When subsequent changes are made to the environment var-
iables of the Super Genie template, the environment variables of the Super Genie page
are also updated.
If you modify a Super Genie template when the project is running in the background,
you need to perform an Update Pages to see the changes in the runtime project. If a run-
time page (created from a Super Genie template) is displayed when the change is made,
it will not be updated until you exit then re-display it.

63
Chapter: 2 What's New in CitectSCADA v7.x

UNINTENDED EQUIPMENT OPERATION

When upgrading from a previous version of CitectSCADA to v7.20 existing Super Genie tem-
plate environment variables will override Super Genie page environment variables. Any man-
ual updates you made to Super Genie page environment variables prior to the upgrade will be
lost.

Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

Graphic Enhancements
Enhancements have been made to how you can configure graphic pages and the objects
you place on the page. These enhancements can be used in the creation and imple-
mentation of Genies and Super Genies.
In addition, wide screen formats are now natively supported including 16:10 and 16:9
aspect ratios.
See Also
Metadata

Improved Installation Process

The installation process of CitectSCADA has been improved to simplify the operation
and guide the user through the installation by use of Installation Profiles and the cre-
ation of default component selections. Whilst still allowing flexibility for the experienced
user, the complexity and multiple installation paths and options have been greatly
reduced. The installer has been enhanced to allow the installation of a runtime-only ver-
sion of the product. This allows the runtime environment to be installed without the con-
figuration tools of the CitectSCADAIntegrated Environment. The Runtime Only
installation provides not only a smaller installation footprint but also the ability to set
up workstations which do not allow project configuration. This automatically improves
the security of the system configuration.

Note: You can also install the CitectSCADA runtime from a single installation file.
This file is on the installation DVD. This allows installation of the software to com-
puters which only need the runtime. The file can be copied to a network location for
remote installation.

64
 Chapter: 2 What's New in CitectSCADA v7.x

Improved CitectSCADA Security

Security enhancements have been implemented in this release to address known security
issues from previous versions and to reduce the possibility of malicious attack. These
security enhancements include, improved inter-operability through the introduction of
new INI parameters, trusted network authentication, and the addition of assigning roles
to CitectSCADA runtime users, as you currently do for Windows users.

Note: The [Privilege]Shutdown parameter is now used to specify the necessary priv-
ilege level of a user to perform a shutdown operation triggered by clicking the Close
button of the project (default privilege level is 8).

Multi-process Support in Demo Mode

If using a demonstration version of CitectSCADA you can now design and run your sys-
tem in multi-process mode (with TCP\IP turned off). This new default for v7.2 will
assist you in finding and fixing design flaws in your project , which may have pre-
viously gone unnoticed due to only being able to run and test your system in single proc-
ess mode.
See Also
Demo Mode

New Example Project

The Example Project has been updated to demonstrate the new tab menu templates that
are available with CitectSCADA v7.20.
The project includes a "What's New?" menu to introduce some of the new features
offered in v7.20. This menu links to pages that demonstrate:
l the use of tag extensions and tag properties on graphics pages
l server monitoring and the ability to implement online changes for alarm and trend
servers
l multi-monitor support
l Instant Trending using the Process Analyst
The new content complements pages drawn in from the existing Example Project and
CSV_Example Project, which are now superseded.

65
Chapter: 2 What's New in CitectSCADA v7.x

To view the new Example Project, select and run it from Citect Explorer. For more infor-
mation, use the help button included in the project on the main navigation panel.

Web-based Help
The wide spread use of the Internet to distribute information has now enabled Schneider
Electric (Australia) Pty. Ltd. to introduce that technology, to bring its users a new rich
and expanded format to deliver its help information.
The traditional on-line help, now referred to in CitectSCADA as PC-based Help, is still
available to provide immediate information which is related to the task at hand. If you
are a registered Technical Support customer you have the option of accessing the new
Web-based Help to provide the very latest information, which will include updates for
help topics to include the improvements to the software application introduced by Serv-
ice Packs.
Updates will also be included from enhancement to the help topics brought about by
user comments and general internal developments by the Schneider Electric (Australia)
Pty. Ltd. Technical Publications team.
You will also be able to "rate" individual help topics with a star rating, and add your
own comments to any help topics. Your comments and topic ratings will be retained in
our database and we will endeavor to incorporate your contributions in our ongoing
development of the quality of our documentation.
The future development of Web-based help will also include links to technical doc-
umentation in the form of:
l Technical Papers
l White Papers
l Knowledge Base content
l Education and Training material
The Web-based help is planned for release by the end of December 2010. So, please check
on its availability periodically with following the link www.citect.com/webhelp

OFSOPC Driver
The release of CitectSCADA v7.20 coincides with the availability of the OFSOPC Driver
for Schneider Electric's OPC Factory Server (OFS).
OFS Factory Server is a foundation component for communication with Schneider Elec-
tric PLCs. The OFSOPC Driver allows CitectSCADA to tightly integrate with OFS Factory
Server, minimizing the amount of configuration necessary for an end-to-end Schneider
Electric system.

66
 Chapter: 2 What's New in CitectSCADA v7.x

You can install the OFSOPC Driver and its supporting documentation via the Driver
Selection page of the CitectSCADA v7.20 installer.

Pelco Camera Support

This feature adds a button to the Graphics Builder toolbox, which will allow two of the
Pelco Camera ActiveX controls to be easily added to a graphics page. This control pro-
vides an ActiveX component that will connect to Pelco IP cameras with configurable
bandwidth usage for slow network connections and auto-resizes video to fit the ActiveX
control size.
The two ActiveX controls supported are:
Video Streaming - Fully Resizable, multiple bandwidth levels, MPEG4 Video, returns
the camera name and model.
Camera Control PTZ (Pan, Tilt and Zoom) - Communicates with DVRs and IP cameras.
Featuring pan zoom and tilt, iris, focus, presets, patterns and adjustable speed.
The button is only enabled if you have installed the Pelco camera software. Refer to the
Pelco camera software documentation for further information.
For details on configuring and using the Pelco Camera ActiveX control, refer to the doc-
umentation installed with the Pelco product.
See Also
Using Objects

Performance Enhancements
The architecture of CitectSCADA Version 7.20 includes a new threading model that
offers significant performance improvements. The new Platform Task Framework (PTF)
defines an explicit threading environment for each subsystem, providing a standard pro-
tocol for work to be created and passed between them.
The performance improvements have been implemented in a way that retains existing
functionality.There is no changes to the configuration or operation of a system, just per-
formance benefits and improved stability.

67
Chapter: 2 What's New in CitectSCADA v7.x

Persisted I/O Memory Mode

With the release of V7.20, a feature called persistence can be applied to I/O devices.
When implemented, the tag cache for an I/O device is written to an XML file at a set
period, allowing the last available data to be reloaded following a shutdown. Persistence
is enabled using the Persist field in the extended section of the I/O Devices Properties
dialog.
A persisted memory I/O device is recommended as an improved alternative to a disk I/O
device, as synchronization is supported if a server becomes unavailable for a period of
time.

Note: It is recommended that data assigned to disk I/O devices be migrated to the
new persisted memory I/0 mode. See the topic Persisted I/O Memory Mode for infor-
mation on how to migrate a disk I/O device to a persisted memory I/O device.

See Also
Using Persisted I/O Memory Mode

Post Compile Commands

After a project has compiled successfully you can execute an optional command, script
or batch file. This offers useful functionality if you have tasks that could be automated
after a successful compile. This provides an expansion point for you to add your own
script or command to perform additional tasks. You can also launch an optional com-
mand, script or batch file to execute after an unsuccessful compile.
See Also
Post Compilation

Improved Client Side Online Changes

Prior to V7.20, you could not load a page if the Cicode library has changed without
restarting the display client. In V7.20, you can now reload a page when the Cicode
library has changed. This will result in the page being reloaded and any Cicode on that
page will use the memory version of the Cicode library, not the latest compiled version.
This may cause a hardware alarm to be raised.
See Also
Client Side Online Changes

68
 Chapter: 2 What's New in CitectSCADA v7.x

Server Side Online Changes

To improve the ability to change configurations on a live system without having to
restart the servers, CitectSCADA now provides the facility to reload server configurations
during runtime either programmatically or using the Runtime Manager.
See Also
Server Side Online Changes

Microsoft Windows 7 Support

CitectSCADAv7.20 also supports the Microsoft Windows 7 and Microsoft Server 2008
R2 operating systems. The changes to CitectSCADA undertaken in the 7.1 release to sup-
port Windows Vista significantly reduced the changes that were necessary to support
Windows 7 and Server 2008 R2. Previous Vista users will experience no functional dif-
ferences in CitectSCADAwhen migrating to Windows 7. However if you migrate to Win-
dows 7 from Widows XP be aware of the functional differences with
CitectSCADAbetween XP and Vista, as described in New Locations for Configuration
and Project Files.

Supportability Enhancements
Supportability Enhancements have been added to CitectSCADA to provide easier access
to the diagnostics functionality of the product. Although the enhancements were pri-
marily introduced to assist Technical Support personnel with system analysis, they have
resulted in many benefits to the end user. These include:
l Timestamp harmonization across log files.
l Additional [Debug] parameters to support category and severity filtering (see
Citect.ini Parameters in Version 7.20).
l Support for online logging adjustments using the new SetLogging() and GetLogging()
Cicode functions.
l A set of parameters that can be modified while online due to periodic or an on-
demand read of the citect.ini file during runtime.
Additionally, the home page of the Computer Setup Editor now includes a link to the
Logging Parameters page, which provides comprehensive instructions for the con-
figuration of logging.
See Also
Configuring logging

69
Chapter: 2 What's New in CitectSCADA v7.x

Adjusting logging during runtime

New Tab Menu Templates

To improve the user interface of projects and integrate the look and feel with the latest
Windows® systems, CitectSCADA now features an optional ribbon style menu system.
Main menu items can be represented as tabs along a menu bar, below which subsidiary
items are displayed in a ribbon. New projects have the new Tab_Style_Include templates
already available to them.
Starter Project
In addition to the new Tab Style templates, it is now possible to create a compilable
starter project that contains a basic level of built-in functions such as viewing alarms
and trends.
See Also
Tab Menu Templates
Creating a New Tab Style Project

Tag Extensions
With the addition of Tag Extensions in CitectSCADA v7.20, the variable tag can now
represent data as a collection of elements, and each of these elements can contain a col-
lection of items.
Each element provides access to a view of the data value for the tag. Each variable tag
can be used on its own or by referencing a particular element. The tag and each element
have items that can be referenced to access the following information:
.v : The value, which will access the data value of the tag or element.
.vt : The value timestamp, which will access the timestamp of when the value last
changed.
.q : The quality, which will access the quality of the value , either GOOD, UNCERTAIN
or BAD. The Quality variable can access further detail using the Cicode Quality func-
tions.
.qt : The quality timestamp, which will access the timestamp of when the quality last
changed.
.t : The timestamp, which will access the timestamp of when the tag or element was last
updated.
See Also
Tag extensions

70
 Chapter: 2 What's New in CitectSCADA v7.x

Time Scheduler
The Time Scheduler is a calendar based programming tool that allows you to manip-
ulate tag values within a CitectSCADA project. It can be used to create a sequence of
automatically executed commands, delivering a valuable scheduling tool for appli-
cations. If you choose the Time Scheduler follow the on screen instruction.
For details on configuring and using the Time Scheduler, refer to the documentation
installed with the Time Scheduler product.

Citect.ini Parameters in v7.20

This topic lists the parameters that have been added or changed in version 7.20 of Citect-
SCADA.
It includes:
l New parameters
l Modified parameters
l Re-installed parameters
l Obsolete parameters

New Parameters
The following parameters are new in version 7.20 . For an entirelist of the system param-
eters, refer to the Parameters documentation.
Alarm Parameters

[Alarm.Clu- Specifies if a client will not connect to

sterName.ServerName]DisableConnection a server.

[Alarm.ClusterName.ServerName]Priority Specifies the client priority for the

server connection.

[Alarm]ReloadBackOffTime Back-off time configured to control

the pace of the reload on an alarm
server.

Client Parameters

[Client]A- When set to 1 the cache is cleared of any client login

utoLoginClearPassword credentials for consistency with the [Server]A-
utoLoginClearPassword ini parameter.

[Client]DisableDisplay Sets whether to allow the client process to run in the back-

71
Chapter: 2 What's New in CitectSCADA v7.x

ground without a visible window.

[Client]EvictTimeout Sets the amount of time a tag reference is cached before it

is evicted.

[Client]PartOfTrustedNetwork Tells a Client process to attempt to authenticate using the

stored server password. It is automatically set by the Com-
puter Setup Wizard.

[Client] StalenessPeriod Number of seconds to use for tag staleness period.

[Client]StalenessPeriodTolerance Staleness period tolerance

CtAPI Parameters

[CtAPI]Roun- Indicates to the user if values rounded to format.

dToFormat

CtDraw.RSC Parameters

[CtDraw.RSC]- When set enables the user to choose whether or

AllowEditSuperGeniePage not to open and edit a Super Genie page.

CtEdit Parameters

[CtE- Indicates to the compiler an optional command,

dit]CompileSuccessfulCommand script or batch file to execute after a successful
compile.

[CtEdit]CompileUnsuccessfulCommand Indicates to the compiler an optional command,

script or batch file to execute after an unsuccessful
compile.

[CtEdit]Starter Specifies the directory where the starter projects

are located.

Debug Parameters

[Debug]ArchiveFiles Archives log files once the size specified by [Debug]Ma-

ximumFileSize is reached.

[Debug]CategoryFilter Allows you to filter logging messages by component category.

[Debug]CategoryFilterMode Enables logging of categories declared by the [Debug]Ca-

tegoryFilter value.

[Debug]EnableLogging Enables or disables the logging mechanism.

[Debug]MaximumFileSize Sets the maximum size for a log file.

[Debug]Priority Allows you to filter logging messages according to their prior-

ity.

[Debug]SeverityFilter Allows you to filter logging messages according to their sever-

ity.

72
 Chapter: 2 What's New in CitectSCADA v7.x

[Debug]SeverityFilterMode Enables logging of severities declared by the [Debug]S-

everityFilter value.

General Parameters

[General]MiniumlUpdateRate Specifies the time period (sec) at which a Data-

Source will send tag update value notifications
to the subscription clients.

[General]StalenessPeriod Specifies the time period (sec) after which a

tag value is considered to be “stale” if it was
not updated during this period.

IOServer Parameters

[IOServer]EnableEventQueue Enables the event queue.

[IOServer]MaxEventsDrop Sets the number of events that are dropped when

too many are queued.

[IOServer]MaxEventsQueued Sets the total number of events that can be queued.

[IOServer]MaxTimeInQueueMs Sets the total time for which an event can be

queued.

LAN Parameters

[LAN]AllowRemoteReload Enables remote reloading of servers from a

client.

[LAN]ClientRetryTime Sets the length of time between connection

attempts by a client.

[LAN]EarliestLegacyVersion Specify the minimum legacy version from which

the current version will accept connections.

[LAN]HighWaterMark The number of messages waiting to be sent on a

particular network connection at which the high
water mark event will occur.

[LAN]KeepAliveInterval Sets the length of time between two keep alive

transmissions by the client.

[LAN]KeepAliveTime Sets the length of time between two keep alive

transmissions in idle conditions.

[LAN]ListenerRetryTime Sets the length of time a server waits between

attempts to listen for a client connection.

[LAN]LowWaterMark After the high water mark has been reached on a

particular network connection, the low water mark
represents the number of messages waiting to be
sent at which we will resume normal operations.

[LAN]NoSocketDelay Switches off the delay on a socket caused by the

use of the Nagle algorithm.

73
Chapter: 2 What's New in CitectSCADA v7.x

[LAN]ReadOnlyLegacyConnections When set to 1 v7.10 clients can only com-

municate in read-only mode.This parameter
overrides 'EarliestLegacyVersion' .

Multi-Monitor Parameters (CSV Include project)

[MultiMonitor]DisableAutoStart Disables the new multi-monitor func-

tionality.

Page Parameters

[Page]AddDefaultMenu Determines whether to add the

default menu items to the tabbed
menu bar.

[Page]BadDitheringColor Sets the dithering color for graphics

elements which are dithered if the
value quality is “bad”.

[Page]BadDitheringDensity Sets the dithering density for graph-

ics elements which are dithered if the
value quality is “bad”.

[Page]BadText Text Objects can be displayed as

#COM type errors, or as the text over-
laid with a dithered pattern if the ‘dis-
play value’ expression has “bad”
quality.

[Page]BadTextBackgroundColor Sets the background color for

numeric / text graphics objects to
indicate “bad” quality.

[Page]EnableQualityToolTip Set by default it controls the quality

tooltip

[Page]ErrorDitheringColor Sets the dithering color for graphics

elements which are dithered if an
internal error occurs.

[Page]ErrorDitheringDensity Sets the dithering density for graph-

ics elements which are dithered if an
internal error occurs.

[Page]ErrorTextBackgroundColor Sets the background color for

numeric / text graphics objects to
indicate an internal error.

[Page]IgnoreValueQuality Defines the value quality handling by

graphics pages.

[Page]OverrideDitheringColor Sets the dithering color for graphics

elements which are dithered if their
values are override (“forced”).

74
 Chapter: 2 What's New in CitectSCADA v7.x

[Page]OverrideDitheringDensity Sets the dithering density for graph-

ics elements which are dithered if an
internal error occurs.

[Page]OverrideTextBackgroundColor Sets the background color for

numeric / text graphics objects to
indicate that the value presented on
the objects is override (“forced”).

[Page]ShowBadText Text Objects can be displayed as

#BAD text, or as the text overlaid with
a dithered pattern if the "display
value" expression has “bad” quality.

[Page]ShowErrorText Text Objects can be displayed as

#COM type errors, or as the text over-
laid with a dithered pattern if the ‘dis-
play value’ expression has
“uncertain” quality.

[Page]ShowUncertainText Text Objects can be displayed as

#UNC text, or as the text overlaid
with a dithered pattern if the "display
value" expression has “uncertain”
quality.

[Page]Splash Specify the name of the Splash

Screen page.

[Page]SplashTimeout Time in milliseconds for the Splash

Screen to display.

[Page]SplashWinName Specify the label of the Splash Win-

dow for use with the Cicode function
WinNumber().

[Page]StartupDelay Milliseconds between when Splash

Screen and Start Screen are dis-
played.

[Page]StartupHeight Height of the Start Page on main dis-

play monitor.

[Page]StartupMode Mode of Start Page on main display

monitor.

[Page]StartupWidth Width of the Start Page on main dis-

play monitor.

[Page]StartupWinName Specify the label of the Start Window

for use with the Cicode function Win-
Number().

[Page]StartupX X coordinate of Start Page on main dis-

play monitor.

[Page]StartupY Y coordinate of Start Page on main dis-

play monitor.

75
Chapter: 2 What's New in CitectSCADA v7.x

[Page]UncertainDitheringColor Sets the dithering color for graphics

elements which are dithered if the
value quality is “uncertain”.

[Page]UncertainDitheringDensity Sets the dithering density for graph-

ics elements which are dithered if the
value quality is “uncertain”.

[Page]UncertainText Text Objects can be displayed as

#COM type errors, or as the text over-
laid with a dithered pattern if the ‘dis-
play value’ expression has
“uncertain” quality.

[Page]UncertainTextBackgroundColor Sets the background color for

numeric / text graphics objects to
indicate “uncertain” quality.

Specifies whether the animation sys-

tem will attempt to wait for valid data
[Page]WaitForValidData
from subscriptions necessary to draw
a graphics page before it is animated.

Report Parameters

[Alarm.ClusterName.ServerName]DisableConnection Specifies if a client will not con-

nect to a server.

[Alarm.ClusterName.ServerName]Priority Specifies the client priority for the

server connection.

Runtime Manager Parameters

[RuntimeManager]AllowReload Enables or disables the reload

option in the Runtime Manager
menu.

Security Parameters

[Security]DisableDEP Set to turn off DEP protection

for the CitectSCADA runtime.

Server Parameters

[Server]AutoLoginMode Determines the auto login

method the server will use
when establishing connections
to other servers.

Trend Parameters

[Trend]AcquisitionTimeout Sets a timeout to stop a trend

server infinitely acquiring a valid
data sample from an I/O device.

76
 Chapter: 2 What's New in CitectSCADA v7.x

[Trend.ClusterName.ServerName]DisableConnection Specifies if a client should not con-

nect to a server.

[Trend.ClusterName.ServerName]Priority Specifies the client priority for the

server connection.

[Trend]ReloadBackOffTime Back-off time configured to con-

trol the pace of the reload on an
Trend server.

Modified Parameters
CtEdit Parameters

[CtEdit]Copy Supports runtime changes, it enables you to switch the SCADA node to
use a new runtime configuration by pointing to a new location.

Re-instated Parameters
IOServer Parameters

[IOServer]Bloc- Determines whetherCitectSCADA will try to block optimize writes

kWrites to I/O devices.

Obsolete Parameters
AnmCursor Parameters

[AnmCursor]Colour Replaced with [AnmCursor]Color. Sets the

color of the cursor.

General Parameters

[General]TagAssMode Validates the tag name in the Ass Function.

Refer to [General]TagDB instead.

LAN Parameters

[LAN]AllowLegacyConnections Set to allow previous versions of client to con-

nect to the server.

[LAN]ServerLoginEnabled Set to disable default server login.

Page Parameters

[Page]BackgroundColour Replaced with [Page]BackgroundColor. Specifies

the color used to fill in the background when a
page is smaller than the minimum width of a win-
dow.

77
Chapter: 2 What's New in CitectSCADA v7.x

[Page]ComBreak Determines whether an error status is displayed

on the screen if a communication error occurs.

[Page]ComBreakText Determines the display of text objects if a com-

munication error occurs that affects the text.

[Page]DynamicComBreakColour Replaced with [Page]DynamicComBreakColor.

Sets the color of the ComBreak dithering.

[Page]DynamicComBreakDensity Sets the density of the ComBreak.

Time Parameters:

[Time]Deadband The deadband time checked by the Time

Server before it adjusts the time on the
client(s).

[Time]Disable Enables/disables the processing of time mes-

sages from the Time Server.

[Time]Name Enables the time synchronization func-

tionality.

[Time]PollTime The period that the Time Server uses to syn-

chronize other CitectSCADA computers on the
network.

[Time]RTsync Determines whether the Time Server will syn-

chronize with the hardware clock.

[Time]Server Determines whether this computer is a Time

Server.

Trend Parameters

[Trend]CursorColour Replaced with [Trend]CursorColor. Allows the

cursor color to be specified.

CtAPI Functions in v7.20

The following section details the changes made to CtAPI functions in CitectSCADA
v7.20.

New Functions

ctListItem Gets the tag element item data.

ctTagReadEx Performs the same as ctTagRead, but with an additional new argument

Modified Functions

78
 Chapter: 2 What's New in CitectSCADA v7.x

ctTagRead Reads the current value from the given I/O device variable tag element value.

ctTagWrite Writes the given value to the I/O device variable tag elements which have read/write
access.

ctTagWriteEx Asynchronously writes the given value to the I/O device variable tag element value
for the tag elements which have read/write access.

ctListAdd Adds a tag element value to the list.

ctListAddEx Adds a tag element value to the list.

Obsolete Functions
None

Cicode Functions in v7.20

Some Cicode functions have been introduced, modified, deprecated or removed. The fol-
lowing sections detail the changes made to these functions:

New Functions
Alarm Functions

AlarmCatGetFormat Returns the display format string of the specified alarm category.

AlarmDspClusterAdd Adds a cluster to a client's alarm list.

AlarmDspClusterInUse Determines if a cluster is included in a client's alarm list.

AlarmDspClusterRemove Removes a cluster from a client's alarm list.

Display Functions

DspAnGetMetadata Retrieves the field value of the specified metadata entry.

DspAnGetMetadataAt Retrieves metadata information at the specified index.

DspAnSetMetadata Non-blocking function, that sets the value of the specified metadata
entry.

DspAnSetMetadataAt Sets the value of a metadata entry.

DspPopupConfigMenu Displays the contents of a menu node as a pop-up (context) menu,

and run the command associated with the selected menu item.

Format Functions

FmtGetFieldCount Retrieves the number of fields in a format object.

79
Chapter: 2 What's New in CitectSCADA v7.x

FmtGetFieldName Retrieves the name of a particular field in a format object.

FmtGetFieldWidth Retrieves the width of a particular field in a format object.

Menu Functions

MenuGetChild Returns the handle to the child node with the specified name.

MenuGetFirstChild Returns the handle to the first child of a menu node.

MenuGetGenericNode Returns the root node of the default menu tree.

MenuGetNextChild Returns the next node that shares the same parent.

MenuGetPageNode Returns the Base menu node of a specific page.

MenuGetParent Returns the parent node of the menu item.

MenuGetPrevChild Returns the previous node that shares the same parent.

MenuGetWindowNode Returns the handle of the root menu node for a given window.

MenuNodeAddChild Dynamically adds a new item to the menu at runtime.

MenuNodeGetProperty Return the item value of the specified menu node.

MenuNodeHasCommand Checks whether the menu node has a valid cicode command
associated with it.

MenuNodeIsDisabled Checks whether the menu node is disabled by evaluating its

DisabledWhen cicode expression.

MenuNodeIsHidden Checks whether the menu node is hidden by evaluating its Hid-
denWhen cicode expression.

MenuNodeRemove Remove the menu node from the menu tree.

MenuNodeRunCommand Run the associated command for a menu node.

MenuNodeSetDisabledWhen Set the DisabledWhen expression for a newly added node.

MenuNodeSetHiddenWhen Set the HiddenWhen expression for a newly added node.

MenuNodeSetProperty Set the item value of the specified menu node.

MenuReload Reload base Menu Configuration from the compiled database.

Miscellaneous Functions

GetLogging Gets the current value for one or more logging parameters.

SetLogging Adjusts logging parameters while online.

ProductInfo Returns information about the CitectSCADA product.

ProjectInfo Returns information about a particular project, which is identified by a

project enumerated number.

Page Functions

80
 Chapter: 2 What's New in CitectSCADA v7.x

PageBack Displays the previously displayed page in the Window.

PageForward PageForward() restores the previously displayed page in the win-

dow following a PageBack command.

PageHistoryDspMenu Displays a pop-up menu which lists the page history of current
window.

PageHistoryEmpty Returns whether page history of the current window is empty.

PageHome Displays the predefined home page in the window.

PagePeekCurrent Return the index in the page stack for the current page.

PageProcessAnalyst Displays a Process Analyst page (in the same window) preloaded
with the pre-defined Process Analyst View (PAV) file.

PageProcessAnalystPens Displays a Process Analyst page (in the same window) preloaded
with the pre-defined Process Analyst View (PAV) file and specified
trend or variable tags.

PageRecall Displays the page at a specified depth in the stack of previously dis-
played pages.

PageTask Used for running preliminary Cicode before displaying a page in a

window.

PageTransformCoords Converts Page coordinates to absolute screen coordinates.

Process Analyst Functions

ProcessAnalystLoadFile Loads the specified PAV file to a Process Analyst object, which is
identified by parameter ObjName.

ProcessAnalystPopup Displays a Process Analyst page (in the same window) preloaded
with the pre-defined Process Analyst View (PAV) file and specified
trend or variable tags.

ProcessAnalystSelect Allows a set of pens to be selected before displaying the PA page.

ProcessAnalystSetPen Allows a new pen to be added to a PA display.

Displays a Process Analyst page (in a new window) preloaded with

ProcessAnalystWin
the pre-defined Process Analyst View (PAV) file.

Quality Functions

QualityCreate Creates a quality value based on the quality fields provided.

QualityGetPart Extracts a requested part of the Quality value from the QUALITY var-
iable.

QualityIsBad Returns a value indicating whether the quality is bad.

QualityIsGood Returns a value indicating whether the quality is good.

QualityIsUncertain Returns a value indicating whether the quality is uncertain.

QualitySetPart Sets a Quality part’s value to the QUALITY variable.

81
Chapter: 2 What's New in CitectSCADA v7.x

QualityToStr Returns a textual representation of the CitectSCADA quality.

QualityIsOverride Returns a value indicating whether the tag is in Override Mode.

QualityIsControlInhibit Returns a value indicating whether the tag is in Control inhibit mode.

VariableQuality Extracts the quality from a given variable.

Server Functions

ServerBrowseClose This function terminates an active data browse session and

cleans up resources associated with the session.

ServerBrowseFirst This function places the data browse cursor at the first record.

ServerBrowseGetField This function retrieves the value of the specified field from the
record the data browse cursor is currently referencing.

ServerBrowseNext This function moves the data browse cursor forward one record.

ServerBrowseNumRecords This function returns the number of records that match the filter
criteria.

ServerBrowseOpen This function initiates a new browse session and returns a han-
dle to the new session that can be used in subsequent data
browse function calls.

ServerBrowsePrev This function moves the data browse cursor back one record.

ServerGetProperty This function returns information about a specified server and

can be called from any client.

ServerReload This function reloads the server specified by cluster and server
name.

ServerIsOnline This function checks if the given server can be contacted by the
client for giving the online/offline status of the server.

String Functions

StrCalcWidth Retrieves the pixel width of a string using a particular font.

StrTruncFont Returns the truncated string using a particular font (specified by name)
or the specified number of characters.

Returns the truncated string using a particular font (specified by font

StrTruncFontHnd
number) or the specified number of characters.

Super Genie Functions

AssMetadata Performs Super Genie associations using the "Name" and "Value" fields.

AssMetadataPage Uses the metadata information from the current animation point for the
page associations for a new Super Genie page, and displays the new
Super Genie in the current page.

AssMetadataPopup Uses the metadata information from the current animation point for the
associations for a new Super Genie page, and displays the new Super
Genie in a new pop up window.

82
 Chapter: 2 What's New in CitectSCADA v7.x

AssMetadataWin Uses the metadata information from the current animation point for the
associations for a new Super Genie page, and displays the new Super
Genie in a new window.

Tag Functions

SubscriptionGetInfo Reads the specified text information about a subscribed tag.

SubscriptionGetQuality Reads quality of a subscribed tag.

SubscriptionGetTag Reads a value, quality and timestamps of a subscribed tag.

SubscriptionGetTimestamp Reads the specified timestamp of a subscribed tag.

SubscriptionGetValue Reads a value of a subscribed tag.

TagSetOverrideBad Sets a quality Override element for a specified tag to Bad Non
Specific.

TagSetOverrideGood Sets a quality Override element for a specified tag to Good Non
Specific.

TagSetOverrideUncertain Sets a quality Override element for a specified tag to Uncertain

Non Specific.

TagSetOverrideQuality Sets a quality of Override element for a specified tag.

Task Functions

Calls a Cicode function by specifying the function name and providing an

TaskCall
arguments string.

Timestamp Functions

TimestampToStr Converts a TIMESTAMP variable into a string.

TimestampDifference Returns a difference between two TIMESTAMP variables as a number

of milliseconds.

TimestampCreate Returns a timestamp variable created from the parts.

TimestampFormat Format a TIMESTAMP variable into a string.

TimestampGetPart Returns one part (year, month, day, etc) of the timestamp variable.

TimestampToTimeInt Converts a TIMETSTAMP variable into a time INTEGER which is rep-

resented as a number of seconds since 01/01/1970.

TimeIntTo Times- Converts a time INTEGER which is represented as a number of sec-

tamp onds since 01/01/1970 to a TIMETSTAMP

TimestampCurrent Returns the current system date and time as a TIMESTAMP variable.

TimestampAdd Adds time (in milliseconds) to a TIMESTAMP variable.

TimestampSub Subtracts time (in milliseconds) from a TIMESTAMP variable.

VariableTimestamp Extract the TIMESTAMP from a given variable.

83
Chapter: 2 What's New in CitectSCADA v7.x

Window Functions

MultiMonitorStart Displays a CitectSCADA window on each of the configured monitors when

a display client starts up.

WinSetName Associates a name with a particular window by its window number.

WndMonitorInfo Returns information about a particular monitor.

Modified Functions
Accumulator Functions

AccumBrowseOpen Opens an accumulator browse session.

Alarm Functions

AlarmDsp Displays alarms.

AlarmDspLast Displays the latest, unacknowledged alarms.

AlmSummaryOpen Opens an alarm summary browse session.

AlmTagsOpen Opens an alarm tags browse session.

Display Functions

DspStr Displays a string at an AN.

DspText Displays text at an AN.

Format Functions

FmtOpen Creates a format template.

Miscellaneous Functions

Shutdown EndsCitectSCADA operation.

Page Functions

PageGetInt Gets a local page-based integer.

PageGetStr Gets a local page-based string.

PageInfo Gets information about the current page.

PagePeekLast Gets any page on the PageLast stack.

PageSetInt Stores a local page-based integer.

PagesetStr Stores a local page-based string.

Security Functions

Login Logs an operator into the CitectSCADA system. Not available when logged

84
 Chapter: 2 What's New in CitectSCADA v7.x

in as Windows user.

Super Genie Functions

The following functions were updated to accept string identifiers for substitution param-
eters.

Ass Associates a variable tag with a Super Genie.

AssGetProperty Retrieves association information about the current Super Genie from the
datasource.

AssGetScale Gets scale information about the associations of the current Super Genie
from the datasource (that is scale information about a variable tag that has
been substituted into the Super Genie)

AssInfo Gets association information about the current Super Genie (that is infor-
mation about a variable tag that has been substituted into the Super
Genie).

AssInfoEx Retrieves association information about the current Super Genie (that is
information about a variable tag that has been substituted into the Super
Genie).

AssScaleStr Gets scale information about the associations of the current Super Genie
(that is scale information about a variable tag that has been substituted
into the Super Genie).

Tag Functions

SubscriptionGetAttribute Reads an attribute value of a tag subscription.

TagRead Reads the value of a particular tag element.

TagWrite Writes a tag element value for the tag elements which have
read/write access.

TagSubscribe Subscribes to a particular tag element.

Window Functions

WinNumber Gets the window number of the active CitectSCADA window.

WndInfo Gets the Windows system metrics information.

Reinstated Functions
Following functions have been reinstated for 7.20.
Time and Date Functions

TimeSet Sets the new system time

85
Chapter: 2 What's New in CitectSCADA v7.x

Kernel Commands in Version 7.0

The following Kernel commands are obsolete in CitectSCADA from Version 7.0:
l Kernel Alarm
l Kernel Trend
l Kernel Report
l Kernel IOServer
l Kernel Client
l Probe
l NetBIOS
l PageNetstat

86
Chapter: 3 Upgrading to CitectSCADA v7.20
To upgrade an existing project to v7.20 from v6.x, perform each of the following pro-
cedures.
You do not need to carry out these procedures if you are upgrading from v7.0 or v7.10 to
v7.20.
l Upgrade CTAPI Applications
Verify that CTAPI applications are upgraded before upgrading and running any
CitectSCADA V7.x projects.
l Configure I/O Devices
Before upgrading, verify that I/O Devices are configured as necessary to run in the
project.
l Run the Citect Installer
The installer will lead you through a number of steps until the installation is com-
plete.
l Launch CitectSCADA
An automatic upgrade of your projects will occur when you initially start Citect-
SCADA
l Run the Migration Tool
The automatic update that occurs when you initially launch CitectSCADA does not
fully upgrade your projects, as such it needs to be followed by running the Migration
Tool.
l Define Clusters
Clusters can now be defined. The project needs to be configured to use at least one
cluster.
l Configure Network Addresses
The network addresses and ports of the computers to be used as servers are now
defined in the project.
l Configure Servers
The Alarm, Report, Trend, and I/O Servers are now defined in the project.
l Configure Tags to Use Clustering
Alarms, reports, trends, SPC tags, and accumulators can now be configured to run in
a specific cluster.

87
Chapter: 3 Upgrading to CitectSCADA v7.20

l Configuring Multiple Monitor Support

You may need to check whether a custom configuration operates correctly in a mul-
tiple-monitor environment.
l Compile the Project
Once you have configured your project, compile it and verify that there are no errors.
l Run the Computer Setup Wizard
Run the Computer Setup Wizard for each computer running the project. At each stage
of the Wizard, configure the appropriate settings for that computer.

Note: If you are running version 5.5, verify that you upgrade your projects to version
6.x before upgrading to v7.x.

See Also
What's new in V7.x

Upgrade CTAPI Applications

To set up CitectSCADA v7.20 communications with CTAPI applications in your system
(including CitectSCADA Reports and Ampla), verify that these products have been
upgraded to their latest versions before running any upgraded CitectSCADAv7.20
projects.
Similarly, if you are using any custom CTAPI applications, upgrade CitectSCADA on the
computers where these applications are installed before upgrading any other Citect-
SCADA computers.
See Also
Configure I/O Devices
"CtAPI Functions" in the CitectSCADA Technical Reference

Configure I/O Devices

The upgrade process verifies that the functionality of your project is upgraded to version
7.x. To facilitate this, parts of your project configuration may change during the upgrade.
It is therefore important to verify that a project is configured the way you want it to run
before you upgrade.
In particular, memory I/O Devices defined in your project (specifying MEMORY as the
port) will be configured in the upgraded project as local variables, since memory I/O
Devices are no longer supported. Local variables offer the same functionality as memory
I/O Devices without the need for further configuration.

88
 Chapter: 3 Upgrading to CitectSCADA v7.20

However, this also means if you have I/O Devices temporarily defined as memory I/O
Devices for testing or simulation, they will be incorrectly configured as local variables by
the upgrade process. Verify that you configure these devices as you require them to run
before upgrading to version 7.x.

UPGRADE ALTERS COMMUNICATIONS CONFIGURATIONS

After upgrading, confirm and adjust the configuration of all I/O devices in your project.

Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

Before attempting to configure your I/O devices for the changes caused by the upgrade
process, first read the information in Configuring Local Variables and Using Memory
Mode. This provides details about local variables and the other I/O Device options that
replace memory I/O Devices, allowing you to select and configure your project appro-
priately.

Note: Alarm devices with their Protocol property set to "Alarm" are no longer used
and will be removed by the Migration Tool. All Alarm Servers will now publish
Alarm Properties.

The reconfiguration will take place when you run the Migration Tool. For detailed infor-
mation on this tool, refer to Migration Tool.
See Also
Run the Citect Installer
Configuring Local Variables
Using Memory Mode

Run the Citect Installer

To begin the upgrade, run the CitectSCADAv7.20 installer. The installer will lead you
through a number of steps until the installation is complete.

Note: Uninstall any existing version 6.x or version 7.0 before installing v7.20, as
CitectSCADA does not support different versions running side-by-side. Additionally,
to use the v7.20 Example and CSV_Example projects, it is recommended that you
delete the existing Example and CSV_Example projects using Citect Explorer before
starting the installation.

89
Chapter: 3 Upgrading to CitectSCADA v7.20

Launch CitectSCADA
An automatic upgrade of your projects will occur when you initially start CitectSCADA.
1. To launch CitectSCADA, click Start | All Programs | Citect | CitectSCADA 7.10 |
CitectSCADA Explorer. The following message will display:

2. Click Yes to confirm the upgrade.

See Also
Define Clusters
Migration Tool

Migration Tool
The automatic update that occurs when you initially launch CitectSCADAv7.20 does not
fully upgrade your projects, and needs to be followed by the use of the Migration Tool (
if migrating from v6.x this is particularly noteworthy). The automatic update is a pas-
sive action which updates the database field definition for any database that has been
changed between the two versions and copies new files that are necessary in v7.20. Prior
to the automatic upgrade proceeding you are given the option of canceling the upgrade.
The upgrade can be invoked at a later time by setting the [CtEdit]Upgrade parameter to 1
(True) in the Citect.ini file.
After the automatic update has completed then prepare your projects prior to running
the Migration Tool.
The Migration Tool is a separate application which has to be manually run after the
automatic upgrade has been executed, and initiated by you after you have prepared the
project for final migration. This tool will accommodate the important changes in project
functionality that are incorporated in v7.0 and v7.20.
It is important that you prepare your existing projects for a successful upgrade using this
tool.

90
 Chapter: 3 Upgrading to CitectSCADA v7.20

Some of the features introduced in v7.20 of CitectSCADA require changes in the project
data from version 6.x

UPGRADE ALTERS COMMUNICATIONS CONFIGURATIONS

After upgrading, confirm and adjust the configuration of all I/O devices in your project.

Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

See Also
Memory devices
Alarm devices
Included projects
Using the Migration Tool

Memory Devices
In previous versions of CitectSCADA an I/O Device could be defined as a memory
device by setting the port value to "Memory". This was generally done for one of the fol-
lowing purposes:
l To provide for future devices that were not currently connected to the system, but
their points needed to be configured at this stage of project.
l For virtual devices where there was no corresponding physical I/O Device and you
needed data storage with the entire functionality normally associated with I/O var-
iables such as alarms.
l To act as a variable which was local to the process being used in place of Cicode
global variables.
You can still use I/O Devices for future or virtual devices in version 7.0, but manually
set the Port parameter to an unused value other than Memory, and set the Memory prop-
erty of the device to True to indicate that it is an offline in-memory device before running
the Migration Tool.
You need to review your project to identify which memory I/O Devices are local variable
holders and which ones need to be changed to non-memory so that the Migration tool
does not convert their variables.
The Migration Tool will set any I/O Device's port which is identified as a Memory
device to the new Local Variable, and the original device record will be deleted.
See Also
Configure I/O Devices
Alarm Devices

91
Chapter: 3 Upgrading to CitectSCADA v7.20

Converting Memory Variables

Alarm Devices
In previous versions of CitectSCADA Alarm devices were defined as devices with their
Protocol property set to "Alarm". In version 7.0 the function of configuring such a device
is now replaced by setting the Publish Alarm Properties property to True on the Alarm
Server.
Alarm devices with their Protocol property set to "Alarm" will be deleted from I/O
Devices table by the Migration Tool.
See Also
Alarm Server Definitions
The Migration tool can delete memory and alarm device records. If you want to delete
the devices at a later time, deselect the "Remove obsolete Memory and Alarm Devices"
option.

Note: Alarm devices with their Protocol property set to "Alarm" are no longer used
and will be removed by the Migration Tool. All Alarm Servers will now publish
Alarm Properties.

See Also
Converting Memory Variables

Converting Memory Variables

A memory variable is a variable with its I/O Device Port property set to either "Memory"
or "MEM_PLC".
If there are multiple I/O Devices with the same name, possibly on different I/O Servers,
then the device would not be considered as a memory device regardless of its port value.
In other words the Migration tool will not process the variables for memory devices with
duplicate names.
See Also
Inserting new local variables
Deleting Variable Tags

Inserting new local variables

When the Migration Tool runs, a local variable record will be inserted for each identified
memory variable, and the variable data will be copied into the new local variable.
Local variables have fewer fields than variables; the following table shows the mapping
from variable to local variable when copying their data.

92
 Chapter: 3 Upgrading to CitectSCADA v7.20

Variable Tag parameter or constant

Local variable parameter
value

Variable Tag name Name

Data Type Date Type

(Empty) Array Size

Eng. Zero Scale Zero Scale

Eng. Full Scale Full Scale

Comment Comment

With the exception of the Array Size, which has been introduced in version 7.0 exclu-
sively for local variables, every field receives it's value from the same or similar field.
See Also
Deleting Variable Tags

Deleting Variable Tags

Once the Migration Tool has created the local variable records it will insert those var-
iable tag records that have been converted in the previous step, and delete the original
variable tag.
If an error is detected during the insertion of the local variables, the deletion of the var-
iable tags will not be performed. If this occurs it is possible to have two records with
same name and data, one in the local variable (the newly inserted record) and one in the
variable tags (the original record that has not been deleted). You need to delete either of
the variables manually, or restore the backed up project after removing the cause of the
error then run the Migration Tool again.
See Also
Default Scale
Deleting Obsolete I/O Devices

Default Scale
The Scale properties in both variable tags and local variables are optional. If a Scale
value is not specified the default value is indicated by a parameter in the Citect.ini file.
The parameter name is "DefaultSliderScale" under the [General] section in the Citect.ini
file. The default values for Scale is 0-32000, unless the default slider scale is true in
which case the default value depends on the type for example Integer, String etcetera.

93
Chapter: 3 Upgrading to CitectSCADA v7.20

The Migration tool will read this parameter and if it is not set, or set to false, then it will
explicitly set any empty Scale property to a value in to the range of 0 to 32000. This will
be done even if either of the Zero Scale or Full Scale parameters has a value, in which
case the empty Scale parameter will receive the default value.
If the DefaultSliderScale in the Citect.ini file set to True, the Scale parameters will not be
populated with a default value if they are empty, rather they will be interpreted at run-
time.

Deleting Obsolete I/O Devices

Deleting obsolete I/O Devices is an optional step in the Migration Tool and will be per-
formed after the memory variables are converted. If the delete option is chosen, then
obsolete Memory devices and Alarm devices will be deleted as the final step of the
Migration Tool operation.
See Also
Included Projects

Included Projects
Each project may contain multiple included projects. Additionally any included project
may contain its own included project so creating a cascading project.
The Migration Tool needs to process the original project and included projects in a sin-
gle step. The reason for this is that variables can be defined in one project that refer to
I/O Devices defined in another included project.
The Migration Tool performs this procedure sequentially on the "master" project then
each included project.
In the case where two master projects share the same project as an included project, it is
important that you do not select the "Remove obsolete Memory and Alarm devices"
check box when you process a project that contains shared included projects. This is
because the removal is performed at the conclusion of the migration process on each
master and included projects sequentially. This could cause the deletion of an I/O Device
in the first master project which is referenced by a tag in a shared included project
which is processed in a later step.
If two separate "master" projects contain the same included project, run the Migration
Tool on each "master" project without selecting to delete obsolete devices.

94
 Chapter: 3 Upgrading to CitectSCADA v7.20

UPGRADE ALTERS COMMUNICATIONS CONFIGURATIONS

After upgrading, confirm and adjust the configuration of all I/O devices in your project.

Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

To remove obsolete devices it is recommended that once the Migration Tool has com-
pleted successfully (without the check box being selected), run it a second time with the
check box selected. This will safely remove the devices since every tag conversion were
completed in the first pass of the Migration Tool.

Creation of roles for existing users

When upgrading an existing project using the migration tool, a new role will be created
(if needed) for every existing user. The new role will have the same security settings that
were defined for that user and be given a generic name such as Role_1, Role_2 etc. Dur-
ing the upgrade process, if a role exists with the same security settings as the user, then
the existing role will be assigned to the user being upgraded. For example; If Role_1
exists and matches the security settings of the upgraded user then that user will be
assigned Role_1 also.
If you do not want to migrate users from an existing project deselect the option "Create
Roles from User security information" from the migration tool dialog before running it.
See Also
Incremental compilation

Using the Migration Tool

Note: Before you use the Migration Tool is strongly recommended that you famil-
iarize yourself with the process that it performs, and the preparatory steps that you
need to carry out with your existing projects as described under Migration Tool.

To run the Migration Tool:

1. Backup the projects that you intend to migrate.

2. From the Citect Explorer or Citect Editor menu bar select Tools | Migration Tool to
display the Migration Tool dialog.
3. Either accept the project displayed in the edit box, or browse for the project that you
wish to upgrade. To migrate this project as well as any included projects within it,
select the option 'Migrate Included Projects'.

95
Chapter: 3 Upgrading to CitectSCADA v7.20

4. Select the Remove obsolete Memory and Alarm devices check box if you wish to
delete these devices after successful migration.

Note: Do not select this check box if the project contains any included projects
which are shared with more than one master project when you run the tool for
the first time on such projects. Run the tool a second time using this option if the
migration is successful after it is run the first time if you want to delete the
devices.

5. Leave as selected the option 'Create Roles from User security information' if you wish
to migrate the users database from an existing project
6. Check the option 'Copy XP_Style menu into Tab_Style Menu' to convert legacy menu
entries to the format necessary for the new menu configuration system. By default
this option is unchecked, to avoid potential compile errors that may occur after migra-
tion if the legacy menu.dbf contains functions which have been removed.
7. Check 'Migrate Included Projects' to migrate the included projects that are in the
project you previously selected.

Note: If 'Copy XP Syle menu into Tab_Style Menu' and 'Migrate Included Projects'
are both selected when the migration tool runs the following message will be dis-
played "Copying menus of included projects may lead to conflicts. Any conflicts
will need to be manually corrected". To avoid this from occurring it is rec-
ommended you run the migration tool twice. In the first instance just select the
option 'Copy XP_Style menu into Tab_Style Menu', and in the second instance
just select the option 'Migrate Included Projects'.

8. Click Migrate to begin the migration process, or click Close to exit without per-
forming the migration.
9. The migration process will begin and display a progress dialog indicating the stage
of the conversion and the name of the project being migrated. If you wish to cancel
the migration at this point click the Abort button.

Note: Aborting a migration will stop the migration process, and any changes
already completed will not be rolled back. You will have to restore your project
from the backup created in the first step.

10. When the migration process is concluded a confirmation dialog box will display indi-
cating the number of variables converted and the number of I/O Devices deleted (if
device deletion was selected at the start of migration)
11. Click the Close button to close the dialog.

96
 Chapter: 3 Upgrading to CitectSCADA v7.20

Define Clusters
Even if you do not intend to use clusters in your project, you need to define at least one.
Tags and servers will default to run in the defined cluster.
1. In the Project Editor, select Servers | Clusters. The Cluster dialog box displays:
2. In the ClusterName field, enter the name of the cluster. The name needs to be unique
to the project and not contain spaces.
3. In the Comment field, enter any useful comment. This property is optional and is not
used at runtime.
4. Click Add.
See Also
Configure Network Addresses

Configure Network Addresses

In the Project Editor, configure the network address of each machine to be used as a
server in the project.
1. In the Project Editor, select Servers | Network Addresses. The Network Addresses
dialog box displays:
2. In the Name field, enter a name for the network address being configured. The name
needs to be unique to the project and not contain spaces.
3. In the Address field,enter the IP address or computer name of the machine being con-
figured.
4. In the Comment field, enter any useful comment. This property is optional and is not
used at runtime.
5. Click Add.
See Also
Configure Servers

Configure Servers
All Primary and Standby Alarms, Reports, Trends, and I/O Servers are now defined
using the Project Editor. This involves specifying a network address and a cluster for
each server.
Default Ports

97
Chapter: 3 Upgrading to CitectSCADA v7.20

Each server has a unique default port assigned to it. This default port may only be used
with that type of server. Attempting to use a default port on another type of server will
result in a compilation error of:
"Invalid port number (2073-2082,20222,21) are reserved"
The following table lists the default port numbers and their associated server type.

Default Port Legacy Port Server Type Server Role

21 N/A FTP Server Page downloads for IDC

IDC Internet Display Server/Client
communications

2073 N/A CTAPI CTAPI Communications

2074 N/A Client Cicode Debugging

2084 2075 Reports Reports Server communications

Server

2080 2076 Alarm Server Alarm Server communications

2085 2077 Trends Trends Server communications

Server

2078 N/A I/O Server Legacy I/O Communications

2080 2076 Alarm Server Alarm Properties Connector

2082 2078 (Client I/O Server Publish Subscribe I/O Server

server com- Communications
munication only)

20222 N/A ODBC ODBC Server

For details on configuring each type of server refer to:

l Alarm Server Definitions
l Reports Server Definitions
l Trends Server Definitions
l I/O Server Definitions

98
 Chapter: 3 Upgrading to CitectSCADA v7.20

Configure Tags to Use Clustering

If you have defined multiple clusters, you can configure alarms, reports, trends, SPC
tags, and accumulators to run on particular clusters. Using the Project Editor, you can
now specify the appropriate cluster for each tag.
l Configure Alarm Tags to use Clustering
l Configure Report Tags to use Clustering
l Configure Trend Tags to use Clustering
l Configure SPC Tags to use Clustering
l Configure Accumulators to use Clustering

Configure Alarm Tags to use Clustering

In the Project Editor, select Alarms, and then the type of Alarm you are configuring. The
dialog box for the chosen alarm type displays:
For each alarm, in the Cluster Name field, select the name of the cluster that will run the
alarm. If there is only one cluster defined in the project, you can leave this field blank.
The alarms will default to the defined cluster.
If the project has multiple clusters, and you do not select a cluster name in this dialog,
then CitectSCADA considers the alarm to run on defined clusters.
Using the F2 key in the Alarm Server Definitions dialog, open the extended properties
page and set the Publish Alarm Properties to "True" if you want the alarm properties to
be published and be viewed as normal variable tags, and have the Alarm Server listen
as if it were an I/O connector.
Click Replace to save the changes.
See Also
Configure Report Tags to use Clustering

Configure Report Tags to use Clustering

In the Project Editor, select System | Reports. The Reports dialog box will display:
For each report, in the Cluster Name field, select the cluster that will run the report. If
there is only one cluster defined in the project, you can leave this field blank. The reports
will default to the defined cluster.
If the project has multiple clusters, and you do not select a cluster in this dialog, then
CitectSCADA considers the report to run on defined clusters.
Click Replace to save the changes.

99
Chapter: 3 Upgrading to CitectSCADA v7.20

See Also
Configure Trend Tags to use Clustering

Configure Trend Tags to use Clustering

In the Project Editor, select Tags | Trend Tags. The Trend Tags dialog box will display:
For each trend, in the Cluster Name field, select the cluster that will run the trend. If
there is only one cluster defined in the project, you can leave this field blank. The trends
will default to the defined cluster.
If the project has multiple clusters, and you do not select a cluster in this dialog, Citect-
SCADA considers the trend to run on defined clusters.
Click Replace to save the changes.
See Also
Configure SPC Tags to use Clustering

Configure SPC Tags to use Clustering

In the Project Editor, select Tags | SPC Tags. The SPC Tags dialog box will display:
For each SPC tag, in the Cluster Name field, select the cluster that will run the SPC tag.
If there is only one cluster defined in the project, you can leave this field blank. The SPC
tags will default to the defined cluster.
If the project has multiple clusters, and you do not select a cluster in this dialog, Citect-
SCADA considers the tag to run on defined clusters.
Click Replace to save the changes.
See Also
Configure Accumulators to use Clustering

Configure Accumulators to use Clustering

In the Project Editor, select System | Accumulators. The Accumulators dialog box will
display:
For each accumulator, in the Cluster Name field, select the cluster that will run the
accumulator. If the project has only one cluster defined, you can leave this field blank.
The accumulator will default to the defined cluster.
If the project has multiple clusters, and you do not select a cluster in this dialog, Citect-
SCADA considers the accumulator to run on defined clusters.
Click Replace to save the changes.
See Also
Compile the Project

100
 Chapter: 3 Upgrading to CitectSCADA v7.20

Configuring Multiple Monitor Support

Multiple monitors are now supported in the core product instead of within a set of tem-
plates. This means you can display an existing project across multiple monitors by
adjusting a set of multi-monitor parameters.
While the standard built-in functions work seamlessly in a multi-monitor environment,
you may need to check whether a custom configuration functions correctly in multiple
windows simultaneously.
See Also
Working with Multiple Monitors
MultiMonitors Parameters

Compile the Project

Once you have configured your project, compile it and verify that there are no errors.
At this stage you may want to reconfigure some of your Cicode to support online
changes. Particularly the AssInfo and TagInfo functions that will be deprecated in future
versions of the software. In most cases they can be replaced with the functions AssIn-
foEx and TagInfoEx.

Run Computer Setup Wizard

Run the Computer Setup Wizard for each computer running the project. At each stage of
the Wizard, configure the appropriate settings for that computer.

Note:If updating projects created using previous versions of CitectSCADA, check that
the Computer Role Setup Page has the correct process mode selected.

See Also
Running the Computer Setup Wizard

Troubleshooting
Carefully consider the following results when upgrading to CitectSCADAv7.20:
l Compiler Errors
l Upgrading a Project that uses Distributed Servers

101
Chapter: 3 Upgrading to CitectSCADA v7.20

Compiler Errors
Before you configure your project to run in version 7.0, compiling the project will gen-
erate a number of compiler errors. These may include messages concerning deprecated
and deleted functions, as well as the detected error "No Clusters defined". This detected
error will be resolved once you define a cluster in the project.
See Also
Troubleshooting

Upgrading a Project that uses Distributed Servers

If you have implemented clustering in Version 6.x using Distributed Servers, a Global
Include Project, and Cluster Projects, configure your project to use clustering in version
7.0.
The existing structure of the Global Display Project and Cluster Projects can remain the
same (that is, the Global Display Project includes each of the Cluster Projects).
The following points describe a recommended project structure for clustering in version
7.0:
l Include a separate communications project in the Global Display Project. In this
project, it is recommended that you define only the Network Addresses, Clusters, and
Servers.

Note: Defining a separate communications project means that when the Global
Display Project compiles, it has the communications information without needing
to load the data from the Cluster Projects.

l In each Cluster Project, specify the appropriate cluster for alarms, trends, reports, SPC
tags, and accumulators.
l You may need to modify the buttons and pages in the Global Display Project, par-
ticularly if they are using Cluster functions which have been modified or deprecated.

102
Chapter: 4 About CitectSCADA
CitectSCADA is a Supervisory Control and Data Acquisition (SCADA) solution that is
used to manage and monitor processes in manufacturing, primary production, utilities
delivery and facilities management.
The graphics, controls, configuration data and programming associated with a Citect-
SCADA installation is configured and implemented through projects. A project acts as a
digital representation of your production facility that is deployed in tandem with your
plant infrastructure, allowing the entire system to be monitored and controlled in real-
time.

Dynamic-point count licensing

In CitectSCADA 6.10 or earlier, multiple tags that share the same I/O device address will
be counted as a single I/O point. This is calculated at compilation time and the compiler
will report the number I/O points used in a project and is referred to as the Static Point
Count. Any other tags used in super genies, read/written to via CTAPI, ODBC, DDE,
TagRead() and TagWrite() are counted at runtime and are referred to the Dynamic Point
Count. Thus, the total I/O point count will be equal to Dynamic Count plus Static Count,
which is calculated at runtime.

However, from CitectSCADA 7.0 the compiler does not generate any static point count
any more. CitectSCADA counts I/O device addresses dynamically at runtime. This
includes tags used by alarms, trends, reports, events, pages, in Super Genies, use of the
TagRead() and TagWrite() Cicode functions, or read or written to using DDE, ODBC, or
the CTAPI. A particular variable tag is only counted towards your point count the first
time it is requested. That is, even though you may have configured a certain tag on a par-
ticular page in your project, unless you navigate to that page and request the data, the
variable tag will not be counted towards your point count.

In addition to this, there have been a number of other changes that have been made to
the licensing structure from CitectSCADA 7.0. These are listed below:
l I/O point count is now tag based not address based. For example, two tags that use
the same PLC address will be counted twice. If two trend tags use the same variable
tag, it will be counted once. The same applies to alarms.
l For the multi-process mode, each server component will accumulate its own point
count. The server component point count is the count added up from each server

103
Chapter: 4 About CitectSCADA

component -if two server components use the same tags, say alarm and trend, the
tags will be counted twice when the point count gets totaled.
l For the multi-process mode, the client component will also accumulate its own point
count including super genie and CTAPI tags.
l For the multi-process mode, the machine point count will be the point count on the
client component or the point count added up from each server component, which-
ever is bigger. For example, if the total point count for each server component is 100,
and the client component point count including CTAPI and super genies is 95, the
kernel "General" window will show 100. If the client component point count reaches
120 later and the server component point count still remains 100, the kernel "Gen-
eral" window will show 120.
l Reading properties of a tag with TagGetProperty() will cause that tag to be included
in the point count, even if the value is not read.
l Writing to local variables or disk IO variable tags via OPC etc will also increase the
point count. For example, if you use an OPC client to write to a local variable, each
local variable will be counted once, the first time it is used.

Configuring a CitectSCADA project

Initially you use CitectSCADA's configuration environment to identify and address the
devices and datasources included in a project by tagging the variables associated with
each.
You can then use templates to design graphics pages that reference these tags, creating
an interface your staff can use to view and control the system.
With these graphics pages, you can:
l use animations to display the operating status and performance of a plant
l provide operators with centralized or local control of production equipment using
keyboard commands and graphical tools
l develop a multi-layered security system that controls user access according to func-
tional groups or geographical areas
l implement historical and millisecond trending of tag data in a graphical format.
A powerful scripting language is also included to enable customized, programmable
functionality.

104
 Chapter: 4 About CitectSCADA

Deploying CitectSCADA
The project is then deployed across a client-server network architecture. The servers are
used to manage communication with plant equipment and collate production data,
while the clients provide the interface for operators and managers to assess and interact
with the system.
This architecture allows the flexibility to adapt CitectSCADA to any production scenario,
with support for scalability, server clustering, and system redundancy.

Running a project
When a project is eventually compiled and implemented in runtime, your production
staff can visually monitor the system, initiate production processes and respond to
alarm conditions.
Historical and trend data can also be collated and distributed to assess operational per-
formance metrics such as production volume, efficiency, and maintenance requirements.

105
Chapter: 4 About CitectSCADA

106
Chapter: 5 Tools
CitectSCADA's architecture can be divided into three distinct areas of functionality:
l Configuration
l Runtime
l Drivers
Configuration involves the tasks necessary to prepare and build a project, while runtime
is the implementation of a project in a live production environment.
Drivers enable communication with devices via a number of communication protocols.
The driver defines the specific project settings necessary for CitectSCADA to com-
municate with a particular device.
When considering the tools included with CitectSCADA, it is easiest to look at their roles
in either configuration or runtime.
See Also
Configuration Tools
Runtime Tools
Drivers

Configuration Tools
The following tools enable you to configure a project and its components, and set up
computers to use CitectSCADA:

CitectSCADA Explorer The application used to create and

manage your projects. It displays a
list of projects, and provides direct
access to the components of each.
You can use Explorer to rename,
back up, restore or delete a project.

See Administering Projects

CitectSCADA Project Editor The application used to create and

manage the configuration infor-
mation for your project, including
tags, alarms, system components,
and communications components

See Components of a project

107
Chapter: 5 Tools

CitectSCADA Graphics Builder The application used to design,

create, and edit the graphics com-
ponents of a project, including tem-
plates, graphics objects, symbols,
genies, and Super Genies

See Defining and Drawing Graphics

Pages

Computer Setup Editor A utility for editing configuration

files and generating reports to com-
pare and analyze files

See Computer Setup Editor online

help

Computer Setup Wizard A wizard that allows you to cus-

tomize a computer's setup and
define its role and function

See Running the Computer Setup

Wizard

Runtime Tools
The following tools enable you to run, monitor, and control projects during runtime:.

CitectSCADA Web Displays a live CitectSCADA project within

Client a web browser

See CitectSCADA Web Client

Internet Display Client A computer used to run a CitectSCADA

project over the Internet from a remote
location.

See Running Your System Over the Inter-

net

Process Analyst An Active X control that allows you to com-

pare and analyze historical and real-time
trend and alarm data during runtime.

See "Configuring the Process Analyst" in

the Process Analyst User Guide

108
 Chapter: 5 Tools

CitectSCADA Runtime An application used to manage and control

Manager the CPU configuration of the project, and
the running state of each component

See "Launching Runtime Manager" in the

Runtime Manager online help

Drivers
CitectSCADA can communicate with an array of I/O Devices, including PLCs (Pro-
grammable Logic Controllers), loop controllers, and distributed control systems (DCS).
The I/O Devices may be local (directly connected to an I/O Server) or remote (connected
to CitectSCADA via an intermediate communications means like a phone line).
Drivers enable communication with devices via a number of communication protocols
(including Ethernet, TCP/IP, and Serial). The driver defines the specific project settings
necessary for CitectSCADA to communicate with a particular device. This includes infor-
mation about:
l Boards
l Ports
l Devices
l Tag addressing
For detailed information on drivers and how to use them in your system, see Com-
municating with I/O Devices

109
Chapter: 5 Tools

110
Chapter: 6 Components of a project
The components you can incorporate in a project are logically divided across the fol-
lowing categories:
l Graphics components
l Tags
l Alarms
l System components
l Communications components
l I/OServer components
l Cicode / CitectVBA
These categories are represented in Citect Explorer through the set of folders associated
with each project.
As you build a project, the components you include are listed in the relevant project
folder. Selecting an item from one of these folders launches the selected component in
the tool necessary to edit its properties.
See Also
Graphics components
Tags
Alarms
System components
Communications components
I/OServer components
Cicode / CitectVBA

Graphics components
The graphical components of a project represent the content used to create the screens
presented on clients. They include:

Pages The basis for the screen layouts

See Defining and Drawing Graphics Pages

Tem- A collection of page layouts used to standardize display screens

plates

111
Chapter: 6 Components of a project

See Using Page Templates

Symbols Graphics objects stored in a library for reuse

See Using symbols

Genies Objects that group multiple graphical and functional elements for
easy duplication

See Understanding Genies

Super Genies that can pass device-specific information at runtime.

Genies
See Using Super Genies

As you create project pages in Graphics Builder, the included components are added to
the relevant subdirectory in the current project's Graphics folder.

Tags
Tags are used to identify the end points in the infrastructure you are using CitectSCADA
to monitor and control. The name you give to a tag becomes a label for a register
address, allowing it to be intuitively applied across graphics pages and in alarm noti-
fications.
Three tag types are included in a project's Tags folder in Citect Explorer:

Variable used to label register addresses

tags
See Tagging Process Variables

Trend used to label tags for data trending

tags
See Trending Data

SPC tags used to label tags according to Statistical Process Control prin-
ciples

See SPC Tags

Selecting one of these tag types in Citect Explorer calls up the associated configuration
dialog in Project Editor.

112
 Chapter: 6 Components of a project

Alarms
Alarms are used to identify conditions in a system that require attention. CitectSCADA
supports seven different alarm types:

Digital

See Digital Alarms

Analog

See Analog Alarms

Time-stamped

See Time-stamped Alarms

Advanced

See Advanced Alarms

Multi-Digital

See Multi-digital Alarms

Time-stamped Digital

See Time-stamped Digital Alarms

Time-stamped Analog

See Time-stamped Analog Alarms

You can also use alarm categories within your project to help identify and manage
alarms.

System components
The system components of a project allow you to customize, manage, and track your run-
time system. They include:

Keyboard A meaningful name assigned to a keyboard key

key
See Keyboard Keys

113
Chapter: 6 Components of a project

Keyboard Key sequences with associated instructions

commands
See System Keyboard Commands

Reports Customized presentation of runtime data and special conditions

See Reporting Information

Events Commands that execute in response to specific runtime

triggers, such as a Cicode expression or variable tag. When the
event trigger is true, the command will execute

See Configuring Events

Accumu- Variable tags tracking continuous runtime data. Data can be

lators monitored and displayed by animating or trending the variable
tags

See Using Accumulators

Devices Components that can transfer high-level data to other com-

ponents such as RTF files, ASCII files, and printers

See Configuring Devices

Users User profiles to restrict and grant access to the runtime system

See Adding User Records

Groups Groups of system areas used to simplify the management of

user profiles

See Defining Areas

Label System-wide substitutions for commonly used commands and

expressions

See Using Labels

Fonts Fonts for displaying alarms and objects

See Using System Fonts

Param- Built-in operating settings for fine tuning the runtime system
eters
See "Citect.ini File Parameters" in the CitectSCADA Technical Ref-
erence

Included Predefined projects with database records automatically

projects included in user projects

114
 Chapter: 6 Components of a project

See Including projects

Communications components
The communications components of a project are the configured representation of the
communications hardware in your system. They include:

Board Hardware enabling various types of communication with I/O

Devices

See Boards Properties

Port The physical connection between the board and the I/O Device

See Ports Properties

Modem Hardware used to connect CitectSCADA to a dial-up remote I/O

Device.

See To set up a modem in CitectSCADA:

I/O An item of equipment that communicates with plant-floor con-

Devices trol or monitoring equipment

See I/O Devices Properties

I/O Device The unique address of an I/O Device CitectSCADA is com-

address municating with

I/O Server components

The server components of a project are the configured representation of the server com-
puters in your system. They include:

Cluster Logical groups of servers running across several physical

machines

See Implementing Clustering

Network The IP addresses or machine names of the primary and standby

addresses servers

See Network Address Definitions

115
Chapter: 6 Components of a project

Alarms Servers that monitor alarms and display them on the appro-
servers priate client(s)

Reports Servers that control the processing of reports

servers

Trends Servers that control the accumulation and logging of trend infor-
Servers mation

I/O Servers Dedicated communications servers that exchange data between

I/O Devices and clients

Cicode / CitectVBA
CitectSCADA offers two programming languages with which you can control and
manipulate CitectSCADA components:

Cicode A structured programming language designed for use in Citect-

SCADA to monitor and control equipment.

See Introducing Cicode.

A Visual Basic for Applications (VBA) and VBScript-compatible

CitectVBA Basic scripting language.

See Introducing CitectVBA.

116
Chapter: 7 Typical system scenarios
The scenarios described in this chapter demonstrate how CitectSCADA can be used to
support typical processes found in primary production, utilities delivery, and man-
ufacturing.
In reality, a project will incorporate a combination of the scenarios described here, with a
high degree of customization and scalability. However, these examples have been sim-
plified to demonstrate how CitectSCADA can be configured and deployed to meet the
specific requirements of a production system.
Standalone system
Every component of a system runs on a single computer. See Standalone system.
Distributed I/O system
CitectSCADA is used to monitor and manage distributed devices that are each connected
to remote I/O Servers. See Distributed I/O system.
Redundant server system
One or more of the servers associated with a system are duplicated and defined as pri-
mary and standby units, allowing the system to keep running in the event one of the
servers becomes inoperative. See Redundant server system.
Client-server system
The servers and clients associated with a system are independently distributed across a
number of computers on a network, offering greater accessibility and performance ben-
efits. See Client-Server system
Redundant and distributed control system
Remote or geographically separate sections of a production system have fully oper-
ational sub-systems in place that are monitored and controlled locally. If such a sub-sys-
tem becomes partially or wholly inoperative in a manner preventing local control, this
arrangement allows remote Control Clients to take control of the affected sub-system. See
Redundant and distributed control system.
Cluster controlled system
A production system is organized into discrete areas being monitored by operators
within each area. However, there is also a level of control that supervises every area of
the system. See Clustered control system.
Load sharing system

117
Chapter: 7 Typical system scenarios

The system splits the load of an otherwise stressed system across multiple machines,
better utilizing the available infrastructure. See Load sharing system.
See Also
Cluster Connections Configuration

Standalone system
A standalone installation of CitectSCADA runs every server and client component of a
system on a single computer. These include:
l I/O Server
l Alarm Server
l Trends Server
l Reports Server
l Control Client
This allows CitectSCADA to be run as a small, self contained system.

Note: You can run the server and client components of a standalone system as a sin-
gle-process or multi-process system. It is recommended that a single- process setup
only be used as a short term solution for your control system, or to run dem-
onstrations and test projects. Adding redundancy to your system will make it more
reliable and more efficient.

Distributed I/O system

This scenario demonstrates a method of connecting CitectSCADA to a number of devices
that are distributed across several sites over a wide geographical area.
Instead of attempting to connect devices directly via a remote connection, an I/O Server
is placed at each site, enabling communication to be managed within the system.

118
 Chapter: 7 Typical system scenarios

This model is also useful in plants that contain devices with a serial port or limited com-
munications capabilities. By placing I/O Servers on the factory floor to interface with
these devices, you can optimize communications on slow or low-bandwidth networks
and improve overall performance.
Despite the geographical distribution of I/O Servers across many sites, this type of sys-
tem can be configured as a single cluster system, as a cluster is able to support many I/O
Servers.
The diagram below demonstrates how to approach the deployment of this type of sys-
tem across the server machines using a single cluster.

A second cluster will only become necessary if your project requirements call for more
than one redundant pair of alarms, trends or reports servers.

119
Chapter: 7 Typical system scenarios

Client-Server system
CitectSCADA's client-server architecture allows the components of a system to be dis-
tributed across a number of computers on a LAN, creating a system that offers geo-
graphical flexibility and performance benefits.
Each component is simply identified within the project by an address, allowing the loca-
tion and hardware requirements for each to be considered independently.

The diagram below demonstrates how this example can still be configured within a sin-
gle cluster.

Each server also acts as a Control Client across the system architecture.

120
 Chapter: 7 Typical system scenarios

Redundant server system

The ability to define primary and standby servers within a project allows hardware
redundancy to be built into your system infrastructure. This helps prevent situations
where an error on one server results in the overall system becoming inoperative. Sys-
tems of this type are especially beneficial when service continuity and/or secure data col-
lection are important.

In the case of I/O Server redundancy, a standby server is maintained in parallel to the
primary server. If a hardware error is detected, the standby server can assume control of
device communication with minimal interruption to the system. You can also use redun-
dant I/O Servers to split the processing load.
Alarm, report and Trends Servers can also be implemented as redundant servers. This
improves the likelihood that clients will continue to have access to data from a standby
server in the case a primary server becomes inoperative. CitectSCADA maintains iden-
tical data on both servers.
In the diagram below, the primary and standby I/O Servers are deployed independently,
while the alarms, trends and reports servers are run as separate processes on common
primary and standby computers. In this case, the entire system can be configured as a
single cluster.

121
Chapter: 7 Typical system scenarios

Clustered control system

In this scenario, the system is organized into discrete sites being controlled by local oper-
ators, and supported by local redundant servers. At the same time, there is a level of
management that requires sites across the system to be monitored simultaneously from a
central control room.

Each site is represented in the project with a separate cluster, grouping its primary and
standby servers. Clients at each site are only interested in the local cluster, whereas
clients at the central control room are able to view every cluster.

122
 Chapter: 7 Typical system scenarios

The deployment of a control room scenario is fairly straightforward, as each site can be
addressed independently within its own cluster. The control room itself only needs Con-
trol Clients.
The deployment of servers could be mapped out as follows:

CitectSCADA's support for dynamic clustering means each site can be monitored and
controlled from the central control room if necessary. For example, if an operator at a par-
ticular site only works during regular business hours, then the monitoring can be
switched to the central control room after hours.

Redundant and distributed control system

In this scenario, a project represents a number of locally operated sites each containing
its own set of servers and clients. For example, a number of pumping stations across a
water distribution system, or multiple production lines in a manufacturing facility. How-
ever, there is a requirement for monitoring to continue in the event the system at one of
the sites becomes inoperative.
This is achieved by distributing the primary and standby servers across the different
sites, or by placing the standby servers in a central location.
Clustering is used to define the role of the different servers at each site, which can be
viewed in a common project running on every client. This means Site A can be mon-
itored from Site B, and vice versa, if a system becomes inoperative at one of the sites.

123
Chapter: 7 Typical system scenarios

The example above would require the creation of two clusters, so that the project can
include two sets of primary and standby servers. The clusters represent the redundant
pairs of servers, and would be deployed across the two sites as follows:

The clusters offer the benefit of keeping a logical structure to the project during con-
figuration, despite the unusual distribution of redundant server pairs.

124
 Chapter: 7 Typical system scenarios

Load sharing system

Load sharing of system components across different computers and CPUs means the
work load of a potentially stressed system can be split across multiple machines, better
utilizing the available infrastructure.
For example, managing alarms can draw heavily on a CPU's performance, while trend-
ing data can use a lot of disk space. By assigning your Trends and Alarm Servers to dif-
ferent processes on a shared computer, an Alarm Server can be used as a standby
Trends Server, making practical use of idle disk space.
This approach can used to improve network performance, data access times, and gen-
eral system stability.
If you introduce clustering, you have the flexibility to run multiple servers of the same
type on a single computer. As long as a client has access to every cluster configured in a
project, it doesn't matter if a set of servers is distributed across a number of clusters.
In the diagram below, two servers have been configured to act as standby units for each
other, supporting two sets of redundant Trends and Alarm Servers.

Both machines have an even balance of Trends and Alarm Servers, making effective use
of the CPU and disk space. By distributing the servers across two clusters, the servers
are also able to act as redundant units to each other. This has reduced the necessary
number of computers from a maximum of eight down to just two.

125
Chapter: 7 Typical system scenarios

126
Using CitectSCADA

This section contains information on using CitectSCADA and

describes the following:
Planning a Project
Administering Projects
Securing Projects
Configuring Your System
Implementing Clustering
Building Redundancy Into Your System
Tagging Process Variables
Linking, Importing, and Exporting Tags
Defining and Drawing Graphics Pages
Configuring and Processing Alarms
Configuring Events
Using Accumulators
Logging and Trending Data
Understanding Statistical Process Control
Reporting Information
Using Security
Using Labels
Using Devices
Exchanging Data with Other Applications
Using Genies and Super Genies
Working with Multi-Language Projects
Using OPC Server DA2.0
Communicating with I/O Devices
Using the Communications Express Wizard
Building Your Project

127
128
Chapter: 8 Planning a Project
This chapter describes the planning phase of a CitectSCADA system.
A planned approach to the design and configuration of your system allows you to make
optimal use of the product's features and performance capabilities, and helps you meet
the requirements of your production facility. It also helps avoid unnecessary rework dur-
ing the configuration of your project.
It is important to consider the following when planning a system:
1. The Physical Layout of a Plant
2. Operational Requirements
3. Project Design
4. Building Your Project
5. Setting up Your Computers

The Physical Layout of a Plant

You need to consider the physical layout of the plant where you would like to imple-
ment CitectSCADA.
This information will help determine the architecture of your project, and many of its
operational requirements. It also allows you to assess the available equipment, to deter-
mine if any additions or modifications are necessary.
Consider the following items when examining the physical layout of a plant:

Geography
The physical layout of your facility, including whether the plant is spread across mul-
tiple geographical locations or specific areas of functionality, such as a number of pro-
duction lines running in parallel.

Machinery
The equipment (machines, physical connections, and devices) in your plant that will be
monitored and controlled by your system.

129
Chapter: 8 Planning a Project

Existing computer hardware

The computers that currently exist within your facility to support CitectSCADA's client-
server architecture. The specifications and limitations of the existing equipment will
have to be considered to determine if the operational requirements of your system can be
supported.

Network configuration
The current configuration of the network that will support your system and its com-
munication with plant equipment. This will include the protocols used, the performance
capabilities of the system, and security.
See Also
Operational Requirements

Operational Requirements
By developing a set of operational requirements for your project, you'll define a com-
prehensive list of needs and objectives that your system needs to support to effectively
monitor and control production.
The things consider to determine the operational requirements include:
Architecture
Security
Reliability
Monitoring
Data collection

Architecture

Production Processes
The operating processes within your production facility need to be considered to deter-
mine how they can be logically represented and supported within your project. If the
processes are dependent on each other, you also need to consider how the interaction
between them will be managed, particularly if unexpected circumstances occur.

130
 Chapter: 8 Planning a Project

Security
When planning a project you need to consider who will be using the system, and which
parts of a project they will need to have access to. To effectively do this you will need to
understand how roles, privileges and areas work together to enable you to develop a
secure CitectSCADA system.
See Also
Users and Areas

Reliability
The nature of your production processes will determine the importance of system relia-
bility. Consider issues such as:
l The need for uninterrupted operation
l the impact and cost of down-time
l the need to collect and protect system data
l the severity of alarm conditions.
This will help determine if your project needs to include redundancy, the type of redun-
dancy necessary, and the most appropriate way to implement it.
For more information, refer to Redundancy.

Monitoring
System monitoring is a key function of a SCADA system and needs to be considered in
terms of the necessary interaction between personnel and production processes.
You need to consider if the delivery of data is time-critical. For example, alarm con-
ditions need to be presented in real time, trend data may be delivered with a slight
delay, while maintenance data can be accumulated and viewed as necessary.
The system may also need to be monitored at different levels, from machinery operators
to control room personnel managing plant-wide processes. For each level of monitoring,
consider the data that needs to be presented, and the specific performance and diag-
nostic conditions that need to be flagged.

Data collection
Consider the kind of data you need to collect from the production process, and how it
will be used. Depending on your requirements, CitectSCADA can collect:

131
Chapter: 8 Planning a Project

l Production data
l Purchasing requirements
l Batch processing statistics
l Equipment status and performance data
l Maintenance scheduling information
l Process performance data
l Dynamic visual analysis data
Carefully consider an assessment of the likely amount of accumulated data, as it will sig-
nificantly impact on your computer hardware and network performance requirements.
For more information, refer to Logging and Trending Data.
See Also
Project Design

Project Design
Once you have developed a clear set of operational requirements, you need to plan how
to design your project to best meet these requirements. When designing your project, con-
sider the following issues:
Naming Standards
Page Templates
Genies and Super Genies
Clustering
Included projects
Redundancy

Naming Standards
By adopting naming standards, you can configure project components with meaningful
names that convey useful information, such as the location or type of component. The
standard that you use depends on the type of information that will be useful to system
operators. A naming standard helps promote consistency throughout the project, making
it easier to quickly identify components, and reducing duplication and user training.
Naming standards may be useful for devices, variable tags, reports, graphics objects,
and pages.
Reserved names

132
 Chapter: 8 Planning a Project

Some names such as IO_Server, Report_Server, Alarm_Server, Trend_Server, and Client

are reserved for use in the include project. Using one of these names for your server will
result in a compilation error. It is better to use names in your project that are meaningful
to your installation.

Page Templates
Page templates are predefined page layouts that you can use to build the display screens
(graphics pages) for your project. Templates allow you to create new pages quickly, and
allow your runtime system to have a consistent look and feel. They can incorporate
standard navigational and support tools that are common to every page. CitectSCADA
includes a number of standard templates, and you can also design new templates to suit
the requirements of your system.
See Also
Using Page Templates

Genies and Super Genies

Genies are like object templates that you can place on graphics pages to help simplify
the configuration of many similar devices. They group functional and graphical ele-
ments, and present device information using configurable string substitutions as place-
holders for specific tags or expressions. The information is then presented during
runtime.
Super Genies are genies that can be passed device-specific information at runtime. Super
Genies are useful for dynamic controls, like a popup switch that can be used to control
many devices.
See Also
Using Genies and Super Genies

Clustering
Clustering allows you to group independent sets of CitectSCADA's server components
within a single project, allowing multiple systems to be monitored and controlled simul-
taneously.
The most appropriate configuration will depend on the requirements for the solution to
be deployed and the environment in which it is being deployed.
Some typical clustering configurations include:
l Standalone system
l Distributed I/O system

133
Chapter: 8 Planning a Project

l Client-Server system
l Redundant server system
l Clustered control system
l Redundant and distributed control system
l Load sharing system
CitectSCADA's implementation of clustering allows for the flexible deployment of graph-
ics pages that can access data from different clusters dynamically. A page can be allo-
cated a cluster context when it is called, and any elements on that page will be assigned
the same cluster, unless they have a cluster explicitly specified. See About cluster
context.
See Also
Typical system scenarios
Rules of Clustering

About cluster context

Many CitectSCADA items require a cluster to be specified in order for them to work cor-
rectly. This ClusterName can either be explicitly specified when the item is called or dis-
played, or an item can use the default cluster context of the calling process or page. If
your system has only one cluster, then no cluster name needs to be specified. See Cluster
context rules.
Cluster context, therefore, is the default cluster used for tag resolution and execution of
expressions and Cicode functions. In the case of tags, a cluster is explicitly supplied by
prefixing the tag name with the cluster name. For built-in Cicode functions ClusterName
is usually an optional parameter.
Server processes (Alarm, Trend, Report) have their default cluster context set to their
own cluster, so that, for example, Alarm definitions that contain variable tags without
clusters explicitly supplied will attempt to resolve those tags to their own cluster. Cicode
tasks started from server code will inherit the servers cluster unless one is explicitly
given.
Graphics pages have no cluster context by default. A page's cluster can be supplied stat-
ically in the page appearance properties, can be inherited from a previous context, or can
be applied dynamically using an optional parameter in the Cicode function that dis-
played the page. Any Cicode tasks started from a page will inherit the cluster context of
that page.
See Also
Cluster context rules

134
 Chapter: 8 Planning a Project

Cluster context rules

1. Single cluster systems always use that cluster and do not require the use of cluster
prefixes.
2. Variable Tags referenced in an Alarms, Reports or Trends Server context are implic-
itly resolved to that cluster unless explicitly stated otherwise using a cluster prefix
such as ClusterName.TagName.
3. Cicode called in an Alarms, Reports or Trends Server context runs with the server's
cluster context as default.
4. Server to Server connections (for example, SPC Alarms) are within the cluster by
default.
5. Client pages can have a cluster context associated with them.
6. Client pages can be configured with a cluster context or inherit the cluster from the
previous (or parent) page.
7. Client pages can have the configured cluster context overridden dynamically at run-
time.
8. Client pages have no default cluster and do not inherit context in multi-cluster sys-
tems by default.
9. The TaskNew Cicode function inherits the caller's (either page or task) cluster context
unless explicitly overridden.
See Also
About cluster context

Included projects
If you have a large production environment, you can simplify the configuration and
management of your system by designing your project as a collection of smaller
"included" projects.
Included projects can operate independently, however, they share resources and operate
interdependently during runtime. This means you can create and test projects rep-
resenting functional or physical sections of a plant, and then gradually bring them
online. Ongoing maintenance can then be managed with a minimal impact on pro-
duction.
For more information, refer to Including projects.

135
Chapter: 8 Planning a Project

Redundancy
Redundancy can be implemented at different levels of your system, depending on the
reliability requirements of your project. The following types of redundancy are available:

Device Redundancy
Multiple data paths to a device can be configured within CitectSCADA. Therefore, if the
primary path becomes unavailable, data can still be monitored over the secondary path.

Server Redundancy
Primary and Standby Alarms, Reports, and Trends Servers can be configured so that if a
primary server becomes unavailable to process a client's request, the request can be chan-
nelled to a standby server for processing.

LAN Redundancy
To avoid service interruptions when the primary network isn't operating, a redundant
LAN can be implemented that will provide an alternative path to a server if necessary.
See Also
Building Redundancy Into Your System

Building Your Project

Once you have determined your project requirements and design, you can begin imple-
menting the design in CitectSCADA.
The following topics will assist you to identify the project components and options that
you need to implement.
Projects
Setting up I/O Device Communication
Graphics components
Alarms
Data Collection
Users and Areas
System Components

136
 Chapter: 8 Planning a Project

Projects
You will first need to create a new project, and familiarize yourself with tasks like stor-
ing, including, and archiving it.
Before running the project, the process of compiling it will alert you to any errors in the
configuration.
See Also
Building Your CitectSCADA Project
Administering Projects
Compiling the Project

Setting up I/O Device Communication

CitectSCADA can be configured to communicate with I/O Devices from a number of dif-
ferent vendors. To establish communications with an I/O Device, you will need to per-
form the following steps:
l Install the relevant device driver
l Configure the hardware and software necessary by the device
l Set up a test project to test the communications channel
l Configure a variable tag for each data point on the I/O Device that you want to com-
municate with.
l Configure the device in the project, either manually or using the Communications
Express Wizard.
See Also
Using the Communications Express Wizard
Communicating with I/O Devices
Tagging Process Variables

Graphics Components
Graphics components are the means through which operators view and interact with
the runtime system. Graphics pages can be designed to provide operators at different sys-
tem areas or levels with relevant monitoring and control options.
To create graphics components that meet your operational requirements, be familiar with
how to create graphics pages, use page templates, and configure graphical objects like
Genies and Super Genies.
See Also
Defining and Drawing Graphics Pages

137
Chapter: 8 Planning a Project

Using Genies and Super Genies

Using Objects
Defining Common Object Properties.
Understanding Object Types

Alarms
The CitectSCADA alarm system monitors your production processes and alerts operators
to unexpected events that may require attention.
There are two types of alarms that you may need to configure:
l Hardware alarms - alert you to inoperative or partially operative equipment
l Configured alarms - allowyou to specify relevant alarm conditions for your facility
(for example, the value of a variable tag monitoring the level, temperature, or status
of a specific piece of equipment). There are seven types of configured alarms, depend-
ing on the type of alarm condition you need to set up.
To help operators process alarms, you can create graphics pages that provide alarm
information (such as the action an operator needs to perform to correct the situation).
See Also
Configuring and Processing Alarms
Configured alarms
Formatting an Alarm Display

Data Collection
Data collection in CitectSCADA incorporates two main aspects:
l Trends - The trends system allows you to collect and monitor plant data. Depending
on your requirements, data can be collected on a periodic basis, or when a specific
event occurs. The data can then be saved to disk for analysis or displayed on a graph
or report. To use trends in your system, you will need to be familiar with how to con-
figure trend tags and display trend data in a graph or report.
l Reports - Reports provide information on the status of your plant and processes. You
can configure reports with the following information so that they meet your oper-
ational requirements:
l Period/Trigger: Reports can be run on a request basis, periodically, or when a spe-
cific event occurs.
l Report format: You can use a text editor to create a file that specifies how a report
is displayed.
l Report output: Reports can be output to a file, device, or displayed on a graphics
page.

138
 Chapter: 8 Planning a Project

See Also
Logging and Trending Data
Reporting Information

Users and Areas

You can design security for your system which incorporates both of the following fea-
tures:
l Users - User accounts allow you to restrict access to your runtime system. Every user
needs to log in to the system with a user name and password to gain access. User
accounts can be set up for individuals or for groups of users.
l Areas - Areas allow you to define geographical or functional boundaries in your sys-
tem.You can then control both the access users have to different parts of the project,
and the tasks they can perform.
See Also
Using Security

System Components
CitectSCADA includes the following system components, which provide further options
for monitoring, control, and user interaction:
l Commands and Controls - Configurable keyboard commands and slider controls
allow operators to interact with the runtime system.
l Events - Events (such as variable tags or expressions) can be configured that trigger a
specific action, like a command.
l Accumulators - Accumulators track incremental runtime data. The data is stored as
variable tags in an I/O Device, and updated regularly while the trigger is active.
l Statistical Process Control - SPC allows to you to track quality by collecting and inter-
preting process variables associated with a product.
l Labels - System wide substitutions can be configured for commonly executed com-
mands and expressions.
l Devices - High-level CitectSCADA data (including reports and logs) can be trans-
ferred to other system elements such as printers, databases, or files.
l Remote Access - A project can be accessed remotely or wirelessly in the following
ways:
l CitectSCADA Web Client - The CitectSCADA Web Client allows you to view a
live project within a Web browser.
l Internet Display Client - An Internet Display Client can be used to run a runtime-
only version of a project over the Internet from a remote location.

139
Chapter: 8 Planning a Project

See Also
Defining Commands and Controls
Configuring Events
Using Accumulators
Understanding Statistical Process Control
Using Labels
Using Equipment
Using Devices
CitectSCADA Web Client
Running Your System Over the Internet
Exchanging Data with Other Applications

Setting up Your Computers

Once you have built your project, you need to configure each computer in your system.
The configuration information is stored on each computer in a Citect.ini file. The infor-
mation includes:
l The role the computer has in the Citect network
l The project being run
l The CPU Configuration
l The Citect Events enabled for each component
l The Cicode run for each component on startup
l The cluster configuration
l The security settings applied
The Computer Setup Wizard displays a series of pages where you can configure these
settings. The selected options are written to the Citect.ini file. run the wizard on each
computer as the final step before running your project.
See Also
Running the Computer Setup Wizard

Setting up CitectSCADA as an OPC data source

CitectSCADA OPC Server allows you to access data available in the CitectSCADA run-
time environment (for example from PLCs and databases) through any OPC Client appli-
cation (v1.0 or v2.0).

140
 Chapter: 8 Planning a Project

When CitectSCADA is used to monitor and control a plant, data from PLCs is collected
and displayed in the runtime environment. OPC Clients can access device and tag infor-
mation through the interface to the OPC Server, which in turn interacts with the CtAPI
interface to the Runtime. For details on how to configure the OPC Server, refer to Using
OPC Server DA2.0

141
Chapter: 8 Planning a Project

142
Chapter: 9 Administering Projects
CitectSCADA is a project-based application. This section of the help looks at the admin-
istrative tasks associated with creating, storing and maintaining your projects. It
includes:
l Managing your projects
l Archiving projects
l Including projects
l Working with the Project Editor
l Using Find and Replace in a project

Managing your projects

This section of the help explains how Citect Explorer is used to manage the admin-
istration of your projects. It includes the following topics:
l Creating a project
l Editing the properties of an existing project
l Copying projects
l Printing project details
l Deleting a project
l Linking projects
l Time Synchronization

Creating a project
There are two ways to create a new project:
l Use a pre-defined starter project
l Create a project from scratch
To base a project on an existing starter project:

1. Start Citect Explorer.

2. Choose New Project from the File menu, or click the New Project button.
3. Type a name for your project and choose a location for the files. This is mandatory.

143
Chapter: 9 Administering Projects

4. Enter a Description, and the Location where the new project files are stored.
5. Click the Create project based on starter project checkbox.
6. Choose the project on which you want to base your new project.
7. Click OK.
The starter project will contain pages, roles and other features that will help you quickly
get started with you project. Exact features will vary based on the template you base
your project on. For example, the Tab_Style starter project will contain:
l A cluster named "Cluster1".
l A role named "Administrators" which is linked to the "BUILTIN\Administrators"
Windows group and have global privilege of 8.
l Pages of Alarm, Summary, Disabled, Hardware, ProcessAnalyst and !Pr-
ocessAnalystPopup based on the relevant templates found in the Tab_Style_Include
project.
The newly created project will be immediately compilable, and will contain a basic level
of built-in functions such as viewing alarms and trends.
To create a project from scratch
To make it easier to configure a project from scratch, follow these steps:
1. Start Citect Explorer.
2. Choose New Project from the File menu, or click the New Project button.
3. Type a name for your project and choose a location for the files. This is mandatory.
4. Enter a Description, and the Location where the new project files are stored.
5. Select a Template style and Template resolution to set the appearance of the graph-
ics pages.
6. Click OK.
If creating a project based on the tab style templates, don't include pages based on tem-
plates that use a different style, including the earlier CSV_Include project. Doing so
might affect functionality.
See Also
New Project dialog
Creating a New Tab Template Project

New Project dialog

This dialog box lets you create a new project. To create a new project, enter a value in the
Name field (the other field entries are optional), then click OK.
Once created, project properties can be viewed and edited using the Project Properties
dialog, which contains the items described below.

144
 Chapter: 9 Administering Projects

Name
A unique name for the project. The project name is restricted to 64 characters. It can con-
tain any characters other than characters in the Windows file naming rules "*|\{}:<>?/;'
Since the project name is a unique identifier, CitectSCADA does not permit you to create
or restore a project with the same name.
Description
A description of the project. This field is useful for giving an explanation of the role of
the project. You are urged to complete this field.
Location
The directory path where the project files are stored. As the Name field is entered, the
directory is automatically generated in the Location field. You can override this by man-
ually entering the location or clicking Browse.
Create project based on starter project
Select this option if you want to create a project based on the built-in starter projects.
Choose the project style from the Project drop down list that is displayed when this
option is selected.
You can create custom starter projects by placing *.ctz backup files in the
<User>/<Data>/Starter folder (where <User>/<Data> is the directory you chose during
installation). The [CtEdit]Starter parameter can be used to change this default path.
[Page defaults] Template style
The style (appearance) of the graphics pages in the runtime system. The style you select
is the default style for any new pages you add to the project. You can change the style of
existing pages and templates using the Page Properties, accessed through the Graphics
Builder.
Most users prefer the Standard style. You can view the pre-defined styles by looking in
the Include project under Graphics, Templates.
[Page defaults] Template resolution
The default screen resolution of the standard graphics pages (such as alarms pages and
standard trend pages):

Screen Type Screen Width (pixels) Screen Height (pixels)

VGA 640 480

SVGA 800 600

XGA 1024 768

145
Chapter: 9 Administering Projects

Screen Type Screen Width (pixels) Screen Height (pixels)

SXGA 1280 1024

WUXGA 1920 1200

User **** ****

[Page defaults] Show template title bar

Determines whether to display the Windows title bar (at the top of each graphics page).
The title bar contains the title of the window, maximize, minimize and close buttons (at
the right hand end of the title bar), and the control menu button (at the left hand end of
the title bar).
To display a page in fullscreen (without a title bar), the size of the page needs to be the
same size as the display (or larger). If the page is smaller than the display, the title bar
still displays, even if fullscreen mode is enabled. Standard templates styles are available
for both page sizes.
[Page defaults] Background color
The background color that will be displayed in newly created graphics pages.

Editing the properties of an existing project

To edit the properties of an existing project:

1. Open Citect Explorer.

2. Select a project from the list.
3. Click the Properties button, or select Project Properties from the File menu.
4. Edit the properties in the Project Properties dialog.
5. Click OK to save your changes, or Cancel to abort.
Properties
Projects have Project General Properties and Project Page Properties.

Project General Properties

(General) Name

146
 Chapter: 9 Administering Projects

The name of the project. This name is identical to the name that was used when the
project was created. The project name is restricted to 64 characters. It can contain any
characters other than the semi-colon (;) or single quote ('). Since the project name is a
unique identifier, CitectSCADA will not permit you to create or restore a project with the
same name. Maximum length is 64 characters.
(General) Status
The status of the project. This can be either COMPILED or UNCOMPILED.
(General) Location
The directory path where the project files are stored. This field cannot be edited.
(General) Description
A description of the project. This field is useful for giving an explanation of the role of
the project. You are urged to complete this field. Maximum length is 255 characters.
(General) Major revision
CitectSCADA sets this property to one (1) when the project is first created. You can use
this field to track major changes to the project. You can use an incremental revision his-
tory (for example 1, 2, 3, . . . or A, B, C, . . .). Maximum length is 4 characters.
(General) Minor revision
CitectSCADA sets this property to zero (0) when the project is first created. You can use
this field in conjunction with the Major Revision to track your project's development.
Maximum length is 4 characters.
(General) Date and Time
CitectSCADA will initially set these fields to the date and times at when the project was
created. These fields are useful when used in conjunction with the Revision fields. Max-
imum length is 20 characters each.
(General) Project ID
A unique number for the project. The project number can be between 1 and 1022.
If you enter an ID that has already been used for another project, CitectSCADAwill detect
this when it compiles the project if the projects are part of the same include structure.
The project number is part of the unique identifier (object ID (OID)) used by OPC drivers
when reading from and writing to tags.
If you do not specify a project number, CitectSCADA will automatically generate one the
next time you select this project in the Citect Explorer, or the next time you compile. Max-
imum length is 4 characters.

Note: If you enter 0, your project ID is automatically set after closing the project's

147
Chapter: 9 Administering Projects

"Properties" page.

(General) Read-only
Specifies that no changes can be made to the project. If an attempt is made to modify the
project with this option selected, a message will prompt the user to disable the option
before continuing.

Note: If you change any properties, you need to click OK to save the changes to the
project.

Project Page Properties

(Page Defaults) [Template] Resolution
The default screen resolution of the standard graphics pages (such as alarms pages and
standard trend pages):

Screen Type Screen Width (pixels) Screen Height (pixels)

VGA 640 480

SVGA 800 600

XGA 1024 768

SXGA 1280 1024

User **** ****

Note: You can override this default for your own pages at the time when you create
them or any time afterward.

(Page Defaults) [Template] Style

The style (appearance) of the graphics pages in the runtime system. The style you select
is the default style for any new pages you add to the project. You can change the style of
existing pages and templates using the Page Properties, accessed through the Graphics
Builder.
Most users prefer the Standard style. You can view the pre-defined styles by looking in
the Include project under Graphics | Templates.

148
 Chapter: 9 Administering Projects

Note: You can override this default for your own pages at the time when you create
them, or any time afterward.

(Page Defaults) [Template] Show title bar

Determines whether the Windows title bar displays (at the top of each graphics page).
The title bar contains the title of the window, maximize, minimize and close buttons (at
the right hand end of the title bar), and the control menu button (at the left hand end of
the title bar).
To display a page in full screen (without a title bar), the size of the page needs to be the
same size as the display (or larger). If the page is smaller than the display, the title bar
still displays, even if full screen mode is enabled. Standard templates styles are available
for both page sizes.

Note: You can override this default for your own pages at the time when you create
them, or any time afterward.

(Page Defaults) Background color

The color that will display in the background of new graphics pages.

Copying projects
You can copy the contents of one project into an existing or a new project.
To copy a project:

1. Open Citect Explorer.

2. Select the Copy icon, or select Copy Project To from the File menu.
3. In the Copy Project dialog box, select the source project from the drop-down list
under Project name.
4. Select an existing destination project to copy to or select a new project.
5. Click OK to copy the project, or click Cancel.
See Also
Copy Project dialog

Copy Project dialog

This dialog box lets you copy the contents from one project into another. To copy a
project, specify the source [From] and destination [To] projects, then click OK.
[From] Project name

149
Chapter: 9 Administering Projects

The name of the source project being copied. If more than one project exists, you can
choose a project name from the drop-down list.
[To] (Existing or New) project
You can copy to either an Existing or a New project name and location.
l Existing Project: The source project is written over (replaces) an existing project loca-
tion under an existing project name.
l New Project: The source project is copied to the new location under a new project
name. A new project needs to be given a new name not currently being used, and
which complies with the naming requirements as detailed below.
[To] Name
The name of the destination project being copied to.
When copying to an existing project, you need to choose a project name from the existing
project names drop-down list.
When copying to a new project, you need to create a new and unique name for the
project. The project name is restricted to 64 characters, and can contain any characters
other than the semi-colon (;) or single quote ('). Since the project name is a unique iden-
tifier, CitectSCADA will not permit you to create or copy to a project with an existing
same name.
After the new project is created, you can change the Name through the Project Properties.

When copying to an existing project location, you can choose to delete the existing con-
tents of the destination project, including subdirectories, before the source project is cop-
ied, by checking both the Clear location before copying, and the Clear subdirectories check
boxes. This removes many files that may be left behind to interfere with the copied
project. If you do not clear the project location before copying, only common files in the
destination project are overwritten.
[To] Clear location before copying
Specifies to delete the contents of the existing destination project before copying the
source project to the destination location. This removes many files that may be left
behind to interfere with the copied project.
[To] Clear subdirectories
Specifies to delete the contents of the sub directories of the existing destination project
before copying the source project to the destination location. This removes many files
that may be left behind to interfere with the copied project.
Location

150
 Chapter: 9 Administering Projects

The directory path where the destination project files are stored. As the Name field is
entered, the directory is automatically generated in the Location field. You might override
this by manually entering the location or clicking Browse.
Check that the project names and location are correct in the confirmation dialog box.
Click Yes to copy the project, or No to cancel.

Printing project details

You can print configuration elements (database records, pages, Cicode files, etc.) in the
current project. CitectSCADA prints to the Windows default printer.
To print project database details:

1. Open the Citect Project Editor

2. Select Print from the File menu.
3. Use the Print selection list to choose the elements you want to print.
4. Click OK to start printing, or Cancel to abort.
Before printing your database, print a small portion to test the results. You can change
the default font, font size, and page size by choosing Options from the Tools menu. For
other print options, refer to your Windows documentation.
See Also
Print (project details) dialog

Print (project details) dialog

This dialog box allows you to print the configuration elements (database records,
graphic pages, Cicode files, etc.) in the current project. Click OK to print the selection, or
Cancel to abort printing.
[Print selection]
Lists the elements in the project that can be printed. To select (or deselect) an element for
printing, click the check box; a checkmark indicates it will be printed.
Click Select All to select every item in the list, or Deselect All to clear your selections.
[Options] Graphics pages included in print selection
Specifies a particular page to print. Use the drop-down list to select a single page from
the project. Choose the <All pages> entry to print the pages in the project.
[Options] Group printouts by graphics page
Print the objects database information with the related page. If this option is not set, then
the objects database information is printed as continuous lists, with just a page reference.

151
Chapter: 9 Administering Projects

You can only print the contents of the current project. Included projects will not be
printed. You can specify the print font, font size, and page size in the Options for the
Project Editor (in the Tools menu).

Deleting a project
To delete an existing project:

1. Open Citect Explorer.

2. Select a project from the list.
3. From the File menu, select Delete Project.
4. A message box asks you if you want to proceed. Click Yes to delete the project, or
click No to cancel.
You cannot delete a project that is currently open or any installed project. You also can-
not delete the Include project that is supplied with CitectSCADA.

Note: You cannot recover a deleted project that hasn't been backed up.

See Also
Linking projects

Linking projects
CitectSCADA installations on different computers over the same network can share the
same project. After a project has been created on one computer, other computers on the
same network can link to the same project, but only if the project location is on a shared
or network drive. Once linked, the remote project is visible in the local Citect Explorer,
and can be edited and compiled over the network. Only one version of a project ever
exists, and this version has to be kept on the computer it was created upon.

Note: Linking to a project provides the developer with normal access and control to
the project, even though it might be on a remote machine over the network.

Note: It is possible to delete a linked project, even though it might be on a remote

machine over the network. unlink a project rather than delete it over the network.

Linked projects will not be included into the compile of any other project unless they
have specifically been Included into that project from within Project Editor.
For details, see Including projects.

152
 Chapter: 9 Administering Projects

UNINTENDED EQUIPMENT OPERATION

Restart the client process if the hardware alarm "Cicode library timestamp differs" is raised
after a page is opened.

Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

Note: A hardware alarm of "Cicode library timestamp differs" will be raised if the Cicode library used by a
page has a different timestamp from the one in memory. The timestamps will be different if the project has
been fully recompiled, the project has been incrementally recompiled after the page has been modified, or if
the project has been incrementally recompiled after any Cicode has been modified.

To link to a project:

1. Open the Citect Explorer.

2. Click the Add Link button, or select Add Project Link from the File menu.
3. Use the Select Project Directory dialog to choose a project location.
4. Click OK to link the project, or click Cancel.
If the new project has the same name as an existing one, you are prompted to change it
before proceeding. Edit the properties in the Project Properties dialog.
To remove a link to a project:

1. Open the Citect Explorer.

2. Select a project from the list.
3. Click the Remove Link button, or select Remove Project Link from the File menu.
4. You are prompted if you want to proceed. Click Yes to remove the link, or No to can-
cel.
See Also
Including projects, Improved Client Side Online Changes

Time Synchronization
Previous versions of CitectSCADA employed a message-based time Synchronization
server to verify clocks on computers running a CitectSCADA project maintained time
synchronization. To support CitectSCADA running under standard user rights with User
Access Control (UAC) switched on in Windows Vista, our existing Time Server func-
tionality needed to be replaced.

153
Chapter: 9 Administering Projects

Note: This has also made the Cicode function TimeSet obsolete, and any usage of it
is recommended to be removed from your existing code.

In order to maintain time synchronization CitectSCADAv7.20 now installs a Windows

service called TimeSyncService, which runs under the built-in LocalSystem account. The
purpose of this service is to maintain the time on the local computer against one or more
time sources. A time source is a computer on which the time service is running.
A Time synchronization utility is provided by CitectSCADA to assist you to configure
time synchronization, and control the service as part of your administration envi-
ronment. The dialog stores and reads settings in the TimeSyncConfig.xml file, which is
installed in the CitectSCADA Config directory by default. See New Locations for Con-
figuration and Project Files for information about configuration file locations. Using the
configuration utility, you can specify an alternative path to the config file, such as a net-
work share. This can be useful where you have multiple computers using the same con-
figuration data and to change any setting you only need to change it on one machine.
To display the Time Synchronization dialog, open Citect Explorer and from the Tools
menu select the Time Synchronization menu item.
See Also

Time Synchronization Dialog

Time Synchronization Dialog

The fields available on the Time synchronization dialog are described in the following
table.

Field Description

Current status Displays the status of the TimeSync Windows serv-

ice, as displayed in service properties under com-
puter management. You may click the Start Service
button if the service is stopped, or Stop Service
service if it is running. If the service is identified as
being disabled, the button is also disabled. To ena-
ble the service use the Windows administrative
tools as either automatic or manual startup.

Startup type Identifies if the service is started manually, or auto-

matically. If the service is disabled, use the Win-
dows administrative tools to enable the service as
either automatic or manual startup.

TCP/IP Port The network port the service will use to listen for
connections from clients.

154
 Chapter: 9 Administering Projects

Field Description

Last synchronization Displays the value of the LastSyncTime registry set-

ting. This is the Local time at which the last suc-
cessful Synchronization occurred.

Current local time Displays the current time on the local computer,
updating every 1 second.

Log information events Controls whether the service writes events of type
'Information' to the event log. The default is
unchecked so that only alerts (called "warnings" in
the software) and errors are recorded.

Keep this computer's time synchronized Select this check box to enable the computer to be
a time client. This allows you to enter the poll time
and list of time servers against which to syn-
chronize.

Synchronize every Enter a number in hours between 1 and 168 (inclu-

sive) to specify frequency that synchronization
needs to occur. The default value is 24.

Synchronise Now Click to synchronize immediately

Synchronize with first available Displays a list of computers, and the current time
on those computers if available. The display is
updated every 1 second

Add button Displays a dialog for you to enter the name of a

server to add.

Remove Select a computer from the list above, and click

"Remove" to remove it from the list

Note: When you add a time source to the list, the current time on that machine will be displayed, provided the
service is running on that remote machine and listening on the same port number. If "Not available" then the
service is not running, or is running and using a different port number, or that port number is being blocked
by a firewall. The column in the list box is provided as a diagnostics function to ensure that the machine
names entered can be synchronized against. The time displayed in this box is an approximate only.

See Also

Time Synchronization

Archiving projects
Once you have configured your system, back up (or archive) the project. This will avoid
the loss of any configuration data in the event your primary storage becomes inoperative
or inaccessible.

Note: When you are developing a project, adopt a regular backup strategy. Before

155
Chapter: 9 Administering Projects

performing a backup, verify that you have refreshed any linked tags in your project.

CitectSCADA lets you back up a project to a local drive (hard drive), network location, or
removable media (floppy drive, memory stick).
This section of the help includes information on the following archiving tasks:
l Backing up a project
l Backing up INI files
l Configuring a backup with password encryption
l Running a backup from the command line
l Restoring a project

Backing up a project
The CitectSCADA Backup program archives files using a standard compression routine,
producing PKZip® v2.04g compatible files. The default extension for CitectSCADA
backup files is .CTZ, though any extension (including .ZIP) can be used. This means you
can also use the PKZip utility to extract files from a compressed CitectSCADA backup.

Note: Files produced with this backup program cannot be restored by product ver-
sions earlier than 5.10.

To back up a project:

1. Open Citect Explorer.

2. Click the Backup button, or select Tools | Backup. The Backup Project dialog
box displays:
3. In the Name field, select the name of the project to back up.
4. In the Backup file field, enter the path to the backup file location, including the file
name. You can either type the path in directly or use the Browse button.
The backup file name defaults to <project>.CTZ. If the extension is omitted then .CTZ
is used.
When you back up a project to a floppy disk, the backup program will ask you if you
wish to delete the files on the floppy disk before starting the backup.
If the destination drive is configured as A: or B: and is detected as removable, you
will have the option to delete any existing files on the disk.
5. Under Options, select the necessary options from the following list:
l Use compression: You can use data compression when you are backing up a
project to save space.

156
 Chapter: 9 Administering Projects

l Save compiled: By default, CitectSCADA backs up the project in uncompiled

mode. If you select this option, CitectSCADA backs up both the compiled and
uncompiled projects, resulting in a larger backup file.
l Save sub-directories: If you select this option, CitectSCADA also backs up data in
any sub-directories within the project directory. The directory structure is main-
tained in the backup, and you can choose to restore the sub-directories when
restoring the project. For example, if you wish to back up your Process Analyst
Views, save them in a sub-directory of the project and select this option. When
you restore the project, you will have the option to also restore the Process Analyst
Views directory.
l Use encryption: As an added security measure, you can back up your project in
an encrypted format. If you select this option, CitectSCADA requests a password.
CitectSCADA writes the project to disk in a format that encodes the password
along with the protected project. The project can only be restored if the password
is entered.
l Save configuration files: Select this option to back up *.ini files from the Config
folder. This will also backup the TimeSyncConfig.xml file used to store the time
synchronization settings configured in the Time Synchronization utility.
6. Click OK.
See Also
Backing up INI files

Backing up INI files

By default, when you select the 'Save configuration files' option, *.ini files from the Con-
fig folder are backed up.
If you are using a custom INI file (for example 'abc.ini') and it is placed in the Config
folder, it also will be backed up. If you are using a custom INI file that is stored in a sub-
directory of the project select the 'Save sub-directories' option to back it up as well.

Note: You can define a non-default INI file for CitectSCADA by passing a parameter
through to the Project Explorer from the Project Explorer Properties dialog box on the
Shortcut tab. See Using an Alternative INI File for further information on how to do
this.

If you run the backup program from the command line, and you specify an INI file as a
parameter, the specified INI file will be backed up instead of Citect.ini.
See Also
Configuring a backup with password encryption

157
Chapter: 9 Administering Projects

Configuring a backup with password encryption

When you select the "Use Encryption" backup option, CitectSCADA writes the project to
disk in a format that encodes the password. The project can only be restored when the
password is entered.
To use encryption:

1. Select the "Use encryption" option on the Backup Project dialog box.
2. Click OK. The Backup/Restore-Encryption dialog displays:
3. In the Enter Password field, enter your password. Asterisks will display in place of
the characters.
4. In the Re-Enter Password field, re-enter your password. CitectSCADA checks that
you have typed the same password both times.
5. Click OK. The project will be backed up.
See Also
Running a backup from the command line

Running a backup from the command line

You can execute the CitectSCADA backup program from the command line to back up
and restore files other than CitectSCADA projects.
From version 5, the backup program is called CtBack32.exe. For older versions, it is
called CtBackup.exe. By default, it is installed in the CitectSCADA project 'Bin' folder.
The CitectSCADA Backup program archives files using a standard compression routine,
producing PKZip v2.04g compatible files. The default extension for CitectSCADA backup
files is .CTZ, though any extension (including .ZIP) can be used. This means you can
also use PKZip to extract files from a compressed CitectSCADA backup if you prefer.
When you execute a backup from the command line, if you specify an INI file as a
parameter, it will be backed up instead of the default citect.ini file.
The backup program reads the citect.ini file for any parameters set using the [BACKUP]
category. These settings (if any, and their defaults if not) are over-ridden by any values
passed as command line options.
The table below describes the backup command line options.

Option Description

- database name
d<name>

158
 Chapter: 9 Administering Projects

-m<ext> include extension

-x<ext> exclude extension

-e encrypt with password

-p<pass- encrypt/decrypt password

word>

-s[+/-] recurse subdirectories

-f<level> format level, 0 only format if necessary, 2 always format disk. [obsolete
since version 3.xx, 4.xx]

-u[+/-] save uncompiled, use -u- to save compiled

-g[+/-] show configure dialog

-c[+/-] compress files

-b<path> path to backup from

-r<path> path to restore to

-i<file- ini file name

name>

-f1 use old file format (truncates long filenames to 8.3)

-a run in auto mode

(Note: Every necessary input needs to be in command line or INI file.)

Examples
l To back up (in version 3) c:\data use the following command:

CTBACKUP -g- -bc:\data

l To restore the above data use (in version 5):

CTBACK32 -g -rc:\data

159
Chapter: 9 Administering Projects

l To backup a CitectSCADA database, for example, to backup demo use:

CTBACK32 -dDEMO -b -u- -c+ -d-

Ctbackup also uses the following parameters in the CITECT.INI file:

[BACKUP]
Database= ! database to backup or restore
BackupPath= ! file to backup to, for example c:\temp\example.ctz.

DrivePath= ! path to backup to or restore from.

FilePath= ! file path, used in not a database

BackupFile= ! file name on backup disk, default CTBACKUP.

Password= ! encryption password

Drive=0/1/2 ! 0=other, 1=A, 2=B
DiskSize=0/1 ! low density=0, high density=1
Encrypt=0/1 ! encrypt backup
FormatLevel= ! format level.

Configure=0/1 ! display configure dialog

Compress=0/1 ! compress backup
Overwrite=0/1 ! overwrite
SaveCompiled=0/1 ! save compiled
Recurse=0/1 ! recurse sub directories
DeleteAll=0/1 ! delete all before restore
SaveIniFiles=0/1! determines whether save ini files is checked
Operation=0/1 ! 0=backup, 1=restore
Include= ! include list
Exclude= ! exclude list, default DBK,_CI
CompiledFiles= ! compiled files, default RDB
FileFormat=0/1 ! 1= use old format (truncates long filenames to 8.3)

Restoring a project
You can restore backed up and archived projects using the Restore Project program. This
program allows you to overwrite any current project with a backed up version, or restore
a backed up project as a new project.

Note: Be careful when restoring files as every file in the destination and sub-direc-
tories will be deleted before restoring. If you accidentally set your restore path to the
root directory of the drive, the program will delete your entire disk drive.

160
 Chapter: 9 Administering Projects

CAUTION
HARD DISK DRIVE ERASURE

Do not set the Restore Project path to the root directory of your drive (usually c:\).

Failure to follow these instructions can result in equipment damage.

To restore a project:

1. Open Citect Explorer.

2. Click the Restore button

or select Tools | Restore. The Restore Project dialog box will display.
3. In the Backup file field, enter the name of the project to restore.
4. Under To, select `Current project', to overwrite a project with the backed up one, or
`New project' to restore a backed up project as a new one.
5. In the Name field, enter a name for the restored project.
6. In the Location field, enter the location of the project to restore, including the file
name. You can either type in the path directly, or use the Browse button.
7. Under Options, select `Configuration files' to restore backed up INI files, and the
TimeSyncConfig.xml file used to store the time synchronization settings configured in
the Time Synchronization utility.
8. If you backed up the sub-directories under the project, the directories will be listed
under `Select sub-directories to restore'. You can choose to restore every or no sub-
directories, or you can select specific sub-directories to restore.
9. Click OK.
See Also
Archiving projects

Including projects
With large systems, it might be more convenient to develop the application using a
series of smaller projects, instead of one large project. For example, you could use a sep-
arate project for each section of the plant, or for each main process. This way, you can
develop and test each of the smaller projects before including them in the main project.
CitectSCADA projects will not be included into the compile of any other project unless
they have specifically been included into that project from within the Citect Project
Editor.

161
Chapter: 9 Administering Projects

Note: If a project exists remotely on the same network as the local installation and it
is on a shared or network drive, it can be linked to the local Citect Explorer. This is
different to including a project. Linking makes a project visible in the local Citect
Explorer. Once linked, it can be selected as the current project for editing over the net-
work.

Any linked project (visible in Citect Explorer) can be included within a local project, and
is subsequently included in the compile of the local Project.
Be careful not to confuse include files with included projects:
l Include Files contain CitectSCADA commands and/or expressions and are used as
substitutions in a CitectSCADA command or expression property field.
l Included Projects are separate and (usually smaller) projects that can be included in
another CitectSCADA project so that they appear together as one project.
Each CitectSCADA system is supplied with a number of include projects. These projects
contains pre-defined database records.
Recommended implementation structures
There are many ways of implementing included projects. However, there are a few pre-
ferred rules for locating projects so that servers and clients function correctly on deploy-
ment. These are listed in the table below:

Deployment

Recommendation Development Computer Server / Display Client WebClient

Good c:\user\ProjectMain d:\run\ProjectMain (<-RunPath) \temp\citect\deployname\

ProjectMain

c:\user\ProjectInclude d:\run\ProjectInclude \temp\citect\deployname\

ProjectInclude

c:\user\Include d:\run\Include \temp\citect\deployname\

Include

OK* c:\user\Dev\ProjectMain d:\runA\ProjectMain (<-Run- \temp\citect\deployname\

Path) ProjectMain

c:\user\Dev\ProjectInclude d:\runA\ProjectInclude \temp\citect\deployname\

ProjectInclude

c:\user\Include c:\user\Include* \temp\citect\deployname\

Include

OK* c:\user\Dev\ProjectMain d:\run\ProjectMain (<-RunPath) \temp\citect\deployname\

ProjectMain

162
 Chapter: 9 Administering Projects

Deployment

Recommendation Development Computer Server / Display Client WebClient

c:\user\Includes\ProjectInclude c:\user\Includes\ProjectInclude* \temp\citect\deployname\

ProjectInclude

c:\user\Includes\Include c:\user\Includes\Include* \temp\citect\deployname\

Include

* For these implementations, the client/server machine needs to already have project con-
tents at the c:\user\Include location and the implementations won't work with the
RUN/COPY features.

Including a project in the current project

To include another project (in the current project):

1. Open the Citect Explorer.

2. Select a Project from the list.
3. Select the System icon and then Included Projects.
4. Complete the Included Projects dialog that is displayed.
5. Click Add to append a record you have created, or Replace if you have modified a
record.

Note: Do not define circular references. That is, if project A includes project B, do not
include project A in project B. This will exit without completing at compile time with
a "Cannot open file" error. Instead, create another project and include both A and B
into this.

See Also
Included Projects dialog
CitectSCADA's included projects

Included Projects dialog

This dialog box lets you include another project in the current project. With large sys-
tems, develop the application using a series of smaller projects instead of one large
project.
You can include up to 240 projects. (You have to set [CtEdit]DBFiles to 310 in order to
enable this limit.) Every record in each project are globally accessible (i.e., a record
defined in one project can be used in another).

163
Chapter: 9 Administering Projects

Note: Each system automatically has an include project, which contains predefined
database records and graphics libraries.

Project Name
The name of the project to include in this project (64 characters maximum).
Comment
Any useful comment (48 characters maximum).

Included projects
Each CitectSCADA installation is supplied with three predefined include projects,
designed to help you develop your project faster. They are:
l the Include project - a template project with trending and alarm pages.
l the CSV_Include project - a Windows XP-styled set of templates with common tool-
bars and advanced visualization tools.
l the CSV_Instant Trend project - created to support the CSV_Include project's instant
trending feature.
These projects contain pre-defined database records and graphics libraries that can be
used as the foundation for the content within your own project.

Note: Do not modify the include project for use as a runtime project. It will not com-
pile successfully, and be set aside for use as a template for new projects. Citect-
SCADA upgrades install a new version of the CSV_Include project, which will
overwrite any changes you make to the project when this happens.

The include projects are hidden from the project tree in Citect Explorer by default.
To show/hide a CitectSCADA Include project:

1. Open the Citect Explorer.

2. Select Show Include Project from the View menu.
See Also
Introducing CSV_Include

Working with the Project Editor

The Project Editor is the primary tool used to configure the variable addressing, com-
munications and system components of a project. This section looks at the components
incorporated into the Project Editor to support this process.

164
 Chapter: 9 Administering Projects

l Setting the Project Editor options

l Paste Tag dialog box
l Paste Function dialog box
l Find User Function dialog box
l Using Find and Replace in a project

Setting the Project Editor options

The Project Editor offers the option to change the way the project configuration envi-
ronment operates.
To set the Project Editor options:

1. Launch the Project Editor

2. Select Options from the Tools menu.
3. Make the necessary option adjustments.
4. Click OK.
See Also
Project Editor Options dialog

Project Editor Options dialog

This dialog box allows you to adjust the functionality of the Project Editor.
Show deleted
Enables the display of deleted records in the databases. When enabled, a check box at
the bottom of the database form indicates if a record is deleted.
Incremental compile
Enables the incremental compilation of the project.
Extended forms
Enables the display of extended database forms. You can also use the F2 key on the key-
board to display extended forms.
Inform record changed
Enables the "Record has been changed" message window to appear when you add (or
change) data in a database form and then try to close the form - before you add or
replace the record.

Note: If you disable this option, you will lose data if you change a database record

165
Chapter: 9 Administering Projects

and forget to add or replace the record.

Disable user functions search

When you use a combo box to select a function (for a command or expression field), a
list of built-in Cicode functions and user-written functions displays. If you disable user
functions, only the built-in functions are displayed in the list.
Confirm on project packing
Enables the "Packing databases may take a long time" message window to appear when
packing a database.
Auto open error form
Automatically displays the Compile Errors form if an error is detected when the project
is compiled.
Compile enquiry message
Enables the "Do you want to compile?" message window to appear when the project has
been modified and Run is selected from the File menu. Normally, CitectSCADA compiles
the project automatically (if the project has been modified) when Run is selected.
Compile successful message
Enables the "Compilation Successful" message window to appear when the project has
been compiled.
Prompt on tag not exist
Enables the "Variable tag not found. Do you wish to create this tag?" message window to
appear when a variable tag is specified that does not exist in the database. With the mes-
sage window enabled, you can create new variable tags as they are necessary.
Prepare for Web deployment
Automatically runs the Web Deployment Preparation tool every time you compile a
project. Please be aware that this dramatically increases the amount of time taken for
each compile, particularly for large projects.
Log deprecated warnings during compile
If you select this option, the compiler will generate an alert message to identify any dep-
recated elements it detects in a project, that is any functions, parameters, or Kernel com-
mands that are no longer supported.
By unchecking this option, the alert messages are still included in the displayed alert
count, but they are not added to the error log.
Info popup time

166
 Chapter: 9 Administering Projects

The delay (in seconds) from the beginning of a database search until a search infor-
mation window displays. The search information window displays the number of the
traced records and allows you to cancel the search. You can cancel the search by select-
ing the Cancel button in the information window.
Cicode Editor
The text editor that is used for editing Cicode function libraries and report format files.
You need to enter the name of the executable file in this field. The default editor is the
Cicode Editor (ctcicode.exe) supplied with CitectSCADA.
Report Editor
The editor that is used for editing Report Format Files. You need to enter the name of the
executable file in this field. The default editor is Write (write.exe). If you are using Rich
Text Format (RTF) reports, verify that your editor is RTF capable.
Print page size
The number of lines (1 to 66) printed on each page when printing database records.
Print font point
The font size used when printing database records.
Print font name
The name of the font used when printing database records.
Maximum list box items
The maximum number of records that are displayed in drop-down combo boxes.
Warn about unused tags during full compile
Enables the generation of alert entries for unused tags that are not used directly in a
project. The alert entries are included in the Project Editor's Compile Errors form when a
full compile is run. By default this option is not selected.

Note: For this option Alert entries are generated only for a full compile, not an incre-
mental compile.

Log "tag not defined" warnings during compile

If you select this option, the compiler will generate a `tag not defined' alert in the error
log for any tags detected that are not defined in the variable database.
As CitectSCADAv7.20 now allows you to include undefined tags on your graphic pages,
this alert may be redundant and impractical. By unchecking this option, the alerts are
still included in the displayed count, but they are not added to the error log.

167
Chapter: 9 Administering Projects

Paste Tag dialog box

If you need to insert a variable tag into a tag or expression field, you can use the Paste
Tag dialog box.
To insert a variable tag into a tag or expression field:

1. Select the location you wish to insert a tag in to such as an expression field in a form.
2. Select Paste Tag from the Edit menu to display the Insert Tag dialog box.
3. Select the tag name, and click OK or click Cancel.
The tag will be inserted in the tag or expression field at the location of the cursor.

Paste Function dialog box

If you need to insert a function into a tag or expression field, you can use the Insert Func-
tion dialog box.
To insert a function into a tag or expression field:
1. Select the location you wish to insert a function in to such as an expression field in a
form.
2. Select Paste Function from the Edit menu to display the Insert Function dialog box.
3. Select the function name, and click OK or click Cancel.
To insert the function with its arguments included, select the Insert arguments box.
The function is inserted in the current field at the location of the cursor.

Note: If the total length of the function and its parameters is greater than 254 char-
acters, it won't appear in this dialog box. Instead, the message "Text Too Big" is dis-
played.

Find User Function dialog box

If you need to locate a Cicode function in your Cicode source files, you can use the Find
User Function dialog box.
To locate a function within a Cicode source file:

1. Select Find User Function from the Edit menu.

2. Enter the function name (or part of the function name) and click OK or click Cancel.
A list of functions that match your search criteria will be displayed.

168
 Chapter: 9 Administering Projects

Note: If you leave the Find field empty and click OK, a full list of functions appear in
the list.

To edit the Cicode file that contains the function:

1. Select the function name from the list that appears when searching for the function
(see above) and click Edit or click Cancel.
The file containing the selected function will be opened in the Cicode Editor.

Using Find and Replace in a project

You can use the Find and Replace dialog to locate specified text in your projects. You
can perform global text replaces in your projects, as well as export search results.
This is explained in the following topics:
l The Find and Replace dialog
l Specifying search coverage
l Using the results list
l Removing results
l Exporting results
l Jumping to a result (Go To)
l Replacing results
l Find and Replace alert messages
There is also a topic on Troubleshooting Searches to help determine if a search has been
correctly configured when unexpected results are returned.

The Find and Replace dialog

You open the Find and Replace dialog box from either the:
l Project Editor: You can find and replace text strings in your projects and included
projects.
l Graphics Builder: You can find and replace text within a single graphics page, tem-
plate, or Genie (including fields of the Metadata and Associations tabs [except the "In
Use" field]).
You can configure your search coverage, view your results, replace results, or open a
search result for more information.
To display the Find and Replace dialog box:

169
Chapter: 9 Administering Projects

l From the Project Editor or Graphics Builder, click Edit | Find or Edit | Replace. The
dialog box appears with either the Find tab or Replace tab selected, depending on
which command you selected.
To search text:

1. On the Edit menu in the Project Editor or Graphics Builder, click Find.
2. In the Find box, type the text string you want to search for. The search is not case-sen-
sitive, so it doesn't matter whether you enter lower- or uppercase letters.
You can enter an entire string or a portion of the string you want to find. For exam-
ple, typing BIT will return any string containing BIT, such as BIT_1, BITE, HABIT,
HABITS, and so on. You cannot enter wildcard characters, but you can include spe-
cial characters, as well as spaces if you want.
3. Specify your search coverage using the Look in and Search options lists.
4. Click Find. Search results appear in the results list when the search completes. The
status text under the results list indicates the progress of the search.

Note: When you start a search, the Find button changes to a Stop button you can
use to exit the search. If you stop a search, a partial list of the results is displayed.

To replace text:

1. On the Edit menu in the Project Editor or Graphics Builder, click Replace.
2. In the Find box, type the text you want to search for.
3. In the Replace with box, enter the replacement text.
4. Specify your search coverage.
5. Click Find.
6. View the search results.
7. Make your replacements using Replace or Replace All.

Specifying search coverage

You specify search coverage using the Look in and Search options lists to determine
which items in your projects you want to search for.
When you choose a Look in option, the Search options change. Each time you select a
Look in option, associated Search conditions are selected by default. The Look in
options work with the Search options as follows.
l Selecting Current Project or Current Project and Include Projects displays the
options described below.

170
 Chapter: 9 Administering Projects

l General: Searches configuration databases associated with a project as well as

included projects (if that option is selected).
l Graphics: Performs an "express search" for graphics pages only (the graphics
page does not have to be currently open). This search will not find text in symbols,
Genies, or templates if they have not been used on a page. If you don't find the text you
want, try the more comprehensive graphics search by opening a page, Genie, sym-
bol, or template and selecting Current Graphic as the Look in option (see below).
l Code Files: Searches Cicode/CitectVBA files in the current project (and included
projects, if that option is selected).
l Reports: Searches report files within the project folder and included projects (if
that option is selected).
l Selecting Current Graphic makes available the options described below. (This search
is a more extensive search than that performed by the Current Project:Graphics
search described above, and will search graphics documents that are currently open.)
l Inside Genies and Symbols includes graphics objects contained within a Genie
or symbol.
l Inside Templates includes objects contained within a page template.
l Selecting Current Form: Searches the current form.

Using the results list

As matches are found they are listed the results list. The results list shows an overview
of items that match the string entered in the search.
The results list can display a maximum of 200 results per page, sorted by project and
then item (you cannot change the sort order). The results list contains the following col-
umns:

Column Description

Project The name of the project in which the found text occurs.

Item Depends on the type of document in which the item occurs. If the document type is a:

Database - User-friendly name of the database.

Page - Name of the page.

Cicode/VBA - Name and path of the Cicode/VBA file.

Report - Name of the report.

Field Identifies that portion of the document/database in which the found item occurs in. For
example, if the found item appears in a database, this refers to the column name in the
database. Be aware that the search covers both expression/command as well as

171
Chapter: 9 Administering Projects

Column Description

numeric properties.

Location Shows the specific record number, AN, or line number on which the found item occurs
within the document/database.

Context An example of the context in which the found item occurs within the project. For exam-
ple, if the document type is a:

Database - a search result of BIT* might have a context of BIT_!.

Page - BIT* might have a context of Toggle(BIT_!)

Cicode/VBA - UserName might have a context of FUNCTION GetUserName()

Report - PUMP* might have a context of @(Pump A)

If the number of results returned exceeds 200 items, use the First, Previous, Next, and
Last buttons to navigate your results in groups of 200 results.
You can toggle between the Find and Replace functionality without losing the search
results, but if you close the Results page, your search results are lost.

Note: You can resize list columns by moving your mouse cursor onto the separator
between the list columns. When the mouse cursor changes shape to a black bar with
arrows, drag the column to the new size. You can also double-click the vertical bar
between fields to resize that field to fit the widest item.

Removing results
You can remove a search result from the Results window. Results that are removed are
not included in exports or in replacement operations. Removing a result does not delete
it, but merely removes it from the Results window.
To remove a result:

l With the result you want to remove highlighted, click Remove. The result is removed
from the Results window.

Exporting results
You can export search results in a tab-delimited format to a specified location. Results
are exported in the format

172
 Chapter: 9 Administering Projects

<Project> <Item> <Field> <Location> <Context>

If the Results window contains more than 200 results, every result is exported, not just
the ones currently displayed. If you remove an item from the results list, it will not be
exported. (For details on removing results, see Removing results.)
If you export an item that has a context, the context string is stripped of tabs and new
line characters.
Results exported are in Unicode format. Because of this, two leading characters and two
trailing characters are added to the file, but in most cases will remain hidden. When
exporting results, use Excel 2000 and later, which support the Unicode format.
To export results:

1. With the search results you want to export listed in the Results window, click Export.
2. Specify the location in the dialog box and then click Save. If the file already exists,
you're given the option to overwrite the file. Status text under the results list indicates
the progress of the export.

Note: If you want to stop the export, click Stop. You cannot perform a partial
export, so clicking Stop cancels the export entirely.

Jumping to a result (Go To)

You can jump to an individual result to see where the result occurs. Depending on the
type of document that contains the search result, the following occurs:
l Database: The form opens in the Project Editor and the text string is highlighted.
l Cicode/VBA: The document opens within the Cicode Editor and the text string is
highlighted.
l Graphic: The page opens in the Graphics Builder and the Properties dialog box
appears for the object that contains the text string. The property containing the text
string is displayed. If the string occurs on or inside a Genie, the Genie form also
appears.
l Report: The configured report editor opens and displays the report file, but the text
string is not highlighted.
To jump to a result:

l With the search result you want to jump to highlighted in the Results window, click
Go To. The document or form containing the occurrence opens.

173
Chapter: 9 Administering Projects

See Also
Replacing results

Replacing results
You can replace single results or multiple results with the replacement text string you
specified. You can also test a single result before replacing it. Depending on the type of
document that contains the search result, the following occurs when a replacement is
made:
l Database: The result is replaced with the replacement text and the database record
updated. The form containing the search result is not opened; to see the location of
the search result before or after the replacement is made, use the Go To command.
l Cicode/VBA: The Cicode file containing the matched text loads (if it is not loaded
already), the replacement is made, and the file saved.
l Graphic: The page opens in the Graphics Builder (if it is not already) and the replace-
ment made. If the page is open and contains unsaved changes, you're instructed to
save or discard the changes before making the replacement. If there are multiple
changes to be made to the same graphics page, the page remains open until every
change has been made.
l Report: The found text is replaced with the replacement text and the file is saved.

Note: Replacements cannot be undone once performed. take care to check your
replacements before making them, especially when working with multiple replace-
ments.

To test a result:

1. With the result you want to test highlighted, click Test. A dialog box appears show-
ing the result of the text replace.
2. Click Accept to accept the text replacement, or click Cancel.
To replace a single result:

l With the result you want to replace highlighted, click Replace. The replacement is
made and the result removed from the Results window. The next result in the list is
then selected.
To replace multiple results:

1. With the search results you want to replace listed in the Results window, click
Replace All. A confirmation dialog appears.

174
 Chapter: 9 Administering Projects

2. The replacements are made and removed from the Results window. (Replacements
that are not made remain in the results list. This will occur if, for example, you try to
replace a property that is read-only.)

Note: Clicking Stop during this process does not undo any replacements already
made.

When attempting to make a replacement, you might encounter an alert message that
alerts you of project-related issues be aware of before making a replacement. For details,
see Find and Replace alert messages.

Find and Replace alert messages

Find and Replace will display one of the following errors if it cannot replace a text
string:
l File in use
l Replaced text truncated
l Original text not found
l Replaced text out of range
l Replacement text not numeric
l Field is read-only
l Undetermined error

File in use
This alert message appears if the database or file that is necessary for writing to has
become unavailable. This may be the case if the database/file is being used by a third-
party application.
Do one of the following:
l Click Try Again (Default) to repeat the operation on the database/file.
l Click Ignore to skip the operation on this file.
l Click Ignore All button to skip any operations on files that are currently in use; this
option causes this message not to reappear.

175
Chapter: 9 Administering Projects

Replaced text truncated

This alert message appears if performing the text replacement in a DBF field exceeds the
field width limits. For example, if an Engineering Units field containing % is replaced
with "%LONGTEXTSTRING", a "replaced text truncated" alert message appears because
this field has a max width of 8. The replacement text would therefore be "%LONGTEX".
This alert message does not occur if searching the current graphics page.
Do one of the following:
l Click Yes to commit the truncated text to the database. Usually this will generate a
compilation alert message when the project is compiled.
l Click Yes to All to commit every change to fields regardless if truncation exists with-
out displaying the alert again.
l Click No (default) to leave the text as is.
l Click No to All button to leave truncated fields as is.

Original text not found

This alert message appears when attempting to replace an item on the current graphics
page when the animation could not be found or the text could not be found. This would
occur if the animation was deleted, or if the text found in an animation's field was
changed after the find but before replacing the item.
In the example below, the Fill Level Maximum contained a value of 23, and the search
text was 23. Before replacing the record, it was changed to 66.
Do one of the following:
l Click Ignore to skip this operation, leave the entry in the list, and move on to the
next replacement if it exists.
l Clicking Ignore All acts like the Ignore button, except that it skips any not found
errors that occur during this replacement.
l Click Stop to stop the replacement at the current record.

Replaced text out of range

This alert message appears when carrying out a replacement on the current graphics
page in two different circumstances:
1. The field is text and is too long for the allowable field width.
2. The field is a numeric field, and would be out of the allowable range for a replace-
ment value.

176
 Chapter: 9 Administering Projects

In the example below, the Fill Level Maximum allows a range or 0-100, and the value
was 23 and is being replaced with 101, which would be out of range.
Do one of the following:
l Click Ignore to skip this operation, leave the entry in the list, and move on to the
next replacement if one exists.
l Clicking Ignore All acts like the Ignore button, except that it skips out-of-range errors
that occur during this replacement.
l Click Stop to stop the replacement at the current record.

Replacement text not numeric

This alert message will appear when carrying out a replacement on the current graphics
page when the field being replaced is a numeric field, and the replacement text contains
a non-numeric value.
In the example below, the Fill Level Maximum contained a value of `23', and the replace-
ment text was `fred'.
Do one of the following:
l Click Ignore to skip this operation, leave the entry in the list, and move on to the
next replacement if it exists.
l Clicking Ignore All acts like the Ignore button, except that it skips any non-numeric
errors that occur during this replacement.
l Click Stop to stop the replacement at the current record.

Field is read-only
This alert message appears when replacing an item on the current graphics page when
the field being replaced is part of a linked object like a Genie or template.
In the example below, the Expression field was part of an object that was part of a genie.

Do one of the following:

l Click Ignore to skip this operation, leave the entry in the list, and move on to the
next replacement if it exists.
l Clicking Ignore All acts like the Ignore button, except that it skips any read-only
errors that occur during this replacement.
l Click Stop to stop the replacement at the current record.

177
Chapter: 9 Administering Projects

Undetermined error
This alert message appears when carrying out a replacement on the current graphics
page when a general error is detected, and not happen in normal operation.
Do one of the following:
l Click Ignore to skip this operation, leave the entry in the list, and move on to the
next replacement if it exists.
l Clicking Ignore All acts like the Ignore button, except that it skips any undetermined
errors that occur during this replacement.
l Click Stop to stop the replacement at the current record.

Troubleshooting Searches
If you don't find a result that you expected to find, check the following points, and then
perform your search again:
l Did you spell the text string correctly?
l Did you include the correct number of spaces?
l Are you using the appropriate Look in option?
l Are you using the appropriate Search options?
l Are you searching in the correct project?
l Are you using the correct graphics search?
l If you are using the graphics page search, do you have the correct graphics page
open?

178
Chapter: 10 Securing Projects
CitectSCADA projects represent a considerable investment. Once a commissioned project
has been delivered, it usually needs to remain in the delivered state until modifications
are performed by an authorized person. In order to help protect projects from mod-
ification by unauthorized personnel, CitectSCADA allows projects to be secured by an
administrator as "read-only."
For large applications, or applications where access to certain processes or machinery
needs to be restricted, you can build security into your system. You can then restrict
access to commands that you do not want to be available to evry one of your operators;
for example, commands that operate specialized machinery, acknowledge critical
alarms, or print sensitive reports. There are 2 options available to you to configure secu-
rity for your system.
These options are to use CitectSCADA native security or CitectSCADA integrated with
Windows Security .
This section describes the following:
l Characteristics of read-write and read-only projects (see Overview).
l Scenarios that describe Securing a Top-level Project and Securing an Include Project.
l How to secure projects as read-only (see Making a Project Read-Only).
l The consequences of securing projects (see Read-Only Privileges on Projects).
l Using CitectSCADA native security.
l Using CitectSCADA integrated with Windows security

Overview
CitectSCADA has two types of project:
l Read-write: allows write and delete privileges to the project folder (or for any project
file) for the current user.
l Read-only: projects that deny write and delete privileges to the project folder for the
current user.
The table below shows the different characteristics of read-only and read-write projects:

179
Chapter: 10 Securing Projects

Task Read-only Read-write

View existing files in project x x

Create new files in project x

Delete existing files in project x

Modify existing files in project x

Delete project x

Rename project directly x

Read-only projects cannot be compiled as top-level projects (i.e., projects that are the
main (root) project as opposed to an included project) and online changes are not sup-
ported.

Note: If the project folder is read-only for the current user, but one or more files in the
project have read-write access for the current user, the project is considered to be a
hybrid read-only/read-write project. CitectSCADA does not support this type of
project. Running a hybrid project may result in your system becoming unresponsive.
(This note does not include those folders or files that require read-write access in
order to operate at runtime; see Using CitectSCADA with Windows Security for
details.)

The security model used in enabling read-only projects does not replace the existing
CitectSCADA user accounts; instead, it works in conjunction with user accounts like this:

l CitectSCADA user accounts govern runtime security to project elements.

l Windows user accounts govern the security of configuration project elements.

Securing a Top-level Project

This section describes a "real-world" situation that might require read-only privileges to
be applied to a top-level project.

Note: Before securing a top-level project, read the section Read-Only Privileges on
Projects for details on operational constraints. Pay particular attention to the section
Read-only on top-level projects.

In this scenario, several onsite engineers are responsible for maintaining a top-level
project, ProjectXYZ. Consequently they require read-write privileges for every project
folder.

180
 Chapter: 10 Securing Projects

The operators responsible for monitoring plant operations will use the project at runtime
only; consequently operators only have read-only access to the project.
The system administrator on site first identifies those employees who will use the
project, and then divides this pool of users into two user groups:
l Project Engineers - responsible for project configuration.
l Operators - responsible for the project's runtime operations.
This is shown in the illustration below.

The administrator creates two user groups to make administering users easier: Pro-
jectXYZEngineers and ProjectXYZOperators, and assigns engineers to the first group,
operators to the second.

Note: Creating user groups is optional and makes it easier to handle privileges for
multiple users. Creating user groups may be unnecessary if you only have a few
users.

The administrator then assigns engineers read-write privileges to the top-level project
folder, and operators read-only privileges, like this.
1. Select the project folder of the top-level project and display its properties.
2. Select the ProjectXYZEngineers user group and allow read-write privileges.
(Remember that in order to use read-write projects, read, write, and delete privileges
needs to be assigned.)

181
Chapter: 10 Securing Projects

3. Select the ProjectXYZOperators user group and deny write privileges. See the section
Making a Project Read-Only for the specific privileges assign.
4. Apply and save the changes.
5. Review the changes to verify that engineers and operators have the correct privileges
for their roles.
See Also
Securing an Include Project

Securing an Include Project

This section describes a "real-world" situation that might require read-only privileges to
be applied to an include project.

Note: Before securing an include project, read the section Read-Only Privileges on
Projects for details on operational constraints. Pay particular attention to the section
Read-only on include projects.

In this situation, an OEM has configured and delivered an include project that is part of
a larger (top-level) project. Because the OEM engineer is solely responsible for main-
taining the include (and only the include) project, the site administrator assigns the OEM
engineer read-write access to the include project, but read-only access to the top-level
project. Conversely, the site's regular engineers can access the top-level project but not
the include project.
This scenario is shown here:

To set up this scenario the administrator does the following:

1. For ease of administration, assigns the site engineers to the user group AcmeT-
opEngineers.

182
 Chapter: 10 Securing Projects

Note: Because there is only one OEM engineer, the administrator did not create a
user group for this single user.

2. Selects the project folder of the top-level project and displays its properties.
3. Selects the AcmeTopEngineers user group and allows read-write privileges for this
folder. (Remember that in order to use read-write projects, read, write, and delete priv-
ileges needs to be assigned.)
4. Applies and saves the changes.
5. Selects the include project.
6. Selects the user name of the OEM engineer and allows read-write privileges for this
folder.
7. Applies and saves the changes.
8. Reviews the changes made to verify the correct privileges have been assigned. In par-
ticular, the administrator has to confirm that the privileges assigned to the AcmeT-
opEngineers user group deny read-write access to the include project.
See Also
Securing a Top-level Project

Making a Project Read-Only

This section describes how to make a project folder read-only by modifying the file secu-
rity settings for selected users and/or user groups. The read-only project configuration is
identical whether you are using Windows 2003 Server, Windows XP, or Windows 2000.
Notes
l This procedure assumes that you have already configured your users and user
groups (optional), and added them to the User groups for the project folder list for the
project you want to secure. For details on creating users and user groups, refer to your
Windows documentation.
l Before making your project read-only, verify that read, write, delete, and execute priv-
ileges have been applied appropriately to allow the CitectSCADA configuration and
runtime environments to operate correctly. For details, see Using CitectSCADA with
Windows Security.
l If you are using Windows XP or Windows 2000 and your file system is FAT32, you
need to convert the file system to NTFS in order to be able to specify the correct user
privileges on that workstation. For details, refer to your Windows documentation.
l To avoid unexpected results, read Read-Only Privileges on Projects before making
your project read-only.

183
Chapter: 10 Securing Projects

To make a project read-only:

1. In Windows Explorer, select the project folder you want to make read-only. By default
project folders are located in the folder
C:\ProgramData\Citect\CitectSCADA 7.10

2. Right-click the folder and choose Properties from the context menu. The Properties
dialog appears.
3. Select the Security tab.
4. Select the user and/or user group you want to modify security settings for.
5. Click Advanced. The Advanced Security Settings dialog appears for the selected
user/user group for the project folder.
Verify that the user or user group you want to modify permissions settings for is
selected.
6. Click Edit to display the Permission Entry dialog box.
7. Click Clear All to clear the current selections and then select the Allow check box for
the following options:
l Traverse Folder/Execute File
l List Folder/Read Data
l Read Attributes
l Read Extended Attributes
l Read Permissions
8. Click OK.
9. Click Apply to apply the permissions to the selected user/user group, and then click
OK to dismiss the Advanced Security Settings dialog.
10. Click OK to close the Properties dialog box.
The project folder has now been specified as read-only for the selected user(s) and/or
user group(s).
See Also
Securing a Top-level Project
Securing an Include Project

Read-Only Privileges on Projects

This section describes the operational constraints of making a project read-only. This sec-
tion also describes issues specific to securing top-level and include projects.

Note: Before Making a Project Read-Only, make sure you're familiar with the issues

184
 Chapter: 10 Securing Projects

described here. Also make sure that the correct privileges have been set in order for
the configuration and runtime environments to operate; for details, see Using Citect-
SCADA with Windows Security.

l Startup
l General
l Graphics and pages
l Backup and restore
l Project upgrades
l Debugging
l Web deployment
l Runtime issues
Most of the issues discussed above are common to both top-level projects and include
projects. The sections listed below discuss issues specific to these types of projects:
l Read-only on top-level projects
l Read-only on include projects

Startup
A project is determined to be read-only when Citect Explorer starts up. If the security per-
missions on the project folder are modified after Citect Explorer has started, the Citect-
SCADA configuration applications may not be able to determine accurately that the
project is read-only.
See Also
Using CitectSCADA with Windows Security

General
When a read-only project is opened using the Graphics Builder, Project Editor, or Citect
Explorer. the title bar shows the name of the project and a Read-Only message to indi-
cate the project is read-only.
Opening the Express Wizard for a read-only project displays a message on the first page
indicating the project is read-only:
In addition, any menu commands, toolbar buttons, and other operations that perform a
write function are grayed out and/or unavailable. For example, the Copy command is
available in the Project Editor for a read-only project, but the Cut and Paste commands
are not.

185
Chapter: 10 Securing Projects

When using the Process Analyst, you cannot create views to a project folder that is read-
only and an alert message is displayed.

Graphics and pages

You cannot update graphics documents or pages in read-only projects. (You can, how-
ever, update pages in a read-write project if that top-level project includes one or more
read-only projects.)
Opening an updated graphics page in a read-only project in Graphics Builder will
attempt to show the upgraded symbol, but only at the presentation (not disk) level.

Note: Updating graphics documents and/or pages in mid-level include projects is

not recommended because it will not update pages in the top-level project. However,
issuing an update pages at the top level iterates through included projects recur-
sively. (If these need to be updated, make the relevant projects read-write first).

Backup and restore

Read-only projects can be backed up by any user, regardless of their privileges. However,
the backup functionality does not archive the current security permissions. Con-
sequently, if the project is restored on another machine, the security settings need to be
reapplied.
Projects cannot be restored into an existing read-only project; attempting to do so will dis-
play an alert message advising that the project is read-only and cannot be restored.

Project upgrades
A project upgrade occurs when any of the following occurs:
l [CtEdit]Upgrade=1 is added to the citect.ini file.
l A project link is added via Citect Explorer.
l When a project is restored.
When CitectSCADA detects that the include, system, or CSV_Include project is read-only
and the version of CitectSCADA that the project was created under does not match the
current version of CitectSCADA, a message box is displayed to advise you of this.
In addition, when CitectSCADA detects that a user project is read-only and the version
of CitectSCADA that the project was created under does not match the current version of
CitectSCADA, a message box is displayed to advise you of this.
Any links to the project will be removed and the project tree in Citect Explorer will be
updated to indicate this.

186
 Chapter: 10 Securing Projects

If you plan to upgrade a top-level project, you need to log on as a user with the appro-
priate read-write security privileges for this project, add a link to the project in Citect
Explorer, and then perform the project upgrade again.

UNINTENDED EQUIPMENT OPERATION

• Do not leave non-upgraded projects in your project environment.

• If security privileges prevent a successful upgrade of projects related to your system,

restore the system to its prior state before resuming operations.

Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

Debugging
In read-only projects you can set breakpoints when debugging code, but these break-
points aren't saved when you exit the Cicode Editor.

Web deployment
You cannot perform Web deployment with read-only projects.

Runtime issues
By default most output operations during runtime occur in the [DATA] or [RUN] location
(see below for details). By default CitectSCADA configures the [RUN] location to the
project directory. If you intend on making the project directory read-only, you need to
modify the path(s) to a suitable read-write location.
l almsav.dat - Alarm data by default is saved in the [RUN] location, which is usually
the project folder. You need to change this location if you intend on making the
project folder read-only. Alternatively use the [Alarm]SavePrimary and [Alarm]Sav-
eSecondary options in the citect.ini file to control the location of the output.

l Disk PLCs - If a user does not have the correct privileges for the [RUN] path, com-
munications will be offline for disk PLCs. You need to change this location if intend-
ing to make the project folder read-only.
l User Cicode functions - Making a project read-only prevents the use of the following
user functions: UserCreate, UserDelete, UserEditForm, UsetrSetPassword, User-
SetPasswordForm. Attempting to use these functions results in an error code 262
(0x0106) ("Cannot open file").

187
Chapter: 10 Securing Projects

l Alarm Cicode functions - Making a project read-only prevents the use of the fol-
lowing alarm functions: AlarmSetDelay, AlarmSetDelayRec, AlarmSetThreshold, Alarm-
SetThresholdRec. Attempting to use these functions results in a hardware alarm 400
(0x0190) ("Project or file is read-only"). You also cannot modify alarm properties such
as threshold or delay.
Any files in your top-level project that require runtime read-write access have to be
located outside of the project folder.

Read-only on top-level projects

Before applying read-only to top-level projects, note the following:
l Before applying read-only to a top-level project, perform a full compile and then
apply the relevant security attributes. Once you apply read-only privilege, you cannot
compile a top-level project (see following bullet). For projects that needs to manip-
ulate files in the top-level project, you can modify the security of individual files to
read-write; the project will be regarded as read-only as long as the project folder is
denied write privileges.

Note: Any files in your top-level project that require runtime read-write access
have to be located outside of the project folder.

l Projects that are read-write that have read-only include projects as a component can
be compiled as usual.
l You can only run a read-only project if it is a top-level project.
l Applying read-only to top-level projects prevents online changes being made to
alarms, users, trends, and pages.
See Also
Making a Project Read-Only
Securing a Top-level Project

Read-only on include projects

Note the following before applying read-only to include projects:
l When compiling a top-level project with a read-only include project, the object IDs of
the included projects are skipped and not changed.
l Updating graphics documents and/or pages in mid-level include projects is not rec-
ommended because it will not update pages in the top-level project. However, issuing
an update pages at the top level iterates through included projects recursively. (If
these need to be updated, make the relevant projects read-write first).

188
 Chapter: 10 Securing Projects

See Also
Making a Project Read-Only
Securing an Include Project

Securing Runtime Computers

The CitectSCADA runtime system is a Windows-based application that runs in the
standard Windows environment. Typically, Windows allows you to run several appli-
cations at the same time, however, this may impact performance or obscure runtime mes-
sages and information if you require a computer to be dedicated to Runtime.
For example, an operator display panel may be used to present alarm notifications. You
don't want the Runtime screen minimized or hidden behind another window.
There are several different ways can limit access to software other than CitectSCADA.
See Also
Client Start up Restrictions
Running a client as a shell
Disabling Windows keyboard commands
Disabling control menu commands
Removing the Cancel button

Client Start up Restrictions

On start up CitectSCADA will establish initial communication with the server using a
view-only login. By default this communication between the client and the server is in
view-only mode. In this mode the user cannot write to any tag, acknowledge any alarm
or use Cicode functions.

Note: View-only mode is applied to the whole control client process, including any
Cicode task that is running.

Write only access is available after a user has successfully logged in. Once the user logs
out it returns to view-only mode.
Users can configure login by modifying the [Client]AutoLoginMode parameter.
See Also

Securing Runtime Computers

189
Chapter: 10 Securing Projects

Running a client as a shell

To limit certain operators from switching a client over to a different application during
runtime, you can configure Windows to launch with CitectSCADA running as the shell.
This will deploy CitectSCADA Runtime as the only available interface for a computer,
limiting access to within the context of the current project.
For information on how to set up a client as a shell, contact your local support office.
See Also
Disabling Windows keyboard commands

Disabling Windows keyboard commands

The Windows environment provides commands to switch between applications running
on the computer at the same time. When using CitectSCADA, these commands might
not be desirable - they allow an operator access to other Windows facilities without your
direct control. You might be able to disable some of these commands with the Computer
Setup Wizard. consult the Citect Knowledge Base for the latest information on disabling
Windows keyboard commands.
See Also
Disabling control menu commands

Disabling control menu commands

The Control Menu (in the top left corner of an application window) provides commands
to position and size the application window, and in some applications to control the
application. The runtime system's Control Menu can be tailored to give access to several
commands specific to CitectSCADA, such as Shutdown (to shut down the runtime sys-
tem), or Kernel (to display the Kernel).
You can enable and disable these commands with the Computer Setup Wizard.
See Also
Removing the Cancel button

Removing the Cancel button

When the CitectSCADA runtime system starts, a message box displays the status of the
system startup. This message box normally contains a Cancel button that allows you to
cancel the startup. This button is useful when you are debugging or testing the system.
When you have completed testing, you can remove the Cancel button from the message

190
 Chapter: 10 Securing Projects

box with the Computer Setup Wizard, so that there will not be an unintentional can-
cellation of system startup.

191
Chapter: 10 Securing Projects

192
Chapter: 11 Using CitectSCADA Security
To set up security in CitectSCADA you need to consider the following:
l Areas - An area is a section of the plant. It can be defined geographically or logically.
l Privileges - Level of access applied to system elements within your project. A user
assigned a role that possesses the matching privilege can control it.
l Roles - A defined set of permissions (privileges and areas) that are assigned to users.
l Users - A person or group of persons that need to access to the runtime system.
Before configuring security within your project you will need to have a thorough under-
standing of these four aspects, and how they work together.
See Also
Areas
Privileges
Roles
Users
Using CitectSCADA integrated with Windows Security

Areas
When implementing CitectSCADA for a large application, you can visualize the plant as
a series of discrete sections or areas. You can define areas geographically (especially
where parts of the plant are separated by vast distances or physical barriers) or logically
(as discrete processes or individual tasks).
Small plants, for example a simple manufacturing plant can be divided into just three
areas - raw product arrives in the receivables area, is transported to an area for proc-
essing, and is then transported to a packaging or despatch area.

193
Chapter: 11 Using CitectSCADA Security

However, with larger or more complex plants you might need to define several areas,
like this:

When defining an area, you would usually encompass a section of the plant that is con-
trolled by one operator (or controlled from one CitectSCADAControl Client).
You can also define smaller areas that are collectively controlled by an operator or Con-
trol Client. This method can increase flexibility, but can introduce a higher level of com-
plexity to your system.

194
 Chapter: 11 Using CitectSCADA Security

You can define up to 255 separate areas. You can then refer to these areas by number (1
to 255) or use a label to assign a meaningful name to the area (for example receivables,
pre-process, conveying, etc).
After you have defined your areas, you then configure the system elements (commands,
objects, alarms, reports, etc). your operators will use in those areas. For example:
For example:

Command CONVEYOR = 1;

Area 8

Comment This command belongs to Area 8

In this example, an operator without access to Area 8 will not be able to send the com-
mand. Refer to Roles for more information on how areas and roles work together.

Note: Any system element that is not assigned to an area between 1 and 255 is auto-
matically placed in a default area known as Area 0. Every user can view the system
elements in Area 0, but without the matching privilege will be unable to control
them.

See Also
Configuring Areas
Privileges
Roles
Users

Privileges
CitectSCADA provides eight privileges, numbered 1 to 8, that are used to restrict access
to parts of the project. To implement privileges into your project:
l Assign a privilege to a particular system element (command, object, report, alarm etc)
l Assign the privilege or privileges to the role or roles that will need to control that sys-
tem element.

Note: Global privileges apply to every area.

You can allocate different privileges to different types of operation, as in the following
example:

195
Chapter: 11 Using CitectSCADA Security

Privilege Command

1 Operate the conveyors

2 Operate the mixers

3 Operate the ovens

4 Acknowledge alarms

5 Print reports

6 Operate box machine

To allow a user to operate the conveyors, you assign privilege 1 to the role associated to
that user, for example:

Global Privilege 1

To allow a user to acknowledge alarms, you assign privilege 4 to the role associated to
that user, for example:

Global Privilege 4

To allow a user to acknowledge alarms and operate the conveyors, you assign both priv-
ilege 1 and privilege 4 to the role associated to that user record:

Global Privilege 1,4

Privilege classifications needs to be separated by commas (,).

To allow a user access to every command in your system, allocate every privilege in the
role associated to that user, for example

Global Privilege 1, 2, 3, 4, 5

Note: In assigning a role a global privilege, that role is granted view access to every area automatically. Any
user assigned that role will then be able to view every area of the plant.

After you have allocated privileges, you can define the privilege requirements of your
system elements (commands, reports, objects, alarms, etc.):

Com- CONVEYOR = 1;
mand

Privilege 1

Comment An Operator with Privilege classification 1 can operate the conveyor

196
 Chapter: 11 Using CitectSCADA Security

Com- Report("Shift");
mand

Privilege 5

Comment An Operator with Privilege classification 5 can print the report

Not every system element needs a privilege classification. At least one command needs
to be issued by users, a command to log in to the system:

Com- LoginForm();
mand

Priv-
ilege

Com- A blank Privilege (or Privilege 0) means that the command has no classification
ment - it is available to every user who performs this role.

See Also
Roles
Users

Roles
When creating a role, consider the tasks the users who are assigned this role will be
expected to perform within the project, and what system elements that user will need to
have access to, or be restricted from. Using the areas and privileges defined previously, a
number of example roles are outlined below.

Note: Area 0 is assigned by default to every role. This means users can view any sys-
tem element in Area 0.

Role Description Viewable Areas assigned Privileges

Receiver controller Needed to monitor the receiver area, 1,2,3 1,4,5

print out reports and track progress
of supplies. Also will need to control
system elements that have a priv-
ilege level of 1,4,5.

Operations Manager Needed to monitor the Processing area 1,2,3,4,5,6,7,8,9 2,3,4,5

of the plant. Needs to be also able to
control elements within processing. At
times will need to be able to check on
the Receivals area.

197
Chapter: 11 Using CitectSCADA Security

Role Description Viewable Areas assigned Privileges

Despatch Handler Needs to be able to organize the pack- 8,10,11,12 1,2,5,6

ing and distribution of final product.
Will need to track product production to
schedule dispatch tasks for packer.

Engineer Engineer is necessary to have access to 1,2,3,4,5,6,7,8,9,10,11,12 1,2,3,4,5,6

every area of the plant, and will be able
to operate any system element.

Conveyor Operator Needs to be able to operate the con- 8 1

veyor.

Mixer Operator Needs to have access to each type of 4,5,6,7 2

mixer operation. Will have access to
areas 4 to 7 and will be able to operate
any system element with a privilege of
2.

Packer Needed to be able to package goods 12 6

See Also
Users
Adding Roles

Users
A user can be a Windows or CitectSCADA user. Each user is assigned zero or more roles
depending on the activities and processes they will have to operate and monitor. If zero
roles are allocated to the user, this is the same as configuring the user with no privileges.

Name Role

John Smith Despatch Handler

Jack Smith Mixer operator

Tom Smith Engineer

Jerry Smith Conveyor Operator

Joan Smith Conveyor operator, Mixer operator

See Also
Configuring CitectSCADA Security
Adding Roles

198
 Chapter: 11 Using CitectSCADA Security

Configuring CitectSCADA Security

To configure CitectSCADA security, you need to do the following:
l Configuring Areas
l Adding Roles
l Configuring Privileges
l Adding Users

Configuring Areas
When configuring areas within a plant you have the option of labeling areas, grouping
areas and naming the group, and granting users view-only access to particular areas.
l Using labels to name areas
l Using groups of areas
l Viewing areas of the plant

Using labels to name areas

It might be easier to remember an area by a meaningful label (name) rather than a
number. For example:

Label Name DespatchAccum

Expression 10

Comment Label Area 10 as "DespatchAccum"

In this case, "DespatchAccum" could be used whenever area 10 is referred to, for exam-
ple:

Command CONVEYOR = 1;

Area DespatchAccum

Comment This command belongs to Area 10 (DespatchAccum)

Note: If you leave the Area field blank on a form, the command does not belong to

199
Chapter: 11 Using CitectSCADA Security

any particular area - it is assigned to every area of the plant.

To label an area:

1. Choose System | Labels.

2. Enter a Name for the label.
3. Enter an expression to be substituted for the label.
4. Click Add to append a new record, or Replace to modify an existing record.
See Also
Using groups of areas

Using groups of areas

You can group several areas and define a name for the group.

Group Name Despatch

Association 1 DespatchAccum

Association 2 11

Association 3 12

Comment Areas 10, 11, 12 = "Despatch"

In the above example, areas 10, 11, and 12 are associated with the name "Despatch".
Any command assigned to "Despatch" belongs to areas 10, 11, and 12.

Command CONVEYOR = 1;

Area Despatch

Comment This command belongs to Areas 10, 11 and 12

You can also define a group that includes other groups.

Group Name Plantwide

Association 1 Receivals

Association 2 Process

200
 Chapter: 11 Using CitectSCADA Security

Association 3 Despatch

Comment Associate every area with "Plantwide"

In this example, the name "Plantwide" refers to every area defined in the "Receivals",
"Process", and "Despatch" groups.
To define a group of areas:

1. Choose System | Groups. The Groups dialog box appears.

2. Complete the Groups dialog box.
3. Click Add to append a new record, or Replace to modify an existing record.
See Also
Groups properties

Groups properties
Use the Groups dialog box to configure properties of groups:
Group Name
The name of the group. You can use this facility, for example, to define multiple areas or
multiple devices. Enter a value of 16 characters or less.
After you have defined a group, it can be used anywhere that an individual entity can
be used. You can also specify complex groups by defining a group of groups.
Association 1 . . . Association 10
A list of the entities associated with the Group Name. Enter a value of 16 characters or
less. An Association can be a number, a name, or another group. You can also specify a
range of numbers in the format <n1..n2> for example:

Association 1 4..10

Specifies numbers 4,5,6,7,8,9,10.

You can also define a group of devices to be accessed with a single name, for example:

Group Name AlarmInfo

Association 1 AlarmPrint

Association 2 AlarmLog

Association 3 AlarmDBF

201
Chapter: 11 Using CitectSCADA Security

In this case, when the group name (AlarmInfo) is used as a device, the information is
sent to three devices - AlarmPrint, AlarmLog, and AlarmDBF.
Comment
Any useful comment. Enter a value of 48 characters or less.

Viewing areas of the plant

You might need to provide a user access to information from other areas of the plant
even though you do not want that user to control any of the processes within those
areas. For example, the user may need to monitor the processes in one area as they
might directly affect another area.
In the following example, John Smith has been assigned the role of Despatch Handler
and as such has been granted control of:
l System elements located in Despatch, with a privilege level of 1; and
l System elements located in DespatchAccum, with a privilege level of 4.
l View-only access Plantwide to track when product is due to arrive in Despatch for
packing and distribution.

User Name J Smith

Global Privilege

Viewable Areas Plantwide

Areas for Priv 1 Despatch

Areas for Priv 2

Areas for Priv 3

Areas for Priv 4 DespatchAccum

Areas for Priv 5

Areas for Priv 6

Areas for Priv 7

Areas for Priv 8

Comment Login for John

202
 Chapter: 11 Using CitectSCADA Security

Alternatively, you could restrict users access to a group of areas (for example, "Recei-
vals") or to a single area (for example, 12).

Adding Roles
Create a role for those people or groups of people you want to use your system. When
creating a role you determine what permissions (privileges and areas) to set for each
based on the tasks the user assigned that role needs to be able to perform within the
project and plant.
To add a Role record:

1. Choose System | Roles to display the Roles dialog box.

2. Complete the Roles dialog box.
3. Click Add to append a new record, or Replace to modify an existing record.
Use the Roles dialog box to define properties for your roles.
Role Name
Enter a value of 16 characters or less, for example "Operator". Role Names are restricted
to using the same syntax as Tag names. See Tag name syntax.
Windows Group Name (Users using Windows Authentication only)
Enter the name of the group that you intend link to the Windows security group. Verify
that this name is same as the group name in Windows which you want the role link to.
It can contain up to 254 uppercase or lowercase characters. Verify that only use the char-
acters that are allowed for Windows group account name in Windows.
The Windows group name can include a domain name or a local computer name in the
format of "domainname\operator", or "localcomputername\operator". If either are spec-
ified in the group name CitectSCADA runtime will only validate for the groups on the
server specified in the name or the local computer.
Comment
Any useful comment. Enter a value of 48 characters or less.
Global Privilege
The privilege assigned globally to the role. Enter a value of 16 characters or less.
In the privilege field you can separate numbers with commas or you can enter a range
separated by two periods le.g. 1..8

203
Chapter: 11 Using CitectSCADA Security

As you configure your system, you can assign privileges to the various elements, such
as graphics objects, alarms, accumulators, commands, and so on. For example, a role
with a Global Privilege of 3 will be able to issue any command that is assigned a priv-
ilege of 3, or action any alarm with a privilege of 3, or click any button that is assigned a
privilege of 3, etc. Unless you are using areas, if you do not specify a global privilege, the
role cannot access any command with a privilege assigned.

Note: (For users using windows authentication) When you have completed the fields
in this dialog and if you have not already done so, add the users to the group in Win-
dows security that you want to have the privileges of this role.

See Also
Adding groups and users in Windows security.
Additional fields on this dialog using extended forms (press F2).

Additional Fields
Viewable Areas
The areas the user assigned the associated role is permitted to view. Enter a value of 16
characters or less.

Note: Do not set Viewable Areas in conjunction with Global privileges, as global
privileges give roles view access to areas automatically.

Remember, you need to still assign privileges to the elements in these viewable areas,
such as graphics objects, alarms, accumulators, commands, etc. If you do not, the user
will have full access to them. For example, if you do not assign a privilege to a com-
mand in one of these areas, the user will be able to issue it regardless if you want them
to or not.
To make an element (such as a button on a expression) view only for a particular user,
assign it an expression and a privilege. Add the area to the user's list of Viewable Areas,
but don't give the user the necessary privileges in that area (or the necessary global priv-
ilege).
Multiple areas can be defined using groups.
If you do not specify “Viewable Areas”, the user will have viewable access to area 0. See
Privilege and Area combinations for more information.
Areas for Priv 1 . . . Priv 8

204
 Chapter: 11 Using CitectSCADA Security

The privileges (by area) assigned to the user. Enter a value of 16 characters or less. Using
this combination of areas and privileges, you can assign a user different privileges for
different areas. For example, users assigned a role with privilege class 6 in areas 29 and
30 will only have access to commands in those areas that require privilege class 6.
In the privilege field you can separate numbers with commas or you can enter a range
separated by two periods le.g. 1..8

Note: In assigning a privilege to an area, you are making that area viewable to users
assigned that role.

If you do not specify areas with associated privileges, access is defined by Viewable
Areas or Global Privileges only
Entry Command
A Cicode command that is executed when the user assigned this role logs in. You can
use any Cicode command or function. Enter a value of 254 characters or less.
Exit Command
A Cicode command that is executed when the user assigned this role logs out. You can
use any Cicode command or function. Enter a value of 254 characters or less.

Configuring Privileges
When configuring privileges you have the option of changing the default from non-hier-
archical to hierarchical. You may also need to assign privileges to a specific area or mul-
tiple areas and as such need to have an understanding of how certain combinations of
privileges and areas will affect the security of your project.
l Using hierarchical privilege
l Implementing system security
l Privilege and Area combinations
l Using multiple areas and privileges

Using hierarchical privilege

By default, privileges are non-hierarchical (i.e. users with privilege 3 only have access to
commands with classification 3).

205
Chapter: 11 Using CitectSCADA Security

When privileges are changed to hierarchical (using ini parameter [Privilege]Exclusive),

privilege 1 becomes the lowest and 8 is the highest privilege. This means users with
privilege 3 have access to commands with privilege classification 3, 2, and 1, whilst to
allocate every privilege, you only need to specify privilege 8.

Global Privilege 8

Implementing System Security

Each of your system elements (objects, alarms, reports, accumulators, etc.) can be
assigned a privilege level and allocated to a specific area. For a user to be able to
acknowledge an alarm, for example, the role they are assigned, need to have access to
the correct area, and have the necessary privileges that match the alarm.

Command CONVEYOR = 1;

Privilege 1

Area 8

Comment This command belongs to Area 8, and requires privilege 1

In this simple example, an operator without privilege 1 in Area 8 will not be able to
issue the command.
See Also
Viewing areas of the plant

Privilege and Area combinations

Outlined below are four general rules regarding the use of privileges and areas within
CitectSCADA.
1. Global privileges apply to every area.
2. Assigning a privilege to an area within a role, means any user assigned that role will
gain viewable access to that area automatically. However the user can only operate
system elements in that area that have a matching privilege. As a result of the first
rule, if users are assigned a global privilege they will also be able to view every area.
3. Area 0 includes every privilege a role may have been assigned in other areas. In
other words if granted a privilege 3 for use in another area that role can also control
those system elements in Area 0 that have a privilege set as 3.
4. All users can view Area 0.

206
 Chapter: 11 Using CitectSCADA Security

These rules will assist you in understanding how the various privilege and area com-
binations between system elements and roles will affect your security. The table below
outlines numerous scenarios, and the resulting security for a simple on/off button.The
first two columns Area and Privilege refer to the button.

Area Priv Role Area Priv Security

No No Con- No No Operator can view

veyor and control the sys-
Operator tem element.

No Yes Con- No No Can view the system

veyor element but cannot
Operator operate it as role does
not have the nec-
essary privilege

No Yes Con- No Yes Can view the system

veyor (matching) element and control it
Operator as role been granted
the matching global
privilege. Role will be
able to control those
system elements that
also have the match-
ing privilege in other
areas of the plant.

Yes No Con- No No Role cannot view the

veyor system element, as it
Operator is no longer assigned
to Area 0.

Yes No Con- Yes (match- No Role can view and con-

veyor ing) trol the system ele-
Operator ment, as no privilege
restriction has been
set.

Yes Yes Con- Yes (match- Yes (not Can view the system
veyor ing) matching) element in the rel-
Operator evant area but cannot
operate it as role does
not have the nec-
essary associated
privilege.

Can view the system

Con-
Yes (match- Yes element and control it
Yes Yes veyor
ing) (matching) within the relevant
Operator
area, as role has been

207
Chapter: 11 Using CitectSCADA Security

Area Priv Role Area Priv Security

assigned a matching
associated privilege.

See Also
Using multiple areas and privileges

Using multiple areas with privileges

By combining area and privilege restrictions, you can select what control an operator
has within a specific area. You can still assign privileges to each of your operators with-
out using areas - to allow them access to the entire plant (global privileges), but by com-
bining Areas and Privileges, you add an extra level of flexibility.

User Name J Smith

Global Privilege 1,2

Viewable Areas

Areas for Priv 1

Areas for Priv 2

Areas for Priv 3 Despatch

Areas for Priv 4 DespatchAccum

Areas for Priv 5 DespatchAccum, 11

Areas for Priv 6

Areas for Priv 7

Areas for Priv 8

Comment Login for John

In this first example, John Smith has been assigned the role of Despatch Handler. This
role has global privileges 1 and 2. Privilege 3 in the "Despatch" areas (10, 11, and 12),
privilege 4 in the "DespatchAccum" area (10) and privilege 5 in areas 10 and 11. This
means he can:

208
 Chapter: 11 Using CitectSCADA Security

l Due to rule 1 and 2, view evry area of the plant.

l Due to rule 1 control every system element in the plant with a value of 1 and 2.
l In area 10, control system elements with a privilege level 1, 2, 3, 4 or 5.
l In area 11, control system elements with privilege level 1, 2, 3 or 5.
Also, in this example, Groups and Labels have been used to make the security con-
figuration intuitive.
Example 2:

User Name J Smith

Global Privilege

Viewable Areas 7,8,9

Areas for Priv 1

Areas for Priv 2

Areas for Priv 3 Despatch

Areas for Priv 4 DespatchAccum

Areas for Priv 5 DespatchAccum, 11

Areas for Priv 6

Areas for Priv 7

Areas for Priv 8

Comment Login for John

In this second example John Smith has been assigned the role of Despatch Handler. This
role has no global privileges. Viewable areas, (7,8,9). Privilege 3 in the "Despatch" areas
(10, 11, and 12), privilege 4 in the "DespatchAccum" area (10) and privilege 5 in areas 10
and 11. This means he can:
l View areas 7,8,9,10,11,12
l In area 10, control system elements with a privilege level 3, 4 or 5.
l In area 11, control system elements with privilege level 3 or 5.
l In area 12, control system elements with privilege level 3.
l Due to rules 3 and 4, control system elements with privilege level 3,4,5 in Area 0

209
Chapter: 11 Using CitectSCADA Security

See Also
Adding Users

Adding users
For each person you want to have access to your project you need to add their user infor-
mation into the system.
To add a user:

1. Choose System | Users. The Users dialog box appears.

2. Complete the Users dialog box.
3. Click Add to append a new record, or Replace to modify an existing record.
Use the Users dialog box to define properties for your users.
User Name
The user's name. Enter a value of 16 characters or less. You can assign a user record for
a single user, for example:

User Name JackSmith

User Name JohnSmith

Each operator needs to enter the User Name and Password to use the system.
User Names are restricted to using the same syntax as Tag names. See Tag name syntax.

Full Name
The full name of the user or class of user. Enter a value of 32 characters or less. This
name is used as a comment and for display in alarm logs and command logs.
Password
The user's password. Enter a value of 36 characters or less. When you enter the pass-
word, an asterisk (*) will display for each character entered. When you save the user rec-
ord, the password will be encrypted before it is saved to the Users.dbf.
Each operator needs to enter the User Name and Password to use the system.
Use the [General]PasswordExpiry parameter to specify when the password will expire.
Confirm Password

210
 Chapter: 11 Using CitectSCADA Security

Re-enter the user's password to confirm the text entered in the Password field. Enter a
value of 36 characters or less. If the contents of the Password and Confirm Password
fields are different when the record is saved, a message will be displayed that indicates
a mismatch and invites you to try again.
Type
The generic type of user. Enter a value of 16 characters or less. For example:

Type Operator

Type Supervisor

Type Manager

The Type field is used in configuration only to specify a class of user that can then be
used as the basis for creating new users in runtime via the UserCreate() cicode function.
When this function is run it displays a form where you can select the user Type. When
you do this, your new user will inherit the properties of the chosen user class record that
you have already created. In doing this it uses the first user record with a matching Type
value.
In configuration, decide what user classes you need. Each class (or Type) would contain
any specific Global Privilege, Viewable Areas and Areas for Privilige and Entry and Exit
Commands values . Maintain just one user record for each class and then base other
individual users on this. If you create new users in configuration in the usual way by
using Add, Replace technique, then you will get multiple user records with the same
Type field value. Whilst this will not directly cause a problem for indiviual records it
could confuse development or provide scope for inconsistencies and unexpected behav-
iour if other field values are changed. When adding records in configuration, it is there-
fore recommended that you remove duplicate Type values from additional user records.
Roles
Each user is assigned roles. The Roles field will accept zero or more comma-separated
role names. If zero roles are specified for the user, this is the same as configuring the
user with no privileges.

Note: When a Windows or CitectSCADA user who is linked to multiple roles logs
onto runtime the privileges and areas that the user will be assigned are the com-
bined privileges of the linked roles.

Comment
Any useful comment. Enter a value of 48 characters or less.

211
Chapter: 11 Using CitectSCADA Security

Notes:To login a user, you need to use the Login() or LoginForm() Cicode functions.

User records and project restoration

For those users not using windows authenticated security if you restore a project from a
backup, or install a new project from a compiled offline master, the user records are reset
to match those originally configured in the project. If the runtime user creation, pass-
word change ability, or password expiry functions are used, the runtime details might be
thrown out of synchronization with master offline projects.
Here, you need to have procedures in place to use the current Users.dbf file (which is run-
ning live in the plant) when offline project compilations are performed. This minimizes
the likelihood of either deleting users created at runtime, or of having expired user rec-
ords locked when a new system is deployed and run up.

Note: Online changes arising from user creations and modifications are reflected
only in the local _Users.rdb and Users.dbf files. Perform user administration activities
on a central node so that user records remain synchronized across a distributed net-
work. Other nodes will use the Copy= functionality in CitectSCADA or custom engi-
neered database replication.

See Also
Adding users

Using CitectSCADA integrated with Windows Security

In CitectSCADA you have the ability to incorporate CitectSCADA users and security
options with the standard Windows security system. You can still use the existing Citect-
SCADA security if you prefer to define users in the project and logon to CitectSCADA
runtime.
Using the integrated Windows security feature, the Windows user can logon to Citect-
SCADA runtime with runtime privileges and areas configured within the project. For a
Windows user to be able to logon to runtime it needs to be linked to a CitectSCADA
"Role" which is defined in the project with associated privileges
In order to link a Windows user to a CitectSCADA role add the "Role" that specifies the
Windows group of which the Windows user is a member. The SCADA machines have
to be added/belong to the domain that has the Windows users.

212
 Chapter: 11 Using CitectSCADA Security

The pre-existing AutoLogin capability has also been extended to include the client, when
the user is a Windows user, having an associated Citect role. In order to invoke this func-
tionality for a Windows user you need to set the [Client]AutoLoginMode parameter in
the Citect.ini file.
A CitectSCADA user will always take priority over a Windows user when logging in at
runtime if the user is also included as a Windows user. However if a valid CitectSCADA
user login does not succeed for some reason, the Windows user credentials will not be
checked and an alert will be generated to advise that the login was not effective.
Conceptual diagram of CitectSCADA security and Windows security

Multi Signature support

When a Windows user is logged on to a runtime system with the associated privileges
and areas of the role to which the user belongs, there are times when a higher level
authorization is necessary for the user to perform certain actions. When this situation
occurs the MultiSignatureForm Cicode function can be displayed through Cicode to
allow authorization of an operation by another user who has the necessary level of priv-
ilege.
See Also
Adding Roles
Using Security

Adding Groups and Users

The Windows groups and users are defined by a Windows administrator or an author-
ized power user through the Windows administration function, as distinct from Citect-
SCADA administration.

213
Chapter: 11 Using CitectSCADA Security

Domain groups and users are defined or created on the domain server by the domain
administrator. Local groups and users are defined or created on the local computer by
the local administrator. To link a Windows user to a CitectSCADA role the user needs to
be a member of the Windows group and the name of the group has to be same as the
Windows group name specified in the CitectSCADA role.
For information on how to add groups and users to Window security, refer to the Win-
dows documentation appropriate to your operating system.
A Windows user need not be a CitectSCADA user. However if a Windows user is added
to the Windows group that is linked to a CitectSCADA role, then that Windows user will
have the privileges as are assigned to the role.
The Windows administrator can control which Windows user can or cannot login to run-
time by choosing whether to add the user to the linked Windows groups.
See also

Adding Roles

Scenarios and Usage

The following scenarios show how a user will be allowed to negotiate access to a Citect-
SCADA runtime system in various situations when using Windows groups and Citect-
SCADA roles.
Local User Login
When authenticating Windows users, if the Role|Group Name does not contain a
domain path, then any domain will be used to authenticate. Therefore, specify a domain.
Domain Login
When authenticating Windows users and the Role|Group Name contains a domain
name, windows will attempt to authenticate the Windows domain users and user
groups. If the domain controllers are unavailable, then cached credentials and Citect
group names will be used if available.

Note: Cached credentials are not supported on the Web Client.

Windows 2000 will only utilize cached credentials if the user is logged on with SE_
TCB_NAME privilege.

Local Client Authentication

214
 Chapter: 11 Using CitectSCADA Security

When a CitectSCADA Windows login is performed on a Control Client or View-only

Client that is part of a domain, the client itself is responsible for authenticating with the
domain. The CitectSCADA server only verifies the account exists – it does not perform
the authentication.
Remote Client Authentication
When a CitectSCADA Windows login is performed on a remote client that is part of a
domain, or a trusted domain, the client itself is responsible for authenticating with the
domain. The CitectSCADA server only verifies the account exists – it does not perform
the authentication. Essentially this mechanism is the same as a local client authen-
tication.
Web Client Authentication
When a CitectSCADA Windows login is performed on a web client that is not a member
of the configured domain, the server is responsible for authenticating the user on the
domain. No local Windows authentication occurs on the web client machine. No auto-
login can occur in this situation.
Multiple Domain Authentication
When a CitectSCADA Windows login is performed on a Control Client or View-only
Client that is part of a domain, the client itself is responsible for authenticating with the
domain. When that client has access to CitectSCADA servers on more than one domain,
it is possible that the client will only be authenticated on one of the domains.
CtAPI Authentication
In this release CtAPI does not support operations with Windows security.

Authenticating a Trusted Network

Computers that are part of the trusted SCADA network will now use a shared secret
password to authenticate each other. This machine password is configured using the
Computer Setup Wizard, and the INI parameter [Client]PartofTrustedNetwork.
If the password has not been configured, and is necessary at runtime due to the INI set-
ting, the servers will become inoperable. An appropriate message will then be recorded
in the syslog.
See Also

Running the Computer Setup Wizard

215
Chapter: 11 Using CitectSCADA Security

Setting the Super User Password

You configure the Super User password using the Computer Setup Wizard. You will
only set this password once, and only for a system running in multi-process mode. Com-
puter Setup Wizard will automatically configure the [Server]AutoLoginMode INI param-
eter in line with the user's settings.
See Also

Authenticating a Trusted Network

216
Chapter: 12 Configuring Your System
Before you run your project you will need to configure each computer in your Citect-
SCADA system. Configuration information is stored on each machine in a Citect.ini file
based on your installation, database configuration and compiled project. Configuration
is done with the Computer Setup Wizard.
The Computer Setup Wizard contains a series of pages allowing configuration of the
computer specific settings including:
l The role the computer has in the system network
l The project being run
l The CPU Configuration
l The CitectSCADA Events enabled for each component
l The Cicode run for each component on startup
l The cluster configuration
l The security settings applied
The wizard uses the configuration stored in the project databases to provide information
to you. Selected options are written to the Citect.ini file.
The wizard needs to be run on each computer in your system to appropriately configure
CitectSCADA for each particular machine. Run after compiling your project and as the
last step before running the system.
See Also
Running the Computer Setup Wizard

Running the Computer Setup Wizard

To start the Citect Computer Setup Wizard:

1. Open Citect Explorer.

2. In the project list area, select My Projects - designated by a computer icon.
3. Double-click the Computer Setup Wizard icon, or choose Tools | Computer Setup
Wizard. The Citect Computer Setup Wizard is displayed.
4. Select Express Setup or Custom Setup.
The pages that are displayed depend on the configuration of the machine and include:

217
Chapter: 12 Configuring Your System

l Project Configuration
l Computer Role Configuration
l Network Model
l Server Password Configuration
l Server User Configuration
l Internet Server Configuration
l Alarm Configuration
l Reports Configuration
l Trends Configuration
l CPU Configuration
l Events Configuration
l Startup Functions Configuration
l Cluster Connections Configuration *
l Control Menu Security Configuration *
l Keyboard Security Configuration *
l Miscellaneous Security Configuration *
l General Options Setup *
* Only available in Custom Setup mode.
Each screen of the wizard is described in the sections that follow.
See Also
Project Configuration

Project Configuration
The dialog box for project configuration will vary depending on whether you are con-
figuring a project from a development and configuration environment, or from a runtime
only environment.
Development and configuration environment

Select the project to run on this CitectSCADA computer. The Computer Setup Wizard
will show you the compiled projects defined in the project list, apart from the include
projects.
If there is only one compiled project present, it will be automatically selected. If there are
no compiled projects present, an alert message is displayed and the wizard will ter-
minate. If this occurs, return to Citect Explorer and confirm that the necessary project is
saved locally and has compiled without errors.

218
 Chapter: 12 Configuring Your System

See Also
Computer Role Configuration

Runtime only environment

Before configuring the runtime only environment, and running the computer setup wiz-
ard, it is assumed you have transferred a project from the configuration environment,
including compiled projects to your local machine. If not refer to Backing up a project for
more information.
Using the .CTZ files from your backup included projects and target project, you can
restore the project. It is recommended you restore the included project before the target
project. The restore project tool is available from the start menu shortcut Runtime Con-
figuration ->Project restore
In the Project Restore dialog :
1. In the Backup file field, browse or enter the name of the project to restore.
2. Under To, the option 'Current project', may be unavailable, this is due to no project
having been run on the local machine before. The option 'New project' will be
selected to restore a backed up project as a new one.
3. In the Name field, enter a name of the restored project.
4. In the Location field, enter or browse to the location of the project to restore (restore
the project under the 'User' folder).
5. Leave the remaining settings as default and click OK.
6. The project will be restored.
You are now ready to run the computer setup wizard available from the start menu
shortcut Runtime Configuration ->CitectSCADA.Computer Setup
In the RUN path edit box enter, or use the select button to browse for, the path to the
local project that you wish to the client to run.If you enter the run path set the run folder
under the ‘User’ Folder.
If you wish to maintain a synchronized local version of an external project select the Ena-
ble RUN/COPY deployment check box. Then in the COPY path edit box enter, or use the
select button to browse for, the path to the external project that you wish maintain syn-
chronization. This feature uses the [CtEdit]RUN and [CtEdit]COPY commands to main-
tain synchronization between the two projects.

219
Chapter: 12 Configuring Your System

Note: The Run/Copy mechanism does not transfer custom files such as meta-data,
icons, images or runtime DBF files. Therefore, it is recommended deploying a project
before Run/Copy to help ensure that those files at least exist. You will still need to re-
deploy a project, when you want to update the custom files.

See Also
Computer Role Configuration

Computer Role Configuration

Use the Computer Role Setup page to specify the role of the computer running Citect-
SCADA. Select one of the options described below.

Note: In order to use CitectSCADA's multi-process capabilities, networking needs to

be enabled.

Option Description

This computer will be a standalone or networked I/O Server and Control Client.
Server This option is disabled if this computer has no Server components assigned to it
and to run. Selecting this option enables the Multi-Process check box.
Control
Select the Multi-Process check box to separate your client and server com-
Client ponents into individual processes. This option can be used for distributing the
components across multiple CPUs.

If you leave the Multi-Process check box unselected, CitectSCADA will run the
client and server components in one process.

If the Multi-Process check box is selected the [General]MultiProcess parameter

in the Citect.ini file is saved with the value 1. If not selected, the parameter is
saved with the value 0.

Con- This computer will only be a Control Client. This option is disabled if this com-
trol puter has been assigned a Server component to run. Selecting this option ena-
Client bles the Full License check box.

Select the Full License check box if you want this Control Client to use a full
license. This sets the [Client]FullLicense parameter in the Citect.ini file to 1 (the
default value).

This computer will only be a View-only Client. This read only option is disabled if
View- this computer has been assigned a Server component to run.
only
Client

220
 Chapter: 12 Configuring Your System

Some of these options may be disabled depending on what servers have been configured
to run on this computer. The Computer Setup Wizard cross-references your computer's
network identification with the network addresses configured for each server in your
project configuration.
See Also
Network Model
CPU Configuration

Network Model
Select the network model to be applied to this CitectSCADA computer. Options include:
l Stand alone (no other SCADA computers))
l Networked (connect to other SCADA computers)
From Version 7.0 CitectSCADA uses TCP/IP to facilitate communications across a net-
work.

Note: TCP/IP address information for Citect servers is configured within the Citect
project itself. See Network Address Definitions for more information.

When you complete the Computer Setup Wizard, the chosen network model is written to
the [LAN] section in the citect.ini file; for example:

...
[LAN]
TCPIP=1
...

See Also
Internet Server Configuration

Configure Server Password

If networking is enabled use this page to configure the machine password. The machine
password is used by computers to authenticate each other and create a trusted network
between servers. Configuring the password automatically sets the [Client]Pa-
rtofTrustedNetwork INI parameter.
If a server process exists and networking has been enabled:
The Configure Server Password checkbox is selected and unavailable.

221
Chapter: 12 Configuring Your System

Enter the Password, and confirm the password in the fields provided, before clicking
Next.
If a client process exists and networking is enabled:
The Configure check box is unchecked. Select to enable the password fields.
Enter the password and confirm password in the fields provided, before clicking Next

Note: If a server password has already been configured for the machine, the ‘Pass-
word’ and “Confirm Password” fields will be pre-filled.

See Also
Configure Server User

Configure Server User

Use this page to define the user to log in for the server processes running on the
machine. The user can be the default server user, none (view-only), or a specified user.
The Computer Setup wizard will automatically configure the [Server]AutoLoginMode
INI parameter in line with the user’s settings.
Select 'Specific User' to enable the Configure Server User fields. The fields will remain dis-
abled if either the 'Default Server User' option or 'None' option are selected.
See Also
Configure Server Password

Internet Server Configuration

Select the This computer is an IDC Server option to make the computer an Internet
Server. To allow communication with a remote Internet Display Client, an Internet
Server requires a permanent Internet connection and a static IP address (or hostname).
1. In the Client Connection Information area, type the Internet Server IP address or
hostname. This adds a Primary=<Internet Server IP address> entry to the [DNS] section
of the citect.ini file if there was no pre-existing entry. For details, see [DNS]Primary
in the Parameter online help.

Note: To determine the TCP/IP address of the Internet Server computer, choose
Start | Run. Type CMD and press Enter. Then at the DOS prompt type IPCON-
FIG and press Enter.

222
 Chapter: 12 Configuring Your System

2. Type the Alternate Internet Server IP address or hostname. This adds a

Standby=<Alternate Internet Server IP address> entry to the [DNS] section of the
citect.ini file if there was no pre-existing entry. For details, see "[DNS]Standby" in
the Parameters online help.
The Internet Display Client automatically connects to this alternate server if connection
to the primary server is lost.

Note: that this can only happen automatically if an initial connection has previously
been made to the primary Internet Server.

See Also
Alarm Configuration
DNS Parameters

Alarm Configuration
The Alarm Configuration page will only be displayed if this machine is configured as an
Alarm Server in the Project Editor.
CitectSCADA has several options available for alarm processing. These are set in the
Alarm section of the Citect.ini file. Refer to the Parameters help for information on these
parameters.

Option Description

Alarm Determines the rate at which alarms are scanned and processed. A value of
scan 500 (the default value) indicates that CitectSCADA tries to process the alarms
time every 500 ms. However, if CitectSCADA cannot read the alarm data from the
I/O Device within 500 ms, the alarms are processed at a slower rate. For exam-
ple, if it takes 800 ms to read the alarm data from the I/O Device, CitectSCADA
processes the alarms every 800 ms.

If you select a larger value for the alarm scan time, the alarms server uses less
CPU (because it does not need to process the alarm records as often). The
amount of data read from the I/O Device is also reduced, so that other proc-
esses (Trends, Reports, and the current page) get their I/O Device data more
quickly. You can enter any value from 0 to 60000 (milliseconds).

Alarm The period for saving alarm and event data (to disk). You can save alarm and
save event data periodically so that the data is restored after a planned or
period unplanned system shutdown. The smaller the period, the greater is the load on
the system.

223
Chapter: 12 Configuring Your System

Sum- The maximum number of alarm summary entries that can be held in memory.
mary You can view these alarm summary entries on the alarm summary page. Each
length event requires approximately 300 bytes of memory, including the length of the
comment. 10,000 events require 3 to 4 MB of memory. If you use many events,
have enough memory to keep them in RAM.

Sum- The length of time that alarm summary entries remain in the alarm summary
mary queue.
timeout

Pri- The path to the primary save files. CitectSCADA uses two save files for each
mary alarms server, ALMSAV.DAT and ALMINDEXSAVE.DAT. The save primary path
alarms is the directory where the primary alarms server creates its save files. When
server restoring the files, the most recent (of the primary and secondary) save files
save will be used.
path

The path to the secondary save files.

Standby

alarms
server
save
path

To minimize the chance of conflicts between alarm files used by multiple Alarm Servers
from different clusters running on the same machine, the alarm files have a dynamic
naming convention based on the following format:
<ProjectName>_<ClusterName>_<filename>.DAT

See Also
Reports Configuration

Reports Configuration
The Reports Configuration page will only be displayed if this machine is configured as a
Reports Server in the Project Editor.

Note: For a networked computer to be a Reports Server it needs to also be the I/O
Server or needs to be able to communicate with the I/O Server on the network.

CitectSCADA has several options available for report processing:

Option Description

224
 Chapter: 12 Configuring Your System

Startup Defines the name of the report to run when CitectSCADA starts up.
report

Inhibit trig- For example, you might have a report that is triggered off the rising edge
gered of a bit on startup. The Reports Server notices the bit come on, and runs
reports on the report. If this option is checked, the Reports Server does not run this
startup report until it has read the I/O Devices a second time.

Run Enables or disables tandem processing of reports. If this server is the

reports standby Reports Server, it can process every report in tandem with the pri-
concurrently mary server, or it can remain idle until called.
with pri-
mary
Reports
Server

See Also
Trends Configuration

Trends Configuration
The Trends Configuration page will only be displayed if this machine is configured as a
Trends Server in the Project Editor.

Note: For a networked computer to be a Trends Server it needs to also be the I/O
Server or needs to be able to communicate with the I/O Server on the network.

CitectSCADA has one option available for trend processing:

Option Description

Inhibit triggered trends on You might have a trend that is triggered off the rising
startup edge of a bit on startup. If this option is enabled, the
trends server does not display the trend until it has read
the I/O Devices a second time.

See Also
CPU Configuration

CPU Configuration
The CPU Setup page is used to assign client and server components to specific proc-
essors in a multi-processor machine.

225
Chapter: 12 Configuring Your System

This page lists each component's full name, including the cluster to which it belongs, the
priority and the CPU assignment. If the Multi-process option was not selected on the
Computer Role Configuration page there will only be one entry listed, either Client or
Client and Servers. If the Multi-process option was selected, you have the option of select-
ing specific CPUs for the Client, I/O Server, Alarm Server, Trends Server and Reports
Server.
To assign a CPU to a component:

1. Select one or more components from the list (hold the Ctrl key down to select mul-
tiple components).
2. Click Modify.
3. Type the number of the CPU and click OK.
When you complete the Computer Setup Wizard, the CPU assignations are written to
each component section in the Citect.ini file; for example:

...
[Alarm.Cluster1.AlarmServer1]
CPU=1
Clusters=Cluster1
...
[Trend.Cluster1.TrendServer1]
CPU=2
Clusters=Cluster1
...

See Also
Events Configuration

Events Configuration
Events are used to trigger actions, such as a command or set of commands. For example,
an operator can be notified when a process is complete, or a series of instructions can be
executed when a process reaches a certain stage. Select the Enable Events on this com-
puter check box if events are to be enabled on this CitectSCADA computer.
The Events Setup page lists each component's full name, including the cluster to which
it belongs, alongside a list of events that can be enabled for each component. If the
Multi-process option was not selected on the Computer Role Configuration page there
will only be one entry listed, either Client or Client and Servers. If the Multi-process
option was selected, you have the option of enabling events for each component on this
computer.

226
 Chapter: 12 Configuring Your System

Note: The Computer Setup Wizard only displays named events from the selected
project. If you are using events in included projects you will need to edit your
Citect.ini file to add these under the [Events] section header.

Note: Events named 'Global' or events with no title will not appear as these are
global events. These events will run on computers that have events enabled. These
events will run in the client process.

To enable an event for a component:

1. Select the component from the list.

2. Select the events you want to enable for that component, or click Enable All or Dis-
able All.
3. Click Next when finished.
When you complete the Computer Setup Wizard, the events are written to each com-
ponent section in the Citect.ini file; for example:

...
[Alarm.Cluster1.AlarmServer1]
CPU=1
Clusters=Cluster1
Events=CSV_AlarmClient
...
[Trend.Cluster1.TrendServer1]
CPU=2
Clusters=Cluster1
Events=CSV_TrendXClient,CSV_TrendXServer
...

See Also
Startup Functions Configuration

Startup Functions Configuration

The Startup Functions Setup page is used to define the Startup Cicode that is executed by
each CitectSCADA process.
The Startup Functions Setup page lists each component's full name, including the cluster
to which it belongs, the priorities of the components and the startup function assigned to
each component. If the Multi-process option was not selected on the Computer Role Con-
figuration page there will only be one entry listed, either Client or Client and Servers. If
the Multi-process option was selected, you have the option of assigning startup func-
tions for each component on this computer.

227
Chapter: 12 Configuring Your System

If the StartupCode parameter value for a process is invalid, the CitectSCADA Runtime
Manager will simply ignore it on start up.
To assign a startup function to a component:

1. Select the component from the list. To select multiple components, hold down the
Ctrl key as you select each item.
2. Click Modify.
3. Type the name of the Cicode function you want to call on startup for that component.
4. Click OK.
When you complete the Computer Setup Wizard, the events are written to each com-
ponent section in the citect.ini file; for example:

...
[Alarm.Cluster1.AlarmServer1]
CPU=1
StartupCode=alarmServerStartup
...
[Trend.Cluster1.TrendServer1]
CPU=2
StartupCode=trendServerStartup
...

See Also
CPU Configuration
Cluster Connections Configuration

Cluster Connections Configuration

The Cluster Connections Setup page is used to specify the clusters that each component
connects to on startup. This controls what data streams a component can see in the sys-
tem.
The Cluster Connections Setup page lists each component's full name, including the
cluster to which it belongs, the priorities of the components and the clusters assigned to
each component. If the Multi-process option was not selected on the Computer Role Con-
figuration page there will only be one entry listed, either Client or Client and Servers. If
the Multi-process option was selected, you have the option of assigning clusters for each
component on this computer.
By default, every component will connect to every cluster unless otherwise modified.
If the Clusters parameter value for a process is invalid, then the CitectSCADA Runtime
will simply ignore it on startup.
To assign a cluster to a component:

228
 Chapter: 12 Configuring Your System

1. Select the component from the list. To select multiple components, hold down the
Ctrl key as you select each item.
2. Click Modify.
3. Select the clusters you want the component to connect to on startup.
4. Click OK.
When you complete the Computer Setup Wizard, the clusters are written to each com-
ponent section in the Citect.ini file; for example:

...
[Alarm.Cluster1.AlarmServer1]
CPU=1
Clusters=Sydney
...
[Trend.Cluster1.TrendServer1]
CPU=2
Clusters=Sydney,Tokyo
...

See Also
Implementing Clustering

Control Menu Security Configuration

The CitectSCADA window property options allow you to control an operator's access to
system features.
This allows for flexibility with system security at run time.

Option Description

Citect- Allows the operator to use the control menu (top left-hand icon) to access
SCADA the Citect Editor, Project Editor, Graphics Builder, and Cicode Editor from
configuration CitectSCADA at run time. Disabling this provides better security.
envi-
ronment
on menu

FullScreen Allows the operator to set whether pages will be displayed in fullscreen or
restored state. When checked “FullScreen” will set the ini parameter
[Animator]FullScreen to 1. If “FullScreen” is set.

Show title Allows the operator to set whether pages will be displayed in fullscreen mode
bar with the title bar. The [Animator]FullScreen ini parameter is set as follows: 0
if “Fullscreen” is unchecked; 1 if “Fullscreen” is checked and “Show title bar”
is unchecked; 2 if both “Fullscreen” and “Show title bar” are checked.
“Show title bar” cannot be modified if the option“Fullscreen” is unselected.

229
Chapter: 12 Configuring Your System

Shutdown Allows the operator to use the control menu (top-left icon) to shut down
on menu CitectSCADA at runtime. The shutdown is not password- or privilege-pro-
tected. Disabling this provides better security.

Kernel on Allows the operator to use the control menu (top left icon) to display the
menu CitectSCADA Kernel at run time. Disabling this provides better security.

See Also
Keyboard Security Configuration

Keyboard Security Configuration

Windows has a set of standard task-swapping shortcut commands that are (optionally)
supported by CitectSCADA at run time. This option allows the Alt-Space Windows com-
mand to be enabled or disabled at run time. Alt-Space provides access to the Windows
control menu (even if the title bar has been disabled).

Note: The ability to disable Alt-Escape, Ctrl-Escape and Alt-Tab is not currently avail-
able.

See Also
Miscellaneous Security Configuration

Miscellaneous Security Configuration

Some standard Windows features may interfere with the secure operation of your sys-
tem. Use the Miscellaneous Security page to disable these features.

Option Description

Inhibit screen saver while CitectSCADA is Stops the screen saver from blanking out
running important screens that have to be always
visible. Alternatively the screen saver pass-
word can add additional security features

Display Cancel button at startup Provides the ability to stop CitectSCADA

from starting up automatically. Automatic
startup is a potential security concern

See Also
General Options Setup

230
 Chapter: 12 Configuring Your System

General Options Setup

Use the General Options Setup page to specify general options.

Option Description

Data Directory The directory where the CitectSCADA data files are located. The
data files are the files that are generated at run time: trend files,
disk PLC etc.

Backup project The backup directory that is used if a runtime database cannot be
path located (due to inoperative hardware or a file that has been moved,
corrupted, or deleted).

Startup page The Page Name of the graphics page to display when CitectSCADA
starts up.

Page scan time The delay (in milliseconds) between updating a graphics page and
starting the next communications cycle. The Page Scan Time sets
the default for how often your graphics pages are updated. When a
page is updated, relevant data (variable tags etc. represented on
the graphics page) is scanned to determine if field conditions have
changed. This setting is overridden by the Scan Time value spec-
ified in Page Properties (if applied).

A value of 250 (the default value) indicates that CitectSCADA will try
to update the page every 250 ms. However, if CitectSCADA cannot
read the entire data from the I/O Device within 250 ms, the page is
processed at a slower rate. For example, if it takes 800 ms to read
the data from the relevant I/O Device, CitectSCADA processes the
page every 800 ms.

Under some conditions, you might want to slow the update of your
pages to reduce the load on the I/O Servers. By reducing the page
scan time, you allow more communication bandwidth to other Citect-
SCADA tasks or Clients. For example, you might want fast response
on your main operator computers, while slowing the response time
on manager computers. You can enter any value from 0 to 60000
(milliseconds).

See Also
Finish

Finish
Click Finish to save the setup to the Citect.ini file, Cancel to quit the wizard without
saving, or Back to navigate to a page that requires adjusting.

231
Chapter: 12 Configuring Your System

232
Chapter: 13 Implementing Clustering
Once you have designed the clustering for your system, including the configurations of
servers you need, you can proceed to implement that design. You will need to configure:
l Cluster Definitions
Each cluster needs to be defined by giving it a unique name in the project.
l Network Address Definitions
Each physical server in your system needs to be identified with a unique name and
IP address.
l Alarm Server Definitions
Each Alarm Server needs to be named, and assigned to a cluster and physical server.
Identify each server as Primary or Standby.
l Reports Server Definitions
Each Reports Server needs to be named, and assigned to a cluster and physical
server. Identify each server as Primary or Standby.
l Trends Server Definitions
Each Trends Server needs to be named, and assigned to a cluster and physical
server. Identify each server as Primary or Standby.
l I/O Server Definitions
Each I/O Server needs to be named, and assigned to a cluster and physical server.
Identify each server as Primary or Standby.
See Also
Rules of Clustering
Assigning tags to a cluster at Runtime

Rules of Clustering
When configuring CitectSCADA the following clustering rules apply:
l Each cluster to have a unique name.
l Each server component to have a unique name.
l Each server component needs to belong to one cluster.
l Each cluster can contain only one pair of redundant Alarm Servers. They need to
reside on different machines.
l Each cluster can contain only one pair of redundant Reports Servers. They need to
reside on different machines.

233
Chapter: 13 Implementing Clustering

l Each cluster can contain only one pair of redundant Trends Servers. They need to
reside on different machines.
l Each cluster can contain an unlimited number of I/O Servers.
There are countless variations in how a clustered system can be configured. The most
appropriate configuration will depend on the requirements for the solution to be
deployed and the environment in which it is being deployed. For more information, refer
to Typical system scenarios.
The diagram below is an example of a system running with two clusters across three
machines. Every server and client component have been deployed in accordance with
the clustering rules.

The next diagram demonstrates circumstances which do not correctly follow the clus-
tering rules.

234
 Chapter: 13 Implementing Clustering

The CitectSCADA compiler or the CitectSCADA Runtime Manager detects when the
rules of clustering are not being observed and advises the user accordingly.
See Also
About cluster context

Cluster Definitions
See Rules of Clustering for additional information.
To define a cluster:

1. In the Project Editor, choose Servers | Clusters.

2. In the Cluster dialog box, complete the cluster properties:

Option Description

Cluster Name The name of the cluster. The name needs to be

unique to the project and not contain spaces.

235
Chapter: 13 Implementing Clustering

Comment Any useful comment. This property is optional and

is not used at runtime.

3. Click the Add button to append a new record, or Replace if you have modified a rec-
ord.
See Also
Network Address Definitions

Network Address Definitions

To configure a network address:

1. In the Project Editor, choose Servers | Network Addresses.

2. In the Network Addresses dialog box, complete the properties:

Option Description

Name The name of the machine at the network address being con-
figured. The name needs to be unique to the project and
not contain spaces.

The IP address or computer name of the machine or net-

Address work card being configured. For machines with dual net-
work cards, add a network address for each card in each
machine to which you want to communicate. See Network
Redundancy for information.

Com- Any useful comment. This property is optional and is not

ment used at runtime.

3. Click the Add button to append a new record, or Replace if you have modified a rec-
ord.
See Also
Alarm Server Definitions

Alarm Server Definitions

Refer to the default server port numbers under Configure Servers.

236
 Chapter: 13 Implementing Clustering

Note: The Alarm server reuses the Alarm Properties port. As a result alarm prop-
erties are now published for configured alarm servers.

To configure an Alarm Server:

1. In the Project Editor, choose Servers | Alarm Servers.

2. In the Alarm Servers dialog box, complete the properties:

Option Description

Cluster The name of the cluster to which this Alarm Server will
Name belong. If there is only one cluster defined in the
project, you can leave this field blank. The Alarm Server
will default to the defined cluster

Server The name of the server. The name needs to be unique

Name to the project and any included projects, and not con-
tain spaces.

Mode The mode for this server, either Primary or Standby. If

this property is left blank, the default value will be Pri-
mary. The Primary and Standby servers need to run on
different computers, and only one Primary and one
Standby can be defined per cluster.

Network The network address(es) of the server being con-

Addresses figured. To specify dual network connections to the
server, use a comma delimited list. See Network Redun-
dancy.

Port The port this server will listen on. You can leave this
field blank if you are running only one Alarm Server on
the machine, in which case the default port number will
be used.

Comment Any useful comment. This property is optional and is

not used at runtime.

Extended forms fields

The following fields are implemented with extended forms (press
F2).

Note: Servers listen on legacy ports only if the INI parameter

[LAN] EarliestLegacyVersion has been enabled.

237
Chapter: 13 Implementing Clustering

Option Description

Legacy Allows legacy connections to the server

Port

3. Click the Add button to append a new record, or Replace if you have modified a rec-
ord.
See Also
Reports Server Definitions

Reports Server Definitions

Note the default server port numbers under Configure Servers.
To configure a Reports Server:

1. In the Project Editor, choose Servers | Reports Servers.

2. In the Reports Servers dialog box, complete the properties:

Option Description

Cluster The name of the cluster to which this Reports Server

Name will belong. If there is only one cluster defined in the
project, you can leave this field blank. The Reports
Server will default to the defined cluster

Server The name of the server. The name needs to be unique

Name to the project and not contain spaces.

Mode The mode for this server, either Primary or Standby. If

this property is left blank, the default value will be Pri-
mary. The Primary and Standby servers need to run on
different computers, and only one Primary and one
Standby can be defined per cluster.

Network The network address(es) of the server being con-

Addresses figured. To specify dual network connections to the
server, use a comma delimited list. See Network Redun-
dancy.

Port The port this server will listen on. You can leave this
field blank if you are running only one Reports Server
on the machine, in which case the default port number
will be used.

Comment Any useful comment. This property is optional and is

not used at runtime.

238
 Chapter: 13 Implementing Clustering

Extended forms fields

The following fields are implemented with extended forms (press F2).

Note: Servers listen on legacy ports only if the INI parameter [LAN] Ear-
liestLegacyVersion has been enabled.

Option Description

Legacy Allows legacy connections to the server

Port

3. Click the Add button to append a new record, or Replace if you have modified a rec-
ord.
See Also
Trends Server Definitions

Trends Server Definitions

Note the default server port numbers under Configure Servers.
To configure a Trends Server:

1. In the Project Editor, choose Servers | Trend Servers.

2. In the Trends Servers dialog box, complete the properties:

Option Description

Cluster The name of the cluster to which this Trends Server will
Name belong. If there is only one cluster defined in the project,
you can leave this field blank. The Trends Server will
default to the defined cluster.

Server The name of the server. The name needs to be unique to

Name the project and not contain spaces.

Mode The mode for this server, either Primary or Standby. If

this property is left blank, the default value will be Pri-
mary. The Primary and Standby servers need to run on dif-
ferent computers, and only one Primary and one Standby
can be defined per cluster.

Net- The network address(es) of the server being configured.

work To specify dual network connections to the server, use a
Addresses comma delimited list. See Network Redundancy.

239
Chapter: 13 Implementing Clustering

Option Description

Port The port this server will listen on. You can leave this field
blank if you are running only one Trends Server on the
machine, in which case the default port number will be
used.

Com- Any useful comment. This property is optional and is not

ment used at runtime.

Extended forms fields

The following fields are implemented with extended forms (press F2).

Note: Servers listen on legacy ports only if the INI parameter [LAN] Ear-
liestLegacyVersion has been enabled.

Option Description

Legacy Allows legacy connections to the server

Port

3. Click the Add button to append a new record, or Replace if you have modified a rec-
ord.
See Also
I/O Server Definitions

I/O Server Definitions

Note the default server port numbers under Configure Servers.
To configure an I/O Server

1. In the Project Editor, choose Servers | I/O Servers.

2. In the I/O Servers dialog box, complete the properties.

Option Description

Cluster The name of the cluster to which this I/O Server will belong. If there is only
Name one cluster defined in the project, you can leave this field blank. The I/O
Server will default to the defined cluster. 16 characters maximum.

240
 Chapter: 13 Implementing Clustering

Server The name of the server. The name needs to be unique to the project and
Name any included projects, and not contain spaces. 16 characters maximum.

Network The network address(es) of the server being configured. To specify dual
Addresses network connections to the server, use a comma delimited list. See Net-
work Redundancy. 70 characters maximum.

Port The port this server will listen on. You may leave this blank in which case
the default port number will be used. 16 characters maximum.

Comment Any useful comment. This property is optional and is not used at runtime.
48 characters maximum.

Extended forms fields

The following fields are implemented with extended forms (press F2).

Note: Servers listen on legacy ports only if the INI parameter [LAN]Ea-
rliestLegacyVersion has been enabled.

Option Description

Legacy Port Allows legacy connections to the server

1. Click the Add button to append a new record, or Replace if you have modified a rec-
ord.

Assigning tags to a cluster at Runtime

CitectSCADA includes functionality that allows you to assign the tags on a page to a spe-
cific cluster during Runtime.
If the tags on a page exist within a number of different clusters, you can use Cicode to
pass a cluster name to the page as it opens. Any tags that do not have a cluster explic-
itly defined will then be assigned to the specified cluster as the page is launched.
This provides a practical solution for a replicated system, where your project controls a
number or identical sites or production lines. As the sites contain the same equipment,
the tags representing the hardware architecture will potentially be the same for each. The
ability to pass a cluster name to a page at runtime means just a single mimic page is nec-
essary to represent multiple sites, reducing configuration time and simplifying project
deployment.

241
Chapter: 13 Implementing Clustering

For example, a menu page could be created to launch the mimic page for three identical
production lines, each based on the same page called "ProductionLine".
To achieve this, you would use the PageDisplay function to configure the following but-
tons on your menu page:

Button one Text Production Line A

Com- PageDisplay("ProductionLine","Cluster_A")
mand

Com- Display the mimic page in the context of production line A

ment

Button two Text Production Line B

Com- PageDisplay("ProductionLine","Cluster_B")
mand

Com- Display the mimic page in the context of production line B

ment

Button Text Production Line C

three
Com- PageDisplay("ProductionLine","Cluster_C")
mand

Com- Display the mimic page in the context of production line C

ment

In each case, PageDisplay would pass the name of the host cluster to the page, depend-
ing on which button is selected. As each production line shares a common architecture,
any tags that do not have a cluster explicitly defined will be assigned to the specified
cluster as the page is opened.
This functionality is supported by the following Cicode functions:
l PageDisplay
l PageGoto
l WinNew
l WinNewAt
You can also use the PageInfo function to determine the cluster context that has been set
for a page.

242
 Chapter: 13 Implementing Clustering

This functionality extends to any Cicode that may be called from a graphics page. You
can write Cicode that only specifies variable tag names, allowing the cluster to be
defined by the current context of the page from which it is launched.
If the Cicode is executed by the function TaskNew, you have the option to specify a
cluster by setting the ClusterName parameter.

Note: The cluster context for Cicode cannot be changed once the code is running.

243
Chapter: 13 Implementing Clustering

244
Chapter: 14 Building Redundancy Into Your Sys-
tem
Redundancy in CitectSCADA can be defined at many different levels. When building
redundancy for your system, it is important to consider the degree of protection nec-
essary to meet your requirements, by:
l Defining how important your processes are;
l Determining the overall likelihood of system downtime, and the important processes
and equipment that will take the longest to restore to service;
l Deciding which components you would like to implement redundancy for; and
l Considering design and maintenance consequences of redundancy.
The section covers the following redundancy concepts:
l I/O Server Redundancy
l I/O Device promotion
l Redundancy and Persistence
l Data Path Redundancy
l Network Redundancy
l Alarms, Reports, and Trends Server Redundancy

Note: Using the Computer Setup Wizard will allow you to define the level of redun-
dancy you require by defining the function of each computer (See Running the Com-
puter Setup Wizard).

See Also
Alarms, Reports, and Trends Server Redundancy
How CitectSCADA handles file server redundancy
How CitectSCADA handles FTP server redundancy
Redundancy of Standalone Systems

245
Chapter: 14 Building Redundancy Into Your System

I/O Server Redundancy

Systems with a single I/O Server can be interrupted by the inoperability of a single
device or process. If the primary server isn't operating normally, control and monitoring
of the system is lost. By introducing a second I/O Server and dedicating it to com-
municating with the same I/O Devices, the ability of a single device to influence the sys-
tem as a whole is minimized. You now have a primary and standby I/O Server in your
system where the standby I/O Server will assume operations in case the primary I/O
Server becomes inoperative.
The diagram below illustrates the introduction of a standby I/O Server into the existing
system. When the system is in operation, both I/O Servers are identically maintained.

Note: Although both I/O Servers are identical, it is important to recognize that the
standby server is not duplicating the primary server's functions. If it were, the load
on the PLC portion of the network would be double and would significantly reduce
performance. Therefore, only the primary server communicates with the PLCs at any
given time.

Redundancy is provided as follows:

l When the system is in operation and the primary I/O Server becomes inoperative, or
if you wish to perform some maintenance and take it offline, every client will be
reverted to the standby server with minimal or no interruption to the system.

246
 Chapter: 14 Building Redundancy Into Your System

l When the primary server is brought back online, the system returns control of the I/O
Devices back to the primary server. This is done by copying the disk image from the
standby server to the primary, allowing the clients to reconnect to it, and thereby
resuming control of the system.
When the system is running, you can also use redundant I/O Servers to split the proc-
essing load. This would result in higher performance as every I/O Server would be run-
ning in parallel when servicing the I/O Devices.
See Also
I/O Device promotion

I/O Device promotion

I/O Device promotion refers to when a system event forces a standby I/O Device to
assume a primary role during Runtime.
If there is more than one standby device available within a cluster, the order they are pro-
moted in will depend on how your project has been configured.
If necessary, you can manually set the order your standby devices are promoted in via
the Priority field on the extended I/O Devices Properties form. If priorities are not set, the
compiler automatically allocates a priority value to each standby device based on the fol-
lowing rules:
l user-configured priority settings take precedence
l any standby devices that do not have a priority setting will follow those that do, their
priority being allocated in the order they were configured
l if no standby devices have a priority setting, they will be assigned priority according
to the order they were configured.
These rules apply regardless of the connections between the I/O Devices and I/O Servers
configured in a cluster.
The standby device priorities are confirmed and/or allocated during project compilation.
Notification is provided for each allocation issued by the compiler. Compile errors will
occur under the following circumstances:
l if a primary device has a priority setting other than the default value of 1
l if standby devices have duplicated priority values.

Example
The following diagram shows four I/O Devices connected to two I/O Servers, with just
one primary device configured.

247
Chapter: 14 Building Redundancy Into Your System

If no priorities were set for the standby devices, the compiler would allocate the fol-
lowing:
l I/O Device1 is allocated Priority 1 by default (no compiler alert)
l I/O Device2 is allocated Priority 2 (compiler warning alert)
l I/O Device3 is allocated Priority 3 (compiler warning alert)
l I/O Device4 is allocated Priority 4 (compiler warning alert)
This presumes the devices were configured in numerical order.
If I/O Device3 has been manually set to priority 2, the compiler would allocate the fol-
lowing:
l I/O Device1 is allocated Priority 1 by default (no compiler alert)
l I/O Device2 is allocated Priority 3 (compiler alert generated)
l I/O Device3 is allocated Priority 2 (no alert generated)
l I/O Device4 is allocated Priority 4 (compiler alert generated)
In this case, the setting for I/O Device3 has taken precedence. The remaining standby
devices are set for promotion based on the order they were configured.

Note: The automated priorities work on an n+1 equation; if I/O Device3 has been set
to Priority 5, the remaining devices would have been allocated priority 6 and 7.

See Also
Redundancy and Persistence
Data Path Redundancy

248
 Chapter: 14 Building Redundancy Into Your System

Redundancy and Persistence

If you are using Server redundancy, Persistence Caches (I/O Server cache) keep standby
servers updated with the most recently read device data. A Persistence Cache, or I/O
Server Cache, is created for each cached I/O Device. The following diagram introduces
the concept of a Persistence Cache.

The diagram shows that there are two I/O Servers, namely IOServer1 (primary) and
IOServer2 (standby). Each connects to the public switched telephone network (PSTN) via
a modem, which is in turn connects to the I/O Devices, also over a modem. Persistence
Caches work as follows:
1. Every IODevices->Cache Time period, data from an I/O Device is stored temporarily
in the memory of the I/O Server (I/O Server cache).
2. For every [IOServer]SavePeriod, IOServer1 saves its in-memory cache to disk.
3. The cache is saved in Persistence Caches -one for each cached device.
4. IOServer1 broadcasts to other I/O Servers the UNC path of the Persistence Caches (set
with [IOServer]SaveNetwork).

249
Chapter: 14 Building Redundancy Into Your System

5. From these Persistence Caches, IOServer2 updates its in-memory cache for its I/O
Devices.
6. Depending on the value of the I/O Server parameter of `[IOServer]SavePeriod' (deter-
mines how often the Persistence Cache is saved to the hard disk in seconds),
IOServer1 saves its in-memory cache to the hard disk every x amount of seconds.

Note: You can define an I/O Device on an I/O Server using the Express Com-
munications Wizard, or by adding a device in the I/O Devices form in Citect-
SCADA's Project Editor.

You are not limited to just one Standby Server, since the UNC path name set in
[IOServer]SaveNetwork is broadcast to I/O Servers. Each I/O Server updates its cache
from the Persistence Caches only for the I/O Devices defined on that server. It is then pos-
sible, therefore, set up several I/O Servers which update their in-memory caches with the
most recently read data.
For example, we set the [IOServer]SaveFile and [IOServer]SaveNetwork parameters as fol-
lows:

On IOServer1 On IOServer2

[IOServer] [IOServer]

SaveFile=C:\Data\IOServer1.dat SaveFile=C:\Data\IOServer2.dat

Save- Save-
Network=\\IOServer1\Data\IOServer1.dat Network=\\IOServer2\Data\IOServer2.dat

IOServer1 would broadcast the following UNC path of the Persistence Cache to other I/O
Servers: '\\IOServer1\Data\IOServer1.dat'. IOServer2 would then use the Persistence
Caches to update its in-memory cache with the device data most recently read by
IOServer1.
See Also
Data Path Redundancy

Data Path Redundancy

Data path redundancy is another form of redundancy involving defining data paths
between the I/O Server and the connected I/O Devices. By providing a second (parallel)
data path, you improve the chances that if one data path to the I/O Device is dis-
connected, the other can be used.

250
 Chapter: 14 Building Redundancy Into Your System

Most brands of PLCs have the facility to allow you to install a parallel data path from
the I/O Server to the I/O Device.

The diagram above shows that an additional data path (running in parallel) has been
defined. The redundancy is provided as follows:
l When you start your runtime system, CitectSCADA connects to the I/O Device using
the primary data path.
l If communications with the I/O Device is lost at any time (for example if the com-
munications cable is disconnected), CitectSCADA will switch to the standby data
path with minimal or no interruption to the system.
l CitectSCADA reconnects through the primary data path when it is returned in to serv-
ice.
On a larger system (such as one running on a network), you can also use data path
redundancy to maintain device communications with multiple I/O Server redundancy,
as shown in the following diagram.

The redundancy is provided as follows:

l By using a redundant data path from the I/O Device (one path to each I/O Server),
you can maintain I/O Device communication.

251
Chapter: 14 Building Redundancy Into Your System

l If communications with either the primary I/O Server or standby I/O Server be dis-
connected, the I/O Device is still accessible.
See Also
Multiple Device Redundancy (Standby Data Paths)

Multiple Device Redundancy (Standby Data Paths)

If your I/O Devices support peer-to-peer communication, you can add another level of
redundancy to your system by duplicating the I/O Devices.

Note: Although I/O Servers are not assigned the Primary or Standby role based on
the I/O devices to which they are connected, it is common practice in redundant I/O
systems to connect the Primary I/O Devices to the Primary I/O Server and the
Standby I/O Devices to the Standby I/O Server. One I/O Server can connect to a mix-
ture of Primary and Standby I/O Devices. The I/O Server can support any number of
Standby Data Paths.

The following diagram demonstrates multiple device redundancy and Standby Data
Paths:

In this scenario, we have three I/O Servers connected to three I/O Devices in the fol-
lowing manner:

252
 Chapter: 14 Building Redundancy Into Your System

I/O Server I/O Devices Connected

IOServer1 I/O Device1 (Primary)

I/O Device2 (Standby)
I/O Device3 (Primary)

IOServer2 I/O Device1 (Standby)

I/O Device2 (Primary)

IOServer3 I/O Device1 (Standby)

I/O Device2 (Standby)
I/O Device3 (Standby)

The following is known:

l CitectSCADA clients communicate with every configured I/O Server at the same time
(on startup, the clients try to connect to each configured I/O Server. If they cannot
establish communications with an I/O Server, a hardware error is generated).
l When every device is running, CitectSCADA processes the I/O on the Primary I/O
Devices (this reduces the I/O load on the I/O Device (and PLC network), which is
important in improving performance).
l The client creates network sessions to the three I/O Servers.
l The client then sends requests for I/O Device1 and I/O Device3 to I/O Server1, and
requests for I/O Device 2 to I/O Server2.
Redundancy is provided as follows:
l If I/O Device1 become inoperative on I/O Server1, the client will send requests for I/O
Device1 to I/O Server2 through the standby data path. It continues to send requests
for I/O Device3 to I/O Server1.
l If I/O Device also becomes inoperative on I/O Server2, the client sends requests to I/O
Server3.
l If the connection between I/O Device1 and I/O Server1 be re-established, the client
resumes sending requests for I/O Device1 to I/O Server1.
The Standby I/O Devices will be activated strictly in the order in which they are first
created in the project. This can be viewed by looking in the Units.dbf file in the project
directory.
Since we can place primary and standby I/O Devices on various I/O Servers, share the
primary I/O Devices between your I/O Servers to balance the loading across the I/O
Servers. However, this might not apply for every protocol because the loading could be
dependent on the PLC network and not the I/O Server CPU. In this case, more than one
active I/O Server on the same PLC Network can degrade the PLC network and therefore,
slow the total response.

253
Chapter: 14 Building Redundancy Into Your System

See Also
Alarms, Reports, and Trends Server Redundancy

Network Redundancy
You can use the dual NIC (or multiple network interface) capabilities of each client or
server, enabling you to specify a complete and unique network connection from a client
to a server.
Consider the following diagram:

The above example shows two levels of redundancy:

l network redundancy
l server redundancy

Network Redundancy
Each of the system components in the cluster are connected to a second network (LAN
2). This is achieved by using the dual end points of each server. This provides con-
nection to two separate LANs to provide for LAN redundancy as follows:

254
 Chapter: 14 Building Redundancy Into Your System

l If LAN 1 is suddenly inoperative, each component in the cluster can easily maintain
connection by using LAN 2.
l In turn, if LAN 2 becomes inoperative, LAN 1 remains in operation.

Server Redundancy
For information about server redundancy, see Alarms, Reports and Trends Server Redun-
dancy.
See Also
Configuring network redundancy

Configuring network redundancy

To connect to machines using dual network connections for redundancy you need to
first define network addresses for each network interface and then specify which net-
work addresses to use for each server.
To configure network redundancy:

1. In the Project Editor, choose Servers | Network Addresses.

2. In the Network Addresses dialog box, define the network address for each network
interface card. See Network Address Definitions.
3. In the Project Editor, choose Servers then the server type you want to connect to the
network.
4. In Network Addresses field of the server configuration dialog box, type the dual
addresses for the server separated by a comma. For example, "Alarm-
PrimaryLAN1,AlarmPrimaryLAN2".
See Also
Network redundancy

Alarms, Reports and Trends Server Redundancy

Redundancy of Alarms, Reports, Trends, and I/O Servers is achieved by adding standby
servers, within a defined cluster, to provide redundant system components. In addition
you can also utilize the dual end point (or multiple network interfaces) capabilities of
each component, effectively enabling you to specify a complete and unique network con-
nection from a client to a server. See Network Redundancy.
Consider the following diagram:

255
Chapter: 14 Building Redundancy Into Your System

Server redundancy of each component in the diagram is achieved by providing a cor-

responding standby server on the same network (LAN 1). Redundancy is provided as fol-
lows:
l If any of the servers become inoperative or communications become inoperative, their
standby counterpart assumes operation.
l For I/O Server redundancy, when the inoperative I/O Server comes back online, it
resumes control based on the individual I/O device primary or standby priority con-
figuration..
l For Alarm, Trend and Report servers, when the inoperative primary server returns
online, the client will remain with the standby unless the primary has a higher prior-
ity.
l For Alarms, Reports, and Trends Server redundancy, clients connect to either the
Alarms, Reports, or Trends primary server or standby server. On startup, clients try
to establish a connection with the primary server. If a connection with the primary
server cannot be established, they will try to establish a connection with the standby
server. If the primary server becomes available, any clients connected to the standby
server remain connected to the standby server unless the primary has a higher prior-
ity. If the standby server becomes inoperative the client will revert to the primary
server. The priority is set using the connectivity parameters described below.

Connectivity Parameters

256
 Chapter: 14 Building Redundancy Into Your System

Two Citect.ini parameters determine how a client will behave if it is unable to establish
or maintain a connection with a primary Alarms, Reports or Trends server. Each server
type has access to these parameters [Type.ClusterName.ServerName]Priority and
[Type.ClusterName.ServerName]DisableConnection, where Type is the relevant server
type (Report, Trend or Alarm). The default setting for these parameters provides behav-
ior as described above, in that a client redirected to a standby server will retain a con-
nection to that server, providing that it is operable, even when the primary server is
restored. This is also the behavior that will occur if you do not add these parameters for
a given server type.
Using the parameters

When a primary server has the parameters [Type.ClusterName.ServerName]Priority=1

and [Type.ClusterName.ServerName]DisableConnection = 0 and a control client cannot
establish a connection to the primary server, the control clients will switch to the
standby server with its parameters set at [Type.ClusterName.ServerName]Priority=0 and
[Type.ClusterName.ServerName]DisableConnection = 0. When the primary server is
restored, the control clients will switch back to the primary server since it has a higher
priority.
If both servers have their [Type.ClusterName.ServerName]Priority set to the same value
and [Type.ClusterName.ServerName]DisableConnection = 0 then the client will switch to
the standby server and will remain connected to the standby server even when the pri-
mary server has been restored. This is the default behavior. The connectivity parameters
can be set at the system level using the Parameters form of the project, or specifically for
each client in the client local Citect.ini file.
If either server has its [Type.ClusterName.ServerName]DisableConnection = 1, then any
client connected to the other server with [Type.Clu-
sterName.ServerName]DisableConnection = 0 will establish a non-redundant connection
to that other server. If that connection becomes inoperative, the client will not be redi-
rected and will have no connection until the server is restored.
For specific detail on setting these parameters see:

[Report.ClusterName.ServerName]Priority
[Alarm.ClusterName.ServerName]Priority
[Trend.ClusterName.ServerName]Priority
[Report.ClusterName.ServerName]DisableConnection
[Alarm.ClusterName.ServerName]DisableConnection
[Trend.ClusterName.ServerName]DisableConnection

in the Parameters online help

257
Chapter: 14 Building Redundancy Into Your System

See Also
Alarm Server redundancy
Reports Server redundancy
Trends Server redundancy
File server redundancy
FTP server redundancy

Alarms server redundancy

It is possible to configure two Alarm Servers in a project. That is, a primary Alarm
Server and a standby Alarm Server. With two Alarm Servers, you have improved (mir-
rored) redundancy on your system.
When both Alarm Servers are in operation, alarms are processed on both servers in par-
allel, and are logged by the primary Alarm Server. If the Primary Alarm Server becomes
inoperative, the Standby Alarm Server starts to log alarms to devices.
When one alarm server task is shutdown the redundant alarm server task continues to
process the alarm states. When the alarm server task is restarted, it tries to establish a
connection to an alternate Alarm Server. If it can connect, it transfers the dynamic alarm
data from the running Alarm Server to the other Alarm Server (this data includes sum-
mary data and the current alarm states). If a connection to an alternate Alarm Server can-
not be established, the Alarm Server opens the save file (defined with the
[Alarm]SavePrimary parameter) and restores the data from the file. If two save files exist,
one from the primary Alarm Server and one from the standby Alarm Server, Citect-
SCADA uses the save file with the later date, or in other words, the newest save file. If
no save file is configured, the Alarm Server cannot obtain the initial status (state) of the
alarms and no summary information will be available. If this is the case, the Alarm
Server starts processing the alarms, and then acknowledges the new alarms.
While both Alarm Servers are active, they will both read data from the I/O Server and
process the alarms. The on/off status of each alarm is not passed between the two
servers. When operators perform functions on alarms (for example, acknowledge, dis-
able, enable, add comments, etc.), this information is passed between the two Alarm
Servers (if an operator acknowledges an alarm on one server, that server tells the other
server to acknowledge the same alarm).
Under normal operation, it is recommended to design your system to have an unin-
terrupted link between the alarm server tasks. This allows each server task to be able to
communicate operational state changes (such as alarm acknowledgment) to the redun-
dant peer. For alarm server task communication, network design that includes redun-
dancy at the network layer helps the alarm server tasks continue operation even during
a single network disconnection.

258
 Chapter: 14 Building Redundancy Into Your System

Alarm redundancy is designed to allow the user to resolve the arbitration of an alarm
list that is different between redundant alarm server tasks. If a mismatch occurs, the user
is able to select which alarm server task is incomplete and restart that server process.
During the restart, the state of the alarm server task will match the online peer.
See Also
Reports Server Redundancy

Reports server redundancy

It is possible to configure two Reports Servers in a project. That is, a primary Reports
Server and a standby Reports Server.
When both Reports Servers are in operation, the scheduled reports only run on the pri-
mary Reports Server. If the primary Reports Server becomes inoperative, the scheduled
reports run on the standby Reports Server (you can also configure the standby Reports
Server so that is also runs the scheduled reports in parallel with the primary Reports
Server). Please be aware that no report data is transferred between the primary and
standby Reports Servers (CitectSCADA does not synchronize the report data because
reports can write their data to any type of device.
See Also
Trends Server Redundancy

Trends server redundancy

It is possible to configure two Trends Servers in a project. That is, a primary Trends
Server and a standby Trends Server.
When both Trends Servers are in operation, trends are processed on both servers in par-
allel, and written to disk (each server needs to write to its own disk or its own private
area on the file server).
When a Trends Server starts up, it tries to establish a connection to the other Trends
Server. If it can establish a connection, it will transfer the trend data from the last time it
was shutdown until the current time (this minimizes the chance that trend data will be
lost).
See Also
File Server Redundancy

259
Chapter: 14 Building Redundancy Into Your System

File server redundancy

CitectSCADA allows for redundancy of the File Server. The [CtEdit]Backup parameter
specifies a backup project path. If CitectSCADA cannot find a file in the Run directory
(i.e. as specified by the [CtEdit]Run parameter), it will look in the backup path. If the file
is found in the backup path, CitectSCADA will assume that the run path has become
unavailable for some reason (for example, the file server has become inoperative). It will
then look for relevant files in the backup before changing over. When CitectSCADA
changes over to the backup path, it will call event number 11 and generate the hardware
error: File server failed, to Standby.
File Server redundancy will only operate correctly if the redirector (or shell) on the com-
puter can respond appropriately if the File Server becomes inoperative. The Novell Net-
ware shell cannot do this and will cause Windows itself to become inoperative or report
what it views as serious Network Errors - if the file server becomes inoperative. Micro-
soft LAN Manager-based networks and peer-to-peer networks correctly handle instances
when the File Server becomes inoperative. Therefore, CitectSCADA File Server redun-
dancy will operate correctly with these networks.

Note: Only CitectSCADA switches to a backup path. Any other applications that are
using files on the File Server will become inoperative when the File Server becomes
inoperative. This may cause the computer to wait for long periods for the File Server
(or to itself become inoperative). This includes Windows itself, so install Windows
on a local drive.

To enable File Server redundancy, set the [CTEDIT]Backup parameter to a backup data-
base path. For example, if your primary path is F:\CITECT\USER\DB, set the backup
path to another File Server or a local drive, such as C:\CITECT\USER\DB.
You will want to verify that the project in the Backup path is the same as the one in the
Run directory - each time you compile the project in the run directory copy it into the
backup directory.

UNINTENDED EQUIPMENT OPERATION

Before placing your CitectSCADA system into service, confirm that the Standby File Server has
an identical copy of the current project, and that the [CTEDIT]Backup parameter is correctly
set.

Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

260
 Chapter: 14 Building Redundancy Into Your System

See Also
FTP Server Redundancy
[CtEdit]Copy
[CtEdit]Run

FTP server redundancy

CitectSCADA supports FTP Server redundancy. If the primary FTP Server goes down,
CitectSCADA will attempt to connect to the FTP Server on the standby machine. This
occurs independently of I/O Server redundancy, so the two FTP Servers need to have the
same passwords and the same directory structure.
FTP Server redundancy is configured by setting parameters in the [CLIENT] and [DNS]
sections of the Primary FTP Server's Citect.ini file. These parameters are downloaded by
the Internet Display Client (IDC) to its own Citect.ini file if the Primary FTP Server
becomes inoperative, provided the [INTERNET]Redundancy parameter has not been set
to 0 (zero). The IDC then uses the downloaded redundancy information to connect to the
standby FTP Server.

Note: Standby FTP Servers need not be Internet Servers. The Standby FTP Server can
be any server using TCP/IP that the IDC can connect to, provided there are IDC
licenses present in the network.

See Also
Redundancy of Standalone Systems

Redundancy of Standalone Systems

If you are using CitectSCADA as a standalone system, in the single process model, you
can still achieve redundancy by implementing your standby systems on another CPU,
provided you have a multi-CPU system. You may also wish to implement this for load-
balancing purposes.
See Also
Configuring Your System

261
Chapter: 14 Building Redundancy Into Your System

262
Chapter: 15 Communicating with I/O Devices
CitectSCADA can communicate with any control or monitoring I/O Device that has a
communication port or data exchange interface, including PLCs (programmable logic
controllers), loop controllers, bar code readers, scientific analyzers, remote terminal units
(RTUs), and distributed control systems (DCS).
Typical CitectSCADA communications consists of four key parts:
1. A CitectSCADA I/O Server;
2. A target I/O Device;
3. A physical means for transporting messages between them (transport);
4. The messages exchanged between them (protocol).

These components work in unison to expose the inputs and outputs of an I/O Device to
a CitectSCADA system.
l Inputs to the I/O Device provide information about your plant, such as the speed of a
machine, status of a conveyor, or the temperature of an oven.
l Outputs from the I/O Device usually initiate tasks that control the operation of your
plant, such as starting electric motors, varying their speed, or switching valves and
indication lamps.

263
Chapter: 15 Communicating with I/O Devices

The transport medium does not need to be a direct cable as shown in the diagram; it can
be any means of carrying the message – such as a high-speed wireless link or an FDDI
network. Similarly, the protocol-specific message could be a simple ASCII message or a
complex object-based message such as DNP 3. Engineers are free to assemble different
combinations of I/O Devices, transports, and protocols.
See Also
The Role of the I/O Server

The Role of the I/O Server

The CitectSCADA computer that directly connects to an I/O Device is an I/O Server. I/O
Servers are responsible for servicing the read, write and subscription requests from
clients. A project can have many I/O Servers, with each cluster able to include multiple
I/O Servers.
An I/O Server keeps up-to-date information on its connected I/O Devices by regularly
retrieving data from each and storing it in a cache (I/O Device data cache). Whenever a
CitectSCADA client requires data from an I/O Device, it will use the information stored
in the I/O Server cache. Clients do not retrieve data directly from an I/O Device.
An I/O Server will read the necessary data from the I/O Device to execute a requested
Cicode task or process. For example, when you schedule a report, CitectSCADA reads the
I/O Device data that the report might need before the first line of the report starts run-
ning.
CitectSCADA performs writes to the I/O Device asynchronously, allowing other oper-
ations to continue while a write is taking place.
See Also
The Role of the I/O Device

The Role of the I/O Device

CitectSCADA is predominantly a supervisory system. It is the I/O Devices that directly
monitor and control automation equipment. In most I/O Devices (such as PLCs) a pro-
gram stored in the I/O Device controls the outputs. The logic (control strategy) of this
stored program and the status of the inputs determine the value of each output.
The value of each input and output is stored in a separate memory register in the I/O
Device. Each memory register is referenced by its address.
By reading and writing to memory registers in I/O Devices, CitectSCADA collects data
from your plant or factory for monitoring and analysis, and provides high-level (super-
visory) control of your equipment and processes.

264
 Chapter: 15 Communicating with I/O Devices

You usually don't need to read (or write) to every register in the I/O Device: Citect-
SCADA lets you specify which inputs and outputs you want to monitor or control. After
defining these register addresses, you can use them for system control, operator displays,
trend analysis, data logging and alarm indication.
The choice of I/O Device is typically not open to the person engineering the com-
munications system. In most cases, the I/O Device hardware is purchased in advance of
the integration effort, or it is legacy equipment. However, if you have the luxury of
influencing the choice of I/O Devices, communications capability is recommended to be
one of the factors you consider.

Note: I/O devices such as programmable logic controllers (PLCs) usually have an
internal program that controls the low-level processes within your plant. A PLC pro-
gram continually scans the input registers of the PLC, and sets the output registers to
values determined by the PLC program logic. While CitectSCADA can replace any
PLC program, this is not recommended. PLCs are designed for high-speed response
(typically 1 to 100 ms) and replacing this functionality with CitectSCADA could neg-
atively affect your control system’s performance. Only use CitectSCADA to com-
plement your PLC program (that is, for high level control and system monitoring).

UNINTENDED EQUIPMENT OPERATION

Do not use CitectSCADA or other SCADA software as a replacement for PLC-based control pro-
grams. SCADA software is not designed for direct, high-speed system control.

Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

See Also
The Role of the Transport Medium

The Role of the Transport Medium

The term ‘transport’ refers to both the physical communications medium and the low-
level logic necessary to drive it. As far as CitectSCADA is concerned, it simply defines
how to package a message, how to send it, and where to send it.
The available transport options are usually governed by the kind of ports available on
the target I/O Device. However, they are also influenced by the geography of the auto-
mation system, specific domain requirements (such as safety, performance, redundancy),
and the amount of money the owners are willing to invest.
The three main categories of available transport are:

265
Chapter: 15 Communicating with I/O Devices

1. Simple serial – such as RS-232, RS-422, RS-485;

2. Ethernet – the dominant frame-based inter-network protocol; or
3. Proprietary – using intermediary PC-communications hardware or software (such as
OPC servers).
Of these, Ethernet is by far the transport technology of choice.
Fortunately, by using the concepts of packet encapsulation and intelligent gate-
way/routing devices, you are able to mix different transport layers. For example, you
could use a serial cable from CitectSCADA to a modem, a PSTN line from the modem to
another modem, then a serial cable to an Ethernet gateway, and Ethernet to the I/O
Device.

Note: Modems are treated as a special case in CitectSCADA since they are rec-
ognized as logical devices by Windows. Refer to the specific online help on setting
up modems.

CitectSCADA uses the ‘COMx’ driver to implement simple serial transports. Similarly,
the ‘TCPIP’ driver implements the Ethernet transport. These are commonly used trans-
port drivers, and both have a range of tuneable options and settings. Each proprietary
board has its own specific transport driver – which is typically integrated with the pro-
tocol driver.
See Also
The Role of the Protocol
Working With Device Drivers

The Role of the Protocol

I/O Devices support at least one protocol – which governs the kind of commands and
data you can exchange with the device. They vary significantly in functionality and in
complexity. However, because CitectSCADA supplies the protocol drivers, the engineer
does not need to know the details of the protocol.
Most modern devices support two or more protocols. This gives engineers flexibility in
designing appropriate communications architectures. Sometimes there is a simple pro-
tocol that provides basic access to device functionality, and a more comprehensive and
complex protocol. Occasionally the protocol is closely linked to the transport layer used
– particularly in the case of proprietary protocols and communications hardware.
Which protocol you choose depends on:
l The protocols supported by the I/O Device;
l The kind of data you need to access;

266
 Chapter: 15 Communicating with I/O Devices

l The commands you need to execute; and

l Any constraints stemming from the transport chosen.
In many cases, a specific card or module is necessary in the I/O Device to support addi-
tional protocols.
Using Industry Standard Protocols
The automation and associated industries have developed a number of standardized
protocols for communicating with I/O Devices. Because these protocols are open and
developed collaboratively, they allow a greater degree of connectivity and longevity than
other options.
The following list shows some of the prominent communication standards used in the
automation industry that are supported by CitectSCADA:
l ASCII – for simple serial communications;
l Modbus – a widely used simple serial protocol for automation;
l DNP 3.0 – a protocol for distributed networks such as RTUs;
l BACNet – specifically for the building automation control industry;
l OPC – a technology for sharing automation data at the PC level;
l IEC870-5 – communication profile for sending basic telecontrol messages;
l EIB – European installation bus;
l Profibus – field bus communications protocols for automation;
l SNMP – widely used protocol for network devices.
As CitectSCADA allows you to choose whatever protocol you need for the situation, you
can choose to use these protocols where supported by your I/O Device.
This is particularly useful when you have a mix of I/O Device brands but you want to
simplify and use one common protocol.
See Also
Communication Configuration
Working With Device Drivers

Communication Configuration
CitectSCADA uses a logical and structured communications configuration, that maps
closely to the elements shown in the diagram below.
It requires the engineer to:
1. Define an I/O Server in the I/O Server form;
2. Define the transport type in the Boards form (COMx, TCPIP, PROFI…);

267
Chapter: 15 Communicating with I/O Devices

3. Define the port to communicate out of in the Ports form.

4. Define the protocol to use (MODBUS, DNP, ASCII…).

Note: Each of these steps is simplified in order to illustrate the mapping of necessary
elements to the basic communication architecture. In reality, some other tasks need to
be performed to setup communications.

The following diagram shows how the elements in the configuration environment map
to the software components in the runtime system.
Although this is not essential to know, it does help understand how drivers fit into the
system.

268
 Chapter: 15 Communicating with I/O Devices

Note: This example omits many logical runtime components for clarity (such as
clients). In addition, the runtime components shown are not visible to the user at run-
time. However, driver information can be accessed at runtime via the CitectSCADA
Kernel.

269
Chapter: 15 Communicating with I/O Devices

A good place to start when setting up simple communications is with the Express I/O
Device Setup wizard. Once you understand how the setup works, you can manually con-
figure arrangements that are more complex. Much of the functionality of the protocols
and transports can be modified using the driver options and parameters. Each driver
has its own specific section in the online help that will guide you through configuration
options.
See Also
Setting up communications
Working With Device Drivers

Retrieving time-stamped data from field devices

With the release of version 7.20, CitectSCADA supports the retrieval of time-stamped
data directly from field devices. This capability is enabled by the Driver Runtime Inter-
face (DRI), a component that is used by the following device drivers:
l OPC
l OFSOPC
l SISCOOPC
l DNPR

Note: Check with Technical Support if new drivers are available that support the
DRI.

The DRI allows a driver to push time-stamped data from field devices into a Citect-
SCADA system. This means time-stamped digital alarms, time-stamped analog alarms
and event-based trends can be updated directly from devices.
No configuration is necessary, as when these drivers start up they scan the system for
time-stamped digital alarms, time-stamped analog alarms and event-based trends. If the
driver receives updated information for any detected tags, it will pass it directly on. Reg-
ular I/O server polling is no longer used.
This mechanism can work in tandem with the tag extension feature (also introduced in
version 7.20) to enable access to field-generated timestamp and quality tag values (see
Tag Extensions).

Note: Prior to version 7.20, time-stamped data was manually pushed into Citect-
SCADA using the Cicode functions AlarmNotifyVarChange and TrnSetTable. If you
are upgrading a project to a version 7.20 system with a driver that uses the new DRI
push mechanism, you will no longer need to use these functions.

270
 Chapter: 15 Communicating with I/O Devices

IO Server parameters
Events pushed from a DRI-supported driver can be buffered on an I/O server while an
alarm or trend server is offline. The way this mechanism operates can be configured via
the following parameters:
l [IOServer]EventsQueued
l [IOServer]EventsDropped
l [IOServer]MaxTimeInQueueMs
For more information, see IO Server Parameters.
See Also
Communications Configuration
Working With Device Drivers

Setting Up Communications
Setting up communications between a device and a CitectSCADA I/O Server typically
involves a process that includes the following steps:
1. Choose the Method of Communication
By examining the capabilities of your I/O Devices and control systems networks,
select an appropriate communication mechanism. This mechanism will usually
imply the transport and protocol drivers that needs to be con figured in Citect-
SCADA.
See The Role of the Transport Medium and The Role of the Protocol for more infor-
mation.
2. Prepare the Device
Confirm that your device meets the hardware and software requirements needed to
communicate with CitectSCADA. The Driver Reference Help provides hardware
setup information specific to each supported device.
3. Prepare the I/O Server for Communication
This involves preparing the I/O Server to communicate with a device. This includes
setting up a COM port, a serial board, or a proprietary board in an I/O Server.
4. Create a Test Project
Before configuring your CitectSCADA project, confirm communications between
CitectSCADA and your system devices. Creating a test project allows you to test the
communication path in isolation, and verifies that CitectSCADA can bring your
devices online.
5. Configure communications using the Communications Express Wizard
The Express Communications Wizard provides default values and a setup tailored to
the communications requirements of a selected I/O Device.

271
Chapter: 15 Communicating with I/O Devices

OR
Configure Communications Manually
You can manually configure the communications to your I/O Device using the
Boards, Ports and I/O Devices forms in the CitectSCADA Project Editor. This often
gives more flexibility, but requires a more detailed knowledge of the driver settings
and parameters.
Once you have performed these steps, you are ready to run and verify your com-
munications.
See Also
Customizing a Project Using Citect.ini Parameters
Using a Disk I/O Device

Preparing a Device
You need to verify your system meets the hardware and software requirements needed
to establish communication between a device and CitectSCADA.
This may include a variety of possibilities, including:
l the installation of a proprietary communications card
l the establishment of a device server
l the installation of configuration software, etc.
The Driver Reference Help provides the hardware and software requirements for each
device, and includes any additional information you need to know about setting up spe-
cific devices. To access this help, select Driver Help from the Help menu in Citect
Explorer and Project Editor.
See also
Preparing the I/O Server for communication

Preparing the I/O Server for Communication

You need to verify a CitectSCADA I/O Server is enabled to support the necessary com-
munications method. This involves installing and configuring any communications
hardware and/or software necessary for communications. Common scenarios are:
l Using a COM port
l Using a Serial board
l Using an Ethernet card
l Using a Proprietary board/intermediary software

272
 Chapter: 15 Communicating with I/O Devices

Using a COM port

The simplest CitectSCADA systems use a single computer connected to the I/O Device(s).
You can connect an I/O Device directly to a communications port with a standard RS-
232 communications cable.

How to set up CitectSCADA to use your computer's COM port:

1. Verify that the Boards configuration has COMx as theType, and the Address set to
0. The I/O Port, Interruptand Special Opt can be left blank.
2. Enter the Port Number in the Ports configuration. The COM port number will
usually be either 1 or 2, and is set in the Ports section of the Control Panel. Use the
Special Opt field to modify the behaviour of the COMx driver. (See COMx driver spe-
cial options reference for more information).

Note: You only need to define the COMx board once. You can then add several ports
that use the same CitectSCADA board. For example, a COM port and two serial
boards could be defined as one COMx board in CitectSCADA, with multiple ports.

See Also
Debugging a COMx Driver
Using a Serial Board

Using a Serial Board

The communications port on the computer is not designed for high-speed com-
munications and reduces system performance. Instead, install a high-speed serial board
(such as a Digiboard). High-speed serial boards have several ports (usually 4, 8, or 16) to
let you connect several I/O Devices to your CitectSCADA system.

273
Chapter: 15 Communicating with I/O Devices

You can use identical I/O Devices or I/O Devices supplied by different manufacturers;
CitectSCADA supports most popular I/O Devices. You can connect any number of I/O
Devices; the only limitation is the size of your computer. High-speed serial boards are
available for RS-232, RS-422, or RS-485 communication.
If you have several I/O Devices from the same manufacturer and these I/O Devices sup-
port multi-drop communication, you can connect them to an RS-422 or RS-485 high-
speed serial board installed in your computer. (The RS-232 standard does not support
multi-drop communication.)

Not every high-speed serial board supports RS-422. You can use an RS-232/RS-422 or
RS-232/RS-485 converter to achieve the same arrangement.

Note: Using a converter can introduce handshaking/timing considerations.

To set up CitectSCADA to use a serial board:

1. Install the board in your computer and set it up under Windows as per the accom-
panying instructions. Use the latest driver from the board manufacturer.
2. Make sure that the boards configuration has COMx as the Type, and the Address set
to 0. The I/O Port, Interrupt, and Special Opt can be left blank.
3. Enter the Port Number in the Ports configuration. The COM port number is usually
greater than 2 and set in the Ports section of the Control Panel. Use the Special

274
 Chapter: 15 Communicating with I/O Devices

Options field to modify the behavior of the COMx driver. (See COMx driver special
options reference for more information).
Notes
l If using your computer's COM port, you don't need to install additional software.
l You only need to define the COMx board once. You can then add several ports that
use the same CitectSCADA board. For example, a COM port and two serial boards
could be defined as one COMx board in CitectSCADA, with multiple ports.
See Also
Using Proprietary Boards

COMx driver special options reference

Special Options (in the Ports form) are space separated and start with the dash character
(-) immediately followed by the option characters. Only a small percentage of users will
need to use the following options:
l cATS0=1: Send the string 'ATS0=1<CR>' on startup to allow the modem to detect the
baud rate the port is running at. Abandon transmit if DCD is low. Wait for incoming
call to raise DCD.
l d: Data will be transmitted only when DSR is high
l di: Received data is ignored when DSR is low.
l dMS: When transmitting a message the driver will wait up to 2000 ms for DSR to go
high, then wait another MS milliseconds before transmitting.
l -e: Provides access to the output signal lines. The format is "~EIAWXYZ" where
WXYZ represents one of the following options:
S Simulate XOFF received
S Simulate XON received
RT Set RTS high
RT Set RTS low
D Set DTR high
D Set DTR low
B Set the device break line
B Clear the device break line
Example: "~EIADTR1" sets DTR high
l -h: Data will be transmitted only when CTS is high.
l -hMS: When transmitting a message the driver will wait up to 2000 ms for CTS to go
high, then wait another MS milliseconds before transmitting.
l -i: The string sent whenever the port is initialized. The tilde (~) and '\M' characters
represent special instructions:
l ~: Delay for 500 milliseconds

l \M: Send carriage return

275
Chapter: 15 Communicating with I/O Devices

Examples:
~Fred: Wait 500 milliseconds and then send 'Fred'
Fred\MMary: Send 'Fred', a carriage return, and then 'Mary'
Note: This option is not available for dialable devices (i.e. when the port number
is -1).
l -nt: With some serial interfaces, line interruptions can cause the COMx read thread to
shutdown. If this happens, the driver does not recover after the interruption. How-
ever, with the -nt (no terminate) option set, the thread is not shutdown, allowing the
system to recover when the interruption is rectified.
l -nts: If errors occur when the COMx driver is starting up, it will not terminate, but
will continue attempts to open the COMx port.
l -r: Driver will raise DTR only when transmitting.
l -ri: DTR is raised when there is enough room in the input buffer to receive incoming
characters and drop DTR when there is not enough room in the input buffer.
l -rPRE,POST: When transmitting a message the driver will raise DTR for PRE mil-
liseconds, transmit message, wait for POST milliseconds then drop DTR.
l -sc: Activates software flow control using XON and XOFF
XonLim: A number in bytes. This represents the level reached in the input buffer before the XON character is
sent (30 bytes)
. XoffLim: The maximum number of bytes accepted in the input buffer before the XOFF character is sent. This is
calculated by subtracting (in bytes) 100 from the size of the input buffer

l -t: Driver will raise RTS only when transmitting.

l -ti: RTS is raised when there is enough room in the input buffer to receive incoming
characters and drop RTS when there is not enough room in the input buffer.
l -to: RTS is raised only when there are characters to transmit.
l -tPRE,POST: When transmitting a message the driver will raise RTS for PRE mil-
liseconds, transmit message, wait for POST milliseconds then drop RTS..
See Also
Using a Com Port
Debugging a COMx Driver
Using a Serial Board

Using an Ethernet Card

Ethernet is one of the most popular methods of communicating with a number of I/O
Devices at high speed. It is certainly one of the easiest to configure. You can typically
connect to Ethernet capable I/O Devices using a standard Ethernet card, or integrated Eth-
ernet port.

276
 Chapter: 15 Communicating with I/O Devices

To set up CitectSCADA to use your computer's Ethernet card:

1. Make sure that your Ethernet card is installed correctly and working under Win-
dows.
2. Make sure that the Boards configuration has TCP/IP as the Type, and the Address
set to 0. The I/O Port, Interruptand Special Opt can be left blank.
3. In the Ports form, use the Special Opt field to enter the destination IP address using
the following format:
-Ia -Pn -T
where:
a = the destination IP address in standard Internet dot format. (For example
192.9.2.60)
n = the destination Port number. Often one physical port has several virtual ports,
used for different purposes. Use this option only if you want to override the default of
2222.
T = forces the driver to use TCP (the default), rather than UDP (-U).
(See TCP/IP driver special options reference for more information)
Leave other fields blank. You can now define your I/O Device units.

Note: You only need to define the TCP/IP board once. You can then add several ports
that use the same CitectSCADA board.

See Also
Using a Serial Board

TCP/IP driver special options reference

Special Options (in the Ports form) are space separated and start with the dash character
(-) immediately followed by the option characters. Use the following special options for
TCP/IP:
l A: Allows the TCPIP driver to be used from Cicode.

277
Chapter: 15 Communicating with I/O Devices

l -Ia.b.c.d: defines remote IP address to connect to.

l -FC: Allows for a fake connection. This creates a pretend connection (no actual IP con-
nection is made). Its intended use is when a driver wants to support a dummy con-
nection but not talk to a device, or have a virtual unit. A virtual unit would allow
access to driver addresses which do not need to talk to a device.
l -K: sets socket SO_KEEPALIVE flag.
l -LIa.b.c.d: defines local IP address.
l -LPn: defines local PORT.
l -Ma.b.c.d: defines multicast IP address.
This option can be set using the [TCPIP]PortName.MulticastAddress parameter. See
Debugging a TCP/IP driver.
l -Pn: defines remote PORT to connect to.
l -PXn: defines an extra port to listen to only in UDP mode.
l -RC: Activates the reconnection retries on reception of FD_CLOSE event. FD_CLOSE
is only received if the Keepalive option is activated. -RC can resolve issues where the
TCP/IP driver is notified of the connection close. For a more comprehensive handling,
the -k option is needed. Retries can also be activated with the following high-level
driver call:
COMSetParam((SHORT)ChannelNumber, (UCHAR*)("DO_RECONNECT"), NULL);

l -T: sets this port for TCP (stream) operation.

l -U: sets this port for UDP (datagram) operation
where:
a.b.c.d = standard IP address in dot notation using decimal numbers 0- 255. (Do not use
a leading 0 when adding an IP address).
n = decimal value for the port ID for the necessary service.
See Also
Using an Ethernet Card
Using a Serial Board

Using a Proprietary Boards and/or Intermediary Software

With some brands of I/O Devices you can install a proprietary interface board in your
computer, or intermediary software. This PLC interface board/software is supplied by the
PLC manufacturer; you can connect it to a single PLC or a PLC network.

278
 Chapter: 15 Communicating with I/O Devices

Note: With some PLCs, a high-speed serial board provides better performance than a
PLC interface board when the system is connected to more than one PLC.

You can mix both PLC interface boards and high-speed serial boards in a single com-
puter. You can, for example, connect a PLC network to a PLC interface board, and
individual I/O Devices to a high-speed serial board.

There are many possible hardware arrangements for a CitectSCADA application. Citect-
SCADA is a flexible system and imposes few restraints on the type (or manufacturer) of
I/O Devices that you can use, or on the way you connect them to the computer.
To set up CitectSCADA to use a proprietary board/software:
If you are using a proprietary board/software (that is, supplied by the PLC man-
ufacturer):
1. Install the board/software in your computer and set it up under Windows as per the
accompanying instructions. Use the latest driver from the manufacturer.
2. If possible, run diagnostics on the board before configuring CitectSCADA to check
that the board works correctly.
3. Check that the I/O Port and Interrupt settings are correct.
4. Configure the Boards and Ports as instructed by the PLC-specific help.

Creating a communications test project

To verify that CitectSCADA can bring your I/O Devices online, it is recommended you
create a test project.

279
Chapter: 15 Communicating with I/O Devices

The Test Project needs to be as simple as possible. For example, if your system will even-
tually be communicating through a COM port, a KTX card, an SA85 card, and via
TCP/IP do not try and make this work on your first try. Make the Test Project with 1 ele-
ment at a time.
First add and test the COM port. When that works, make a new test project for the KTX
card, then make a new test project for the SA85 card, and finally one for the TCP/IP.
Once you are happy that each individual element works properly, start to add them
together.
While checking that you have only the absolute minimum information in the project to
enable communications, verify that there are no duplicated records.
A good way to do this is to open a form and then check the Record Number shown on
the bottom left of the form. Check that it is on Record 1, and then click the button in the
scroll bar on the right hand side of the form and drag it down. When you get to the bot-
tom of the scroll bar, let the button go. If it pops back up to the top of the form and the
record numbers stays at 1 then you have only 1 record.
It is necessary to drag the scroll bar as the forms are indexed on the I/O Server name.
Quite often there will be 'orphaned' records from a previous I/O Server name still in the
database files. If you find any extra records, delete them and then pack the project. Dupli-
cate or orphaned records in the communications database can negatively impact com-
munications performance.
See Also
Running Your Test Project

Running Your Test Project

Before running your test project, verify that the Kernel is enabled on CitectSCADA
startup so that you can follow the startup procedures step by step.
To do this, edit your citect.ini file to contain the following:
[DEBUG]
Kernel=1
This will show the Kernel on startup of CitectSCADA.
Next, run the Computer Setup Wizard. Verify that the computer is defined as a stand-
alone CitectSCADA system and configured to run your test project.
Start the project running. When the kernel appears, double-click the title bar in the Main
window, then double-click the title bar of the kernel. Doing this in order is important, as
it will maximize the Main window, then Maximize the whole kernel. If you don't do this
then you will not see what is happening as the information in the Kernel cannot be

280
 Chapter: 15 Communicating with I/O Devices

scrolled, and once it is off the screen it is gone. This might require a bit of practice as the
startup procedure might only take 1-2 seconds or less on a fast machine.
Once you have the project running (and assuming that everything worked) the last line
in the Main window in the Kernel will tell you that your I/O Devices are online. Do not
confuse this with the message telling you that your Port channels are online. Citect-
SCADA will first report that it can communicate through the port you have setup, then
report that it can communicate with the I/O Device.
See Also

When Your Test Project Does Not Compile

When Your Test Project Does Not Communicate

Check everything and run it again. Depending on the type of board driver you are using
there are different methods for debugging them. However, most of them are basically the
same. Add one item at a time and test.
See Also

Troubleshooting Device Communications

Using the Communications Express Wizard

You use the Express Communications Wizard to set up communications with your I/O
Devices.
Based on your selections, the Express Communications Wizard provides default values
and a setup tailored to your I/O Device communications requirements.
To access the Communications Express Wizard:

1. Open the Project Editor.

2. Choose Communication | Express Wizard or open Citect Explorer.
3. Double-click the Express I/O Device Setup icon in the Communications folder of the
current project.
4. Complete the Wizard.

Note: Each I/O Device/protocol combination requires a unique setup for the boards,
ports, and I/O Devices forms. See the specific Help for each device.

See Also
Express Communications Wizard - introduction

281
Chapter: 15 Communicating with I/O Devices

Express Communications Wizard - introduction

You will be asked to select an I/O Server, choose a name, and indicate the type of I/O
Device (External, Memory, Disk). From the list of available manufacturers you choose
the manufacturer, model and communications method for the I/O Device. If you are con-
necting external devices or using a proprietary board in your computer you may be
requested to nominate addresses and communications port.
After completing your setup, the Summary Page summarizes the configuration of your
I/O Device and/or internal boards. Click Finish to save the listed configuration, or click
Back to change a previous selection.
See Also
Express Communications Wizard - Server selection

Express Communications Wizard - Server selection

Select an existing I/O Servers as defined in the current Project, or create a new I/O Server.

When you create a new I/O Server, CitectSCADA automatically suggests the name
IOServer1. You can enter a different name if you want. The name you specify needs to
be 16 characters or less and use alphanumeric characters (A-Z, a-z, 0-9). You can also
use the underscore character ( _ ).

Note: If you add a new I/O server, you will need to run the Computer Setup Wizard
on the designated computer before you attempt to run the project. This is necessary
to enable the computer to function as an I/O Server.

See Also
Express Communications Wizard - Device selection

Express Communications Wizard - Device selection

Enter the name of the new I/O Device that you want to create, or accept the name IODev
which CitectSCADA automatically suggests.
See Also
Express Communications Wizard - I/O Device type

Express Communications Wizard - I/O Device type

Select the type of I/O Device. You may choose from the following options:

282
 Chapter: 15 Communicating with I/O Devices

l External I/O Device

l Persisted Memory I/O Device
l Disk I/O Device

Note: Using a Persisted Memory I/O Device is recommended as an alternative to

using a Disk I/O Device, as full synchronization is supported if a server becomes
unavailable for a period of time. See Persisted I/O Memory Mode for more infor-
mation.

See Also
Express Communications Wizard - I/O Device communications selection

Express Communications Wizard - I/O Device communications selection

From the list of available manufacturers, select the manufacturer, model, and com-
munications method specific to the I/O Device.
If a memory or disk I/O Device has been selected, the CitectSCADA Generic Protocol is
included at the top of the tree.
See Also
Express Communications Wizard - TCP/IP address

Express Communications Wizard - TCP/IP address

Enter the IP address for the I/O Device, in standard Internet dot format (for example,
192.9.2.60). This address is set on (or specified by) your I/O Device.
The Port number and Protocol (TCP or UDP) fields have been set to the default values
for the I/O Device. change these fields only if necessary.
For details about addressing your specific I/O Device, click Driver Address Help to
browse driver-specific information for your I/O Device.
See Also
Express Communications Wizard - I/O Device address

Express Communications Wizard - I/O Device address

Enter the address for the I/O Device. What you enter in this field is determined by the
type of I/O Device (and protocol) used, as each has a different addressing strategy.
For details about addressing your specific I/O Device, click Driver Address Help to
browse driver-specific information for your I/O Device.

283
Chapter: 15 Communicating with I/O Devices

See Also
Express Communications Wizard - I/O Device connection schedule

Express Communications Wizard - I/O Device connection schedule

This form allows you to define the details of the communications schedule for your I/O
Device and indicate that your I/O Device is remote by checking the PSTN box.

Options Description

Connect I/O Device to Check this box to indicate that the I/O Device is a dial-up
PSTN I/O Device (connected to a PSTN - Public Switched Tel-
ephone Network).

Note: Even if your I/O Device is not connected via a

modem, you need to still check this box to schedule com-
munications (but leave the Phone number to dial and Caller
ID fields blank).

Once you have completed your I/O Device setup using this
Wizard, you need to go to the Ports form and change the
Port number to the actual number of the COM port.

You can choose to define the communication period in

terms of months, weeks, days, or hours, minutes, and
seconds. Alternatively, you can choose to communicate
only at startup (persistent connection). Click a radio but-
ton to make your selection, then enter the start time and
period as described below.

Synchronize at The I/O Server will attempt to communicate with the I/O
Device at this time, and then at intervals as defined below.
This time is merely a marker for CitectSCADA. If you run
up your project after this time, the I/O Server won't wait
until the next day to begin communicating. It will operate
as if your project had been running since before the start
time.

Repeat Every The time between successive communication attempts.

(See Examples below.)

Phone number to dial The telephone number that needs to be dialed to initiate
contact with the I/O Device.

Note: These values can also be set using the I/O Devices form in the Project Editor.

Examples
All based on a Synchronize at time of 10:00:00:

284
 Chapter: 15 Communicating with I/O Devices

l If you enter 12:00:00 in the Repeat every field, and start your project at 9 a.m., the I/O
Server will communicate with the I/O Device at 10 a.m., then once every 12 hours
after that, i.e. 10 p.m., then again at 10 a.m. of the following day, etc.
l If you enter 12:00:00 in the Repeat every field, and start your project at 4 p.m., the I/O
Server will communicate with the I/O Server at 10 p.m., then again at 10 a.m. of the
following day, etc. It will assume that communications were established at 10 a.m.,
so it continue as if they had been - communicating once every 12 hours after 10 a.m.
l If you enter 3 days in the Repeat Every, and start your project at 9 a.m. on a Wed-
nesday, the I/O Server will communicate with the I/O Device at 10 a.m., then once
every 3 days after that, i.e. 10 a.m. on the following Saturday, then at 10 a.m. on the
following Tuesday, etc.
l If you enter the 6th of December in the Repeat every, and start your project during
November, the I/O Server will communicate with the I/O Device at 10 a.m. on
December 6, then again on December 6 of the following year, etc.
l Select On Startup for a persistent connection. To disconnect a persistent connection,
you need to call the IODeviceControl() function with type 8.
See Also
Caller ID and commands
Express Communications Wizard - Link to external database

Caller ID and commands

Caller ID
A unique identifier which identifies a remote I/O Device when it dials back to the I/O
Server. The caller ID can be any combination of alpha-numeric characters and/or the
character '_' (underscore).
This ID will only be used if the I/O Device initiates the call to the I/O Server. If the
modem initiates the call, you need to set the caller ID on the modem.

Note: If you are multi-dropping off a single modem, use your I/O Devices to issue the
caller ID, not the modem. This is because using the modem to issue the ID will send
the same ID no matter which I/O Device the call is relevant to, which makes it dif-
ficult to identify the I/O Device that triggered the call.

By using the I/O Device to issue the ID, the I/O Server will receive a unique caller ID for
each I/O Device. However, not every I/O Devices are capable of issuing caller IDs. If you
are multi-dropping, use I/O Devices that can issue caller IDs.

Option Description

285
Chapter: 15 Communicating with I/O Devices

[Event Com- Cicode to be executed once the modem is connected and the I/O
mands] On Device has come online (that is, before any read or write requests are
connect processed).

[Event Com- Cicode to be executed before the connection to the I/O Device is ter-
mands] On minated (and after read and write requests are processed).
disconnect

Note: These values can also be set using the I/O Devices form in the Project Editor.

See Also
Express Communications Wizard - Link to external database

Express Communications Wizard - Link to external database

This screen allows you to link to an external data source.

Option Description

Link I/O Device to an Determines whether or not you want to link the I/O
external tag database Device to an external data source. If you link to an exter-
nal data source, CitectSCADA is updated with any
changes made to the external data source when a refresh
is performed.

If you disconnect an existing link, you can choose to

make a local copy of the tags in the data source or you
can delete them from CitectSCADA's variable tags data
source altogether.

Database type The format of the data referenced by the external data
source.

External tag database Specify the location of the external database. This could
either be a path and filename of the external data source
for the I/O Device, or the IP address/directory, computer
name, or URL of a data server, etc. (for example
"Work.CSV" or "127.0.0.1", "139.2.4.41\HMI_SCADA"
or "http://www.abicom.com.au/main/scada" or
"\\coms\data\scada").

Depending on the database type selected, the browse

button could:

display a standard Windows file browse dialog to browse

for the external database.

286
 Chapter: 15 Communicating with I/O Devices

Option Description

display a modal dialog to browse in a tree view of servers

on the network connected to the computer.

display the Unity Link Configuration Properties dialog.

Connection string Enter a connection string to provide connection details

for the data source. This is similar to an ODBC connection
string. For example:

UserID = XXX; Password = YYY

or

ServerNode=111.2.3.44; Branch=XXX

Not every data source requires a connection string.

Add prefix to externally Check this box if you want to insert a prefix in front of the
linked tags names of linked tags in your Variable.DBF.

Tag prefix The prefix that will be inserted in front of the names of
linked tags in your Variable.DBF (for this I/O Device
only). To change the prefix, delete it first, perform a man-
ual refresh, then add the new prefix.

Automatic refresh of Determines whether the linked tags in CitectSCADA's var-

tags iable tags database will be updated when the external
data source is changed (i.e. you manually change a field,
etc.). This refresh will occur the first time you link to the
data source, and then whenever you attempt to read the
changed variables (for example you compile your
project, display the variable using the Variable Tags
form, or paste the tag, etc.).

Without an automatic refresh, you will need to perform a

manual refresh to update the linked tags in CitectSCADA.

Live Update This field is only available if you have installed one of the
CitectSCADAFastLinx products. It controls whether or not
the linked tags in CitectSCADA and an external tag data-
base will be synchronized if either database is changed.
To enable live linking, choose Yes from the Live Update
menu, and verify that the Automatic refresh check box
is not selected. (Live Update and Automatic Refresh are
mutually exclusive.)

When Live Update is enabled and the CitectSCADA var-

iable tag database is accessed (for example, during
project compilation or when a dropdown list is pop-
ulated), CitectSCADA queries the external tag database to

287
Chapter: 15 Communicating with I/O Devices

Option Description

determine if it has been modified. If so, CitectSCADA

merges the changes into the local variable tag database.
Conversely, any changes made to the local tag variable
database will be incorporated seamlessly into the exter-
nal tag database.

See Also
Express Communications Wizard - Serial device

Express Communications Wizard - Serial device

Since your protocol is based on serial communications you need to select which port on
your computer will be used for the I/O Device.
The serial ports listed have been detected from your operating system registry. If you
have correctly installed a proprietary serial board (for example a Digiboard) and the asso-
ciated driver, the available port will be listed.
See Also
Express Communications Wizard - Summary

Express Communications Wizard - Summary

Summarizes the I/O Device setup using the information you provided. The summary
shows the CitectSCADA communications setup and the recommended configuration of
your I/O Device and/or internal boards.

Manually Configuring Communications

Usually the Express Communications Wizard is sufficient to set up your com-
munications. However, if you need to manually configure communications, do the fol-
lowing:
1. Define an I/O Server in the I/O Server Properties form. This defines the name of the
CitectSCADA server that the I/O Device will communicate with.
2. Complete the Boards Properties. This defines which board (on your CitectSCADA
computer) to use to communicate (mother board, network card, serial board or a PLC
communication card). Dial-up remote I/O Devices need to use a COMx board.
3. Complete the Ports Properties. Often boards have multiple communication ports and
you need to specify the port to use. Some equipment can have several logical (virtual)
ports assigned to the one physical port. If using modems, you need to specify a

288
 Chapter: 15 Communicating with I/O Devices

unique port name for each and -1 for the port number. You need to also specify the
communication parameters and any special behavior of that port.
4. Complete the I/O Devices Properties. This defines the I/O Device that CitectSCADA is
talking to, by specifying the address. The protocol is also defined at this level.
5. Run the Computer Setup Wizard to complete configuration. This allows you to define
your CitectSCADA computer as the I/O Server defined above. This is usually done
after you compile the project.
6. If using dial-up remote I/O Devices, you need to complete the Modems dialog box.
This defines how CitectSCADA uses a modem to communicate with remote I/O
Devices.

Note: If there is no data to read or write, CitectSCADA will not communicate with an
I/O Device regardless of whether it is defined or not. You need to create a variable
tag and use it before CitectSCADA will do a read request. For example, use an integer
variable to display a number on a page.

I/O Server Properties

To define an I/O Server, you need to specify a name on the I/O Server form. This name
will be used to reference the I/O Server and has to be logical. For example, for a single
I/O Server, you might use the name IOServer. When specifying the server name, you can-
not use localized characters. See I/O Server Definitions.
If you are using multiple I/O Servers for redundancy (or to split the communications),
you need to add a database record for each. Select a unique name for each I/O Server, for
example IOServer1 and IOServer2.

Note: You need to add the record to the project database (use the Add Button at the
bottom of the form) or replace the record (use the Replace Button at the bottom of the
form) if you have changed the record.

Adding an I/O Server

To define a computer as an I/O Server, you need to run the Computer Setup Wizard on
that computer. The wizard allows you to choose from a selection of the I/O Servers you
have configured in your project.
See also
I/O Server Properties

289
Chapter: 15 Communicating with I/O Devices

Boards Properties
The properties of a board depend on the type of board installed in the I/O Server com-
puter.

Note: The term "Board" is a legacy term from the time when most ports on a com-
puter were provided by additional boards. For example, an Ethernet card. The logical
board concept is still useful even though a physical board may not exist (it may be
software).

Boards have the following properties:

Board Name
A name for the board. 16 characters maximum. For example Server1_Board1.
If you have more than one board in your I/O Server computer, the name of each board
needs to be unique. If you have multiple I/O Servers, the board name need only be
unique within each server. For example Server1_Board2
Board Type
The type of board. 16 characters maximum.
If you are using a serial board or your computer's COM port, enter COMx.
Address
The starting address of the Board. For example 0xCC00. 8 characters maximum.
You need to specify the address to match the switch settings on the board when it was
installed in your computer. If you are using a serial board or your computer's COM port,
enter 0 as the address.

Note: If more than one board is installed in the same computer, use a different mem-
ory address for each board.

I/O Port
The I/O port address of the Board. 8 characters maximum.
You need to specify the address to match the switch settings on the board when it was
installed in your computer.

Note: If you are using your computer's COM port not enter the port address here.
specify the port number in the Ports form.

Interrupt

290
 Chapter: 15 Communicating with I/O Devices

The interrupt number used by the Board. This is not necessary if using your computer's
COM port.
Special Opt
Any special options supported by the board. 32 characters maximum. Please check the
Hardware Arrangements Help Topic for your specific I/O Device to see if specific options
are necessary.
Comment
Any useful comment. 48 characters maximum.

Ports Properties
The properties of a port depend on the type of board installed in the I/O Server, and on
the I/O Device connected to the port. Ports have the following properties:
Port Name
A name for the port connected to your I/O Device(s). 31 characters maximum. Each port
needs to have a unique name (i.e. you cannot assign the same Port Name to two ports in
your system). You can use any name, for example: Board1_Port1
If you have more than one board in your computer, you can use the port name to iden-
tify the board, for example: Board2_Port1
Port Number
The port number that the I/O Device is connected to. 4 characters maximum. Do not
assign the same Port Number to two ports on a board, unless connecting to a dial-up
remote I/O Device via a modem (see the note below). Ports on different boards can be
assigned the same number.
If you are using your computer's COM port enter the port number here - the port number
is defined in the Ports section of the Windows Control Panel.

Note: If you are connecting to a dial-up remote I/O Device (via a modem), you need
to define a unique port name on the I/O Server for each dial-up remote I/O Device,
and the port number needs to be -1 for each.

Board Name
The name you used for the board. 16 characters maximum. This is necessary to link the
port to the board. For example Server1_Board1
Baud Rate
The baud rate of the communication channel (between the CitectSCADA I/O Server and
the I/O Device). 16 characters maximum.

291
Chapter: 15 Communicating with I/O Devices

Note: The I/O Device hardware and serial board may support other baud rates. If
you do choose an alternative baud rate, verify that both the I/O Device and serial
board support the new baud rate.

Data Bits
The number of data bits used in data transmission. You need to set your I/O Device to
the same value or a communication link cannot be established.
Stop Bits
The number of stop bits used to signify the completion of the communication. You need
to set your I/O Device to the same value.
Parity
The data parity used in data transmission.
Special Opt
Any special options supported by the port. 32 characters maximum. Please check the
Hardware Setup Help Topic for your specific I/O Device to see if specific options are nec-
essary.
Comment
Any useful comment. 48 characters maximum.

I/O Devices Properties

Configuring an I/O Device involves specifying its properties using the Project Editor. The
properties depend on both the protocol and I/O Device.
To configure an I/O Device:

1. In the Project Editor, select Communication | I/O Devices. The I/O Devices dialog dis-
plays.
2. In the Name field, type in a name for your I/O Device (PLC). The name needs to be
unique in the CitectSCADA system, unless the I/O Device is defined in other I/O
Servers (to provide redundancy). If redundancy is used, the I/O Device needs to then
have the same I/O Device number and address for each I/O Server. use different I/O
Device names for your primary and standby I/O Devices, otherwise I/O Device
Cicode functions cannot differentiate between them. 31 characters maximum.
3. In the Number field, enter a unique number for the I/O Device (0-16383). 8 characters
maximum. The number needs to be unique in the CitectSCADA system, unless the
I/O Device is defined in other I/O Servers (to provide redundancy). If redundancy is
used, the I/O Device needs to then have the same I/O Device number and address for

292
 Chapter: 15 Communicating with I/O Devices

each I/O Server. You may use the same device name, but if you want to use I/O
Device Cicode functions, it is easier to have different I/O Device names.

Note: For Numbers, Protocol and Port Type - The same network number is used
for redundancy (as stated above), however this implies that the Protocol is
usually the same (though there maybe some special circumstances where devices
support multiple protocols) and the Port modes are similar. i.e. a real world port
reference, DISKDRV or MEMORY . If DISKDRV is being used, then redundant
units (i.e. the same NUMBER) needs to be DISKDRV. This also applies for MEM-
ORY mode.

4. In the Address field, enter the address of the I/O Device. 64 characters maximum.
What you enter in this field is determined by the type of I/O Device (and protocol)
used, as each has a different addressing strategy.
5. In the Protocol field, select the protocol you are using to communicate to the I/O
Device. 16 characters maximum. Many I/O Devices support multiple protocols,
dependent on the communication method chosen.
6. In the Port Name field, specify the port on the board to which the I/O Device is con-
nected. 31 characters maximum. This is necessary to link the I/O Device to the port.
For example Board1_Port1.

Note: There is a limit of 255 COMx ports on a server. To avoid this limitation
restricting your number of remote I/O Devices, you can connect multiple remote
I/O Devices to the same port as long as communication details (Telephone
number, baud rate, data bits, stop bits, and parity) are identical.

7. In the Startup mode field select the type of I/O Device redundancy:

Primary Enable immediate use of this communications channel.

This is the default mode if no mode is specified.

Standby This channel will remain unused until the I/O Device
configured with the primary channel becomes inoper-
ative.

Stand- This channel will remain unused until the I/O Device
byWrite configured with the primary channel becomes inoper-
ative. Write requests sent to the primary channel are
also sent to this