0% found this document useful (0 votes)

1K views

CitectSCADA User Guide

manual de usuario de citect scada

Uploaded by

SamuelEsauMorenoMoreno

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

1K views

CitectSCADA User Guide

manual de usuario de citect scada

Uploaded by

SamuelEsauMorenoMoreno

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 1393

CitectSCADA v7.

40
CitectSCADA User Guide
August 2013
Legal Information
DISCLAIMER
Schneider Electric (Australia) Pty. Ltd. makes no representations or warranties with respect to this manual and, to the maximum
extent permitted by law, expressly limits its liability for breach of any warranty that may be implied to the replacement of this manual
with another. Further, 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.
The Example Projects are provided to you for the purpose of illustrating how the SCADA software v7.40 could be used in an oper-
ational environment ("the Purpose").Schneider Electric grants you a royalty free, non exclusive, non transferable license to use the exam-
ple projects installed with your SCADA software version v7.40 (“the Example Projects”) for the Purpose only.
The Example Projects are provided by Schneider Electric as part of the SCADA software version v7.40 on an "as is" basis and Schneider
Electric does not guarantee the reliability, serviceability or function of the Example Projects.
Should you modify the Example Projects, you bear the risk of any use of such modified Example Projects.
Schneider Electric gives no express warranties, guarantees or conditions and to the extent permitted under applicable laws, Schneider
Electric disclaims all implied warranties, including any implied warranties of merchantability, fitness for a particular purpose or non-
infringement of third parties’ intellectual property rights.
Schneider Electric shall not be liable for any direct, indirect or consequential damages or costs of any type arising out of any action
taken by you or others related to the Example Projects.

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,, PowerSCADA Expert and CitectSCADA are either registered trademarks or trademarks of Schneider Electric (Aus-
tralia) Pty. Ltd. .
Pelco, Spectra, Sarix, Endura, are registered trademarks of Pelco, Inc.
IBM, IBM PC and IBM PC AT are registered trademarks of International Business Machines Corporation.
MS-DOS, Windows, Windows NT, Microsoft, and Excel are either registered trademarks or trademarks of Microsoft Corporation in the
United States and/or other countries.
DigiBoard, PC/Xi and Com/Xi are trademarks of Digi International Inc.
Novell, Netware and Netware Lite are 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 INFORMATION
Some product names used in this manual are used for identification purposes only and may be trademarks of their respective com-
panies.
August 2013 edition for CitectSCADA Version v7.40.
Manual Revision Version v7.40.

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. © 2013 Schneider Electric (Aus-
tralia) Pty. Ltd. . All Rights Reserved.
Validity Note
The present documentation is intended for qualified technical personnel responsible for the implementation, operation and main-
tenance of the products described. It contains information necessary for the proper use of the products. However, those who wish to
make a more "advanced" use of our products may find it necessary to consult our nearest distributor in order to obtain additional infor-
mation.
The contents of this documentation are not contractual and in no way constitute an extension to, or restriction of, the con-
tractual warranty clauses.

Contact Schneider Electric today at www.schneider-electric.com

Contents

Legal Information 1

Contents 3

Getting Started 29

Safety Information 31

Chapter 1: Getting Technical Support 33

CitectSCADA Technical Support 33
Training 34
Contact information 34

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

What's New in CitectSCADA 7.0 35
The Migration Tool 36
Clustering 36
Local Variables 36
Publish Alarm Property 37
Memory Mode 37
Client-side Online Changes 37
Publisher-Subscriber Model 38
Dual Network Support 38
Project-Based Network Configuration 38
Citect.ini Parameters in version 7.0 39
New Parameters 39
Obsolete Parameters 42
Cicode Functions in 7.0 46
CtAPI Functions in 7.0 56
Kernel Commands in Version 7.0 57

3
Contents

What's New in CitectSCADA 7.10 57

CitectSCADA Security Enhancements 58
Windows Integrated Security 58
Multi-Signature Support 59
Edit .dbf Files in Microsoft® Excel 59
Enhanced Driver Installation 59
New Font Selection for Graphics Button 60
Microsoft Windows Vista Support 61
New Locations for Configuration and Project Files 61
Alarm Field Enhancements 62
New Time Synchronization Service 64
New Equipment Database Functions and Forms 64
Citect.ini Parameters in 7.10 64
Cicode Functions in 7.10 66
What's New in CitectSCADA 7.20 68
Control SCADA Client Connections 69
Dynamically Optimized Writes 69
Environment variables in 7.20 70
Graphic Enhancements 70
Improved Installation Process 71
Improved CitectSCADA Security 71
Multi-process Support in Demo Mode 72
New Example Project 72
Web-based Help 72
OFSOPC Driver 73
Pelco Camera Support 73
Performance Enhancements 74
Persisted I/O Memory Mode 74
Post Compile Commands 75
Improved Client Side Online Changes 75
Server Side Online Changes 75
Microsoft Windows 7 Support 75
Supportability Enhancements 76
New Tab Menu Templates 76
Tag Extensions 77
Citect.ini Parameters in 7.20 77
CtAPI Functions in 7.20 85
Cicode Functions in 7.20 85
What's New in CitectSCADA 7.30 92
ActiveX Data Objects(ADO) 93
Alarm Enhancements 93
Equipment Hierarchy 94
GUI Enhancements 94
Importing Equipment 95
Software Protection 95
Using an OPC DA Server 96
Schneider Electric Software Update 97
Supportability Enhancements 97
Tag Browsing 98

4
Contents

Scheduler 98
Citect.ini Parameters in 7.30 98
CtAPI Functions in 7.30 103
Cicode Functions in 7.30 104
What's New in CitectSCADA 7.40 112
Referencing a variable tag using Equipment.Item 113
New Cicode functions to maintain a list of unique Pages "opened" 114
Equipment Editor Interface 114
New StruxureWare Templates 114
OPC Factory Server (OFS) Security Update 115
Citect.ini Parameters in 7.40 115
Cicode Functions in 7.40 116
CtAPI Functions in 7.40 119

Chapter 3: Upgrading to CitectSCADA 121

Upgrade CTAPI Applications 126
Configure I/O Devices 126
Run the Citect Installer 127
Launch CitectSCADA 127
Migration Tool 128
Creation of roles for existing users 133
Define Clusters 135
Configure Network Addresses 135
Configure Servers 136
Configure Tags to Use Clustering 137
Configuring Multiple Monitor Support 139
Compile the Project 139
Run Computer Setup Wizard 139
Alarm Server Upgrade 139
Migrating Alarm Event History 140
Upgrade queries that use custom alarm filters 141
New Alarm Page Templates 141
Alarm Database Upgrade 141
Alarm string translation changes 141
Alarm Summary Page Behavior 142
Alarm*Rec Functions changes 142
Troubleshooting 142

Chapter 4: About CitectSCADA 145

Software Protection 145
Floating Point License Manager 146
FlexNet license server 146
Independent Point Count 147
CiUSAFE dialog properties 149
Demo mode 150
Dynamic-point count licensing 150
Configuring a CitectSCADA project 152
Deploying CitectSCADA 152

5
Contents

Running a project 153

Chapter 5: Tools 155

Configuration Tools 155
Runtime Tools 156
Drivers 157

Chapter 6: Components of a project 159

Graphics components 159
Tags 160
Alarms 161
System components 161
Communications components 163
Server components 163
Cicode / CitectVBA 164

Chapter 7: Typical system scenarios 165

Standalone system 166
Distributed I/O system 166
Client-Server system 168
Redundant server system 169
Clustered control system 170
Redundant and distributed control system 171
Load sharing system 173

Using CitectSCADA 175

Chapter 8: Planning a Project 177

The Physical Layout of a Plant 177
Operational Requirements 178
Architecture 178
Security 178
Reliability 179
Monitoring 179
Data collection 179
Project Design 180
Naming Standards 180
Page Templates 181
Genies and Super Genies 181
Clustering 181
Included projects 182
Redundancy 183
Building Your Project 183
Projects 184
Setting up I/O Device Communication 184

6
Contents

Graphics Components 185

Alarms 185
Data Collection 185
Users and Areas 186
System Components 186
Anti-virus software setup 187
Setting up Your Computers 188
Setting up CitectSCADA as an OPC DA server 189

Chapter 9: Administering Projects 191

Managing your projects 191
Understanding Projects within CitectSCADA 191
Creating a project 194
Viewing projects 196
Editing the properties of an existing project 197
Copying projects 200
Printing project details 201
Deleting a project 202
Linking projects 203
Time Synchronization 204
Time Synchronization Dialog 205
Archiving projects 206
Backing up a project 207
Backing up INI files 208
Configuring a backup with password encryption 208
Running a backup from the command line 209
Restoring a project 211
Including projects 212
Including a project in the current project 214
Working with the Project Editor 215
Setting the Project Editor options 215
Paste Tag dialog box 218
Paste Function dialog box 219
Find User Function dialog box 219
Using Find and Replace in a project 220
The Find and Replace dialog 220
Specifying search coverage 221
Using the results list 222
Removing results 223
Exporting results 223
Jumping to a result (Go To) 224
Replacing results 225
Find and Replace alert messages 226
Troubleshooting Searches 229

Chapter 10: Securing Projects 231

Overview 231
Securing a Top-level Project 232

7
Contents

Securing an Include Project 234

Making a Project Read-Only 235
Read-Only Privileges on Projects 236
Securing Runtime Computers 241
Client Start up Restrictions 241
Running a client as a shell 242
Disabling Windows keyboard commands 242
Disabling control menu commands 242
Removing the Cancel button 242

Chapter 11: Using CitectSCADA Security 245

Areas 245
Privileges 247
Roles 249
Users 250
Configuring CitectSCADA Security 251
Configuring Areas 251
Using labels to name areas 251
Using groups of areas 252
Groups properties 253
Viewing areas of the plant 254
Adding Roles 255
Configuring Privileges 257
Using hierarchical privilege 258
Implementing System Security 258
Privilege and Area combinations 258
Using multiple areas with privileges 260
Adding users 262
Reserved User Names 264
User records and project restoration 265
Using CitectSCADA integrated with Windows Security 265
Adding Groups and Users 266
Scenarios and Usage 267
Authenticating a Trusted Network 268
Setting the Super User Password 269

Chapter 12: Configuring Your System 271

Running the Computer Setup Wizard 271
Project Configuration 272
Runtime only environment 273
Computer Role Configuration 274
Network Model 275
Configure Server Password 275
Configure Server User 276
Internet Server Configuration 276
Reports Configuration 277
Trends Configuration 278
CPU Configuration 278

8
Contents

Events Configuration 279

Startup Functions Configuration 280
Cluster Connections Configuration 281
Control Menu Security Configuration 282
Keyboard Security Configuration 283
Miscellaneous Security Configuration 283
EcoStruxure Web Services Server Setup 284
Modifying the URL Reservation 284
EcoStruxure Web Services Server User Setup 285
General Options Setup 286
Finish 287
Firewall Settings and CitectSCADA 287
Launching Runtime for the first time 288

Chapter 13: Implementing Clustering 289

Rules of Clustering 291
Cluster Definitions 293
Network Address Definitions 294
Alarm Server Definitions 294
Alarm Server Side Synchronization 296
Main-Main Scenario 296
Duty Mode 297
Reports Server Definitions 298
Trends Server Definitions 299
I/O Server Definitions 300
Assigning graphics page objects to a cluster at Runtime 301

Chapter 14: Building Redundancy Into Your System 303

I/O Server Redundancy 304
I/O Device promotion 305
Redundancy and Persistence 307
Data Path Redundancy 308
Multiple Device Redundancy (Standby Data Paths) 310
Network Redundancy 312
Configuring network redundancy 313
Reports and Trends Server Redundancy 313
Alarms server redundancy 315
Reports server redundancy 317
Trends server redundancy 318
File server redundancy 318
FTP server redundancy 319
Redundancy of Standalone Systems 320

Chapter 15: Communicating with I/O Devices 321

The Role of the I/O Server 322
The Role of the I/O Device 322
The Role of the Transport Medium 323

9
Contents

The Role of the Protocol 324

Communication Configuration 325
Retrieving time-stamped data from field devices 328
Setting Up Communications 329
Preparing a Device 330
Preparing the I/O Server for Communication 330
Creating a communications test project 338
Using the Communications Express Wizard 339
Express Communications Wizard - introduction 340
Express Communications Wizard - Server selection 340
Express Communications Wizard - Device selection 340
Express Communications Wizard - I/O Device type 341
Express Communications Wizard - I/O Device communications selection 341
Express Communications Wizard - TCP/IP address 341
Express Communications Wizard - I/O Device address 342
Express Communications Wizard - I/O Device connection schedule 342
Express Communications Wizard - Link to external database 344
Express Communications Wizard - Serial device 346
Express Communications Wizard - Summary 346
Manually Configuring Communications 347
I/O Server Properties 347
Boards Properties 348
Ports Properties 349
I/O Devices Properties 350
I/O Devices Properties Extended 353
Working With Device Drivers 358
Determining Which Driver to Use 359
Installing a Driver Pack 360
The Driver Update Utility 361
Using the Driver Reference Help 361
Customizing Communication Using Citect.ini Parameters 362
Using a Disk I/O Device 363
Disk I/O Device setup 364
Redundant Disk I/O Devices 365
Disk I/O Device Errors 366
Using Memory Mode 367
Using Persisted I/O Memory Mode 368
Troubleshooting Device Communications 369
Gathering information about device communication 370
Debugging I/O Devices and Protocols 371
Debugging a COMx driver 372
Debugging a TCP/IP driver 375
Debugging a protocol driver using serial communications 377
Debugging proprietary board drivers 379
Serial Port Loop-Back Test 379
Contacting Technical Support 381
Performance Considerations 382
Caching data 382
Grouping registers 384

10
Contents

Remapping variables in an I/O Device 385

Remapping example 389
Advanced Driver Information 390
Variable (digital) limitations 390
Validating distributed project data for tag-based drivers 392
Write delay effects 392
Communicating with Remote Devices via Modems 394
Modems at the I/O Server 395
Modems at the I/O Device 396
Example configurations for modems at the I/O Server 396
I/O Device constraints for multi-dropping 401
Configuring multidrop remote I/O Devices 403
I/O Server redundancy for dial-up remote I/O Devices 407
Troubleshooting dial-up remote I/O Device communications 407
Alternative (backward compatibility) method of persistent connection 408
Scheduled Communications 409
Specifying a schedule 409
Writing to the scheduled I/O Device 410
Reading from the scheduled I/O Device 411

Chapter 16: Tagging Process Variables 413

Tag Naming 414
Tag name syntax 414
Using structured tag names 415
Tag Data Types 420
Configuring Variable Tags 421
Variable Tag Properties 422
Defining Variable Tag Names 427
Referencing Variabe Tags in your project 429
Formatting numeric variables 429
Using arrays 432
Configuring Local Variables 436
Tag Browsing 438
The Browsing Session 438
Opening a Browsing Session 439
Browsing Filter 440
Browsing Field 440
Sort Order 441
Browsing Clusters 441
Tag Extensions 441
The Quality Tag Element 444
Reading and Writing Tags 449
XML DataSource Schema 451

Chapter 17: Linking, Importing, and Exporting Tags 463

Linking tags 463
Breaking the link to the external data source 465
Deleting the I/O Device 465

11
Contents

Chapter 18: Defining and Drawing Graphics Pages 513

Creating a New Graphics Page 513
Animation points 514
New Dialog Box 514
Working with pages 514
Use Template (new page/template) dialog box 516
Open/Save As dialog box 517
Using Page Templates 518
Choosing a page style 519
Linking templates 519
Creating your own templates 519
New Style dialog box 521
Using a Browse Sequence 521
Specifying a Startup or Splash Page 522
Sizing the Page 523
Page (screen) resolution 523
Screen examples 524
Page size at runtime 532
Securing the window title bar 532
Defining Page Properties 533
Page Properties - General 533
Page Properties - Appearance 535
Page properties - Keyboard Commands 537
Page Properties - Events 538
Page Properties - Environment 540
Page Properties - Associations 541
Setting Default Page Settings 542

12
Contents

Page defaults 543

Understanding the Drawing Environment 544
Grids 544
Grid Setup dialog box 545
Guidelines 545
Guidelines Setup dialog box 546
Options 546
Colors 548
Edit Favorite Colors dialog box 549
Swap Color dialog box 552
Adjust colors dialog box 554
Zooming 555
Using libraries 556
Using symbols 557
Bitmaps 558
Import dialog box 560

Chapter 19: Using Objects 563

Using groups 564
Reshaping objects 565
Reshaping a line object 565
Using bitmaps 565
Importing graphics 566
Object Properties 566
Appearance 566
Movement 567
Scaling 567
Fill 568
Input 568
Slider 568
Access 569
Metadata 569
Using Metadata 571
Passing Animation Point Metadata as Super Genie Associations 576
Manipulating Objects 577
Selecting objects 578
Moving objects 578
Resizing objects 579
Deleting objects 580
Locking/unlocking objects 581
Grouping objects 581
Copying and pasting objects 582
Changing the Overlap of Objects 583
Aligning objects 584
Rotating objects 585
Mirroring objects 586
Locate an object 586

Chapter 20: Understanding Object Types 589

13
Contents

Free Hand Line Objects 589

Freehand Line Properties - Appearance (General) 590
Straight Line Objects 591
Straight Line Properties - Appearance (General) 591
Rectangle Objects 592
Rectangle Properties - Appearance (General) 593
Ellipse Objects 596
Ellipse Properties - Appearance (General) 597
Polygon Objects 601
Polygon Properties - Appearance (General) 602
Pipe Objects 605
Pipe Properties - Appearance (General) 606
Text Objects 607
Text Properties - Appearance (General) 607
Text Properties - Appearance (Display Value) 608
Number Objects 614
Button Objects 614
Button Properties - Appearance (General) 615
Symbol Set Objects 617
Symbol Set Properties - Appearance General (On/Off) 619
Symbol Set Properties - Appearance General (Multi-state) 619
Symbol Set Properties - Appearance General (Array) 621
Symbol Set Properties - Appearance General (Animated) 622
Trend Objects 623
Trend properties 624
Insert Trend dialog box 626
Cicode Objects 626
Cicode Object Properties - Cicode (General) 627
Pasted Symbol Objects 628
Paste Symbol dialog box 628
Symbol Properties - Appearance (General) 629
Pasted Genie Objects 630
ActiveX Objects 630
Managing associated data sources 630
ActiveX Object Properties 631
Tag Association 631
ActiveX Object Properties - Appearance (Tag Association) 632
Object Identification 634
Object Properties - Access (Identification) 634
Database Exchange Control Objects 635
Vijeo Web Gate Control Objects 635

Chapter 21: Defining Common Object Properties 637

3D Effects 637
Object Properties - Appearance (3D Effects) 638
Visibility 641
Object Properties - Appearance (Visibility) 641
Movement 642

14
Contents

Object Properties - Movement (Horizontal) 642

Object Properties - Movement (Vertical) 644
Object Properties - Movement (Rotational) 646
Group and object movement - examples 648
Scaling 650
Object Properties - Scaling (Horizontal) 651
Object Properties - Scaling (Vertical) 654
Fill Color 657
Object Properties - Fill Color (On/Off) 657
Object Properties - Fill Color (Multi-state) 659
Object Properties - Fill Color (Array) 661
Object Properties - Fill Color (Threshold) 664
Object Properties - Fill Color (Gradient) 666
Fill Level 668
Object Properties - Fill (Level) 669
Touch Commands 672
Object Properties - Input (Touch) 673
Keyboard Commands 675
Object Properties - Input (Keyboard Commands) 676
Sliders 678
Object Properties - Slider (Horizontal) 679
Object Properties - Slider (Vertical) 680
Object Properties - Slider (Rotational) 682
Access 683
General Access to Objects 684
Object Properties - Access (General) 684
Disable Access to Objects 686
Object Properties - Access (Disable) 686

Chapter 22: Defining Commands and Controls 689

Touch commands 689
Keyboard commands 690
Slider controls 690
System Keyboard Commands 690
System keyboard command properties 691
Keyboard Keys 692
Keyboard keys properties 692
Keyboards 693
Defining Key Sequences for Commands 694
Using a hot key 695
Using variable data input 696
Passing multiple arguments 698
Passing keyboard arguments to functions 699
Configuring Page Menus 699
Menu Configuration Properties 701
Displaying Tags 702

Chapter 23: Using Alarms in SCADA 705

15
Contents

Pre-requisite Alarm Information 705

Understanding Alarms and Events in SCADA 705
Understanding how the alarm information is retrieved 707
Configuring alarms 709
Adding a new Alarm 710
Using alarm delay 713
Digital Alarm Properties 715
Time-stamped Alarm Properties 718
Multi-digital Alarm Properties 722
Analog Alarm Properties 726
Time-stamped Digital Alarm Properties 731
Advanced Alarm Properties 734
Time-stamped Analog Alarm Properties 737
Scenarios for the Item Name Field 741
Using custom alarm filters 743
Converting AlarmSetQuery() functions to the Alarm filter functions 743
Implementing queries that use custom alarm filters 746
Understanding Named Filters 747
Implementing alarm filters using Cicode 750
Efficiency considerations 751
Alarm Categories 752
Alarm Category Properties 752
Formatting the Alarm Display 759
Including CitectSCADA data 760
Including fixed text 761
Displaying lists and tables 761
Variable data in alarm messages 761
Alarm display fields 762
Alarm SOE fields 766
Alarm summary fields 771
Changing the Order of the Alarm Summary Display 772
Using System Fonts 773
Fonts properties 773
Configuring Custom Color Fonts 775
Using Alarm Properties as Tags 776
Supported alarm properties 777
Writing to alarm properties 782
Setting up alarm properties 784
Handling Alarms at Runtime 784
Working in the Alarm Display List 786
Adding a comment to the Alarm SOE page 786
Adding a new event to the Alarm SOE page 787
Troubleshooting Alarms 788
SOE page displays old events with recent events not shown 788
SOE page is empty 788
Archiving the Event Journal 789
Understanding the archiving parameters 790
Manually archiving using SOE Cicode functions 791
Automatic archiving using the Alarm Server Definitions Form 793

16
Contents

Using Scheduler to trigger archiving 793

Chapter 24: Using an OPC AE Server 795

Using a Third Party OPC Client to access Alarm Server Data 795

Chapter 25: Configuring Events 797

Events Properties 797
Running Events 799
Specifying times and periods 799
Using triggers 800

Chapter 26: Using Accumulators 803

Accumulator Properties 803

Chapter 27: Logging and Trending Data 807

Trending Data 807
Configuring trend tags 808
Trend Tag Properties 808
Trend Graphs 817
Creating trend pages 818
Trend interpolation 819
Printing Trend Data 820
Exporting Trend Data 821
Using Trend History Files 821
Storage method 823
Calculating disk storage 823
Reconfiguring history files 825
Using Path Substitution 825
Default path definitions 826
Debugging Trending 827

Chapter 28: Understanding Statistical Process Control 829

Process Variation 830
Statistical Control 831
Process Capability 831
XRS Control Charts 832
CL, UCL and LCL 832
Interpreting the chart 833
Capability Charts 833
USL and LSL 834
Cp index 834
Cpk Index 834
Pareto Charts 834
Using Statistical Process Control (SPC) 835
SPC Tags 835

17
Contents

Chapter 29: Reporting Information 855

Configuring reports 855
Reports dialog box 856
Running Reports 858
Running a report on startup 858
Specifying times and periods 858
Using triggers 859
Using commands 860
Report Format File 860
Report example 862
Handling Communication Errors in Reports 863
Reporting errors in I/O Device data 864
Suppressing reports 865

Chapter 30: Using Labels 867

Using Arguments in Labels 869
Converting Values into Strings 870
Substituting Strings 871
Defining Labels 871

Chapter 31: Using Devices 873

Using groups of devices 875
Using devices to read data 875
Configuring Devices 876
Configuring SQL Devices 881
Formatting Data in the Device 882
Printer and ASCII devices format 882
dBASE and SQL database devices format 884
Using a database device 885
Using Device History Files 888
Using Command Fields 891
About Print Management 892

Chapter 32: Understanding Equipment in SCADA 895

18
Contents

Defining an Equipment Hierarchy 896

Configuring Equipment 897
Naming Equipment in your project 898
Association with Clusters 899
Using the Equipment Editor 899
Equipment Editor Tabs 900
Equipment Types 900
Adding Equipment types 901
Duplicate Equipment Types 902
Modifying Equipment Types 902
Items 903
Modifying Items 904
Elements 904
Modifying Elements 905
Fields 906
Parameters 906
Parameter Groups 908
Equipment Editor 908
Create Equipment 909
Duplicate Equipment 909
Rename Equipment 909
Move Equipment 910
Close Equipment 910
Delete Equipment 910
Example - Using the Equipment Editor 911
Using the Equipment Forms 922
Equipment Types 922
Equipment Properties 923
Associating Equipment 925
Importing Equipment Using XML Templates 926
Equipment XML Template 927
Equipment Templates: Output Node 931
Equipment Templates: Output Field 932
Equipment Templates: Output Common Fields 932
Equipment Templates: Output Database 933
Troubleshooting Equipment Templates 935

Chapter 33: Using External Databases 937

dBASE databases 937
SQL databases 938
Using Structured Query Language 939
Limitations When Using Legacy SQL Functions 940
Database Connection Objects 940
Basic SQL Scenarios 941
Connecting to an SQL database 942
Working with recordsets 944
Parameterized queries 944
Executing legacy SQL commands 945

19
Contents

Using a transaction 946

Expressing dates and times in SQL 946
Conversions between database and Cicode types 947

Chapter 34: Exchanging Data with Other Applications 951

Using DDE (Dynamic Data Exchange) 951
DDE conversations and client syntax 952
DDE function types 955
Exchanging data via DDE 956
Connecting to the tag database using DDE 956
Posting select data using DDE 957
Writing values to a DDE application 958
Reading values from a DDE application 959
Using DDE with Microsoft Office applications 960
Network DDE 961
DDE Shares 964
Using DDE Trusted Shares 964
Using ODBC drivers 967
Installing the ODBC driver 967
About the ODBC driver 968
Setting up ODBC 969
Getting the correct syntax with ODBC 969
Programming style with ODBC 970
Comparing DDE with ODBC 971
ODBC compatibility 972
Using CitectSCADA as an ODBC server 974
Reading data from an access table with ODBC 976
Appending data with ODBC 977
Editing data with ODBC 977
Deleting rows from an Access table 978
Calling action queries with ODBC 978
Parameter queries 979
Access and Cicode date/time conversions 980
Using Microsoft Excel to Edit .dbf Tables 981
Functionality 983

Chapter 35: Genies and Super Genies 985

Genies 985
Defining Substitutions for Genies 986
Configuring Genies 986
Using Genies 988
Maintaining a Genie 990
Using Genie Substitutions in Templates 991
Using structured tags with Genies 991
Super Genies 992
Defining Substitutions for Super Genies 993
Defining Associations for Super Genies 994
Configuring a Super Genie 994

20
Contents

Configuring a Super Genie as a Page 994

Configuring a Super Genie as a Library Object 996
Using a Super Genie Page 998
Using a Super Genie Library Object 999
Maintaining a Super Genie Page 1002
Maintaining a Super Genie Library Object 1003
Using Constants and Arrays with Super Genies 1004
Nesting Super Genies 1006
Super Genie areas 1006
Super Genie Library Objects and Associations 1007
Using structured tags with Super Genies 1007
Hiding Graphics Objects 1009
IFDEF macro 1009

Chapter 36: Multi-Language Projects 1011

Preparing a project for multi-language support 1011
Marking text for translation 1012
Marking alarm text for translation 1013
Defining the languages supported by a project 1015
Languages Properties 1018
Defining CitectSCADA unsupported languages 1019
Translating local language databases 1020
Setting the local language used at runtime 1021
Logging data in different languages 1021
Changing the local language at runtime 1022
Alarm data localization 1022
ASCII and ANSI character sets 1023
OEM character sets 1024

Chapter 37: Working with Multiple Monitors 1025

Configuring Startup Pages for Multiple Monitors 1025
Using an OPC DA Server 1026
Configuring an OPC DA Server 1027
OPC DA Server Properties 1027
OPC DA Server DCOM settings 1029
Operating the OPC DA Server at Runtime 1031
Starting the OPC DA Server on a Client Connection 1032
OPC Item Browsing 1032
OPC DA Server Diagnostics 1033
OPC DA Server Logging 1033
OPC DA Server Kernel statistics 1034
OPC DA Server reference information 1034
Supported OPC DA Server Interfaces 1034
Client request data type conversions 1036
OPC client read request conversions 1036
OPC client write request conversions 1037
OPC DA Server mandatory properties 1039
Using an EcoStruxure Web Service Server 1041

21
Contents

Configuring an EcoStruxure Web Services Server 1042

EcoStruxure Web Services Server Properties 1042
EcoStruxure Web Services Server SSL Certificate 1043
Operating the Ecostruxure Web Services Server at Runtime 1044
EcoStruxure Web Services Server Supported Methods 1044

Chapter 38: Compiling and Running a Project 1047

Compiling a Project 1047
Incremental compilation 1049
Debugging the compilation 1049
Compilation options 1050
Compile Error Properties 1051
Compile Error Messages 1052
Distributing the Project 1062
Example of Using Run/Copy to Distribute Project Runtime Files 1063
Identifying external files for inclusion in a runtime deployment 1065
Custom Files Properties 1066
Running the System 1068
Startup and runtime configuration 1069
Running servers independently 1069
Server Redirection Using Address Forwarding 1070
Using an Alternative INI File 1071
System tuning 1072
Client Side Online Changes 1074
Server Side Online Changes 1075
Alarm Reload Behavior 1081
Restarting the System Online 1082
Restarting a networked system online 1082
Running Your System Over the Internet 1086
The Internet Display Client 1086
The Internet server 1087
Startup and runtime configuration 1087
Server - client file updates 1088
Monitoring and Debugging the Runtime System 1090
Gathering Runtime Information 1091
Hardware alarms 1091
Log Files 1092
Configuring Logging 1096
Adjusting Logging During Runtime 1096
The Crash Handler 1097
Using the Kernel 1099
Displaying the kernel window 1100
Inside the kernel 1102
Using Kernel Commands 1105
Kernel commands 1106
Integration with Historian 1142
Preparing variables for Historian integration 1143

Scheduler 1145
22
Contents

Chapter 39: Scheduler for Operators 1147

Scheduler - an Overview 1147
The Scheduler Interface 1147
Views within Scheduler 1148
Understanding the Equipment Tree 1148
Scheduling entries on Daylight Saving 1149
Adding a new Schedule entry 1150
Maintaining Schedule Entries 1152
Overlapping schedule entries 1153
Schedule Inheritance 1154
Override and Normal mode 1155
Special Days 1156

Chapter 40: Scheduler for Engineers 1159

Understanding Scheduler 1159
Backing up CitectSCADA 1160
Scheduler Security and Permissions 1160
Online Changes 1161
Redundancy 1161
Kernel Trace Messages 1162
Tracelog Trace Messages 1163
Time Synchronization 1165
Configuring Scheduler 1165
Configuring Equipment for Inclusion in Scheduler 1166
Configuring Equipment States 1168
Editing States 1168
Equipment State Properties 1168
Configuring States with Entry Action 1170
SchedulerConfiguring States with Delay 1171
Configuring States with Repeat Action and Period 1171
Demand and Response Support 1172
Using the Scheduler ActiveX Control 1173
Configuring Special Day Groups 1174

Using the Web Client 1175

Chapter 41: The Web Client 1177

System architecture 1177
Getting Started 1179
Preparing a Project for Deployment 1180
Functionality limitations of the Web Client platform 1181
Running the Web Deployment Preparation tool 1183
Configuring a deployment 1184
Creating a new deployment 1185
Deploying a project from within CitectSCADA 1187
Displaying a deployment 1190

23
Contents

Editing an existing deployment 1191

Updating a deployment to reflect project changes 1192
Deleting a deployment 1192
Implementing Multiple Language Support 1193
How default languages are implemented 1193
Using a language different to the current system locale setting 1194
Implementing a non-default language 1195
Web Client Upgrade Considerations 1197
Frequently Asked Questions 1198

Chapter 42: Windows Language Codes 1205

Using the StruxureWare Templates 1208

Chapter 43: Introducing StruxureWare Templates 1209

The StruxureWare Interface 1209
The Header 1210
The Right-Panel 1212
The Main Window 1213

Chapter 44: Using StruxureWare Pages and Templates 1215

Normal Page Template 1216
Blank Page Template 1216
Data Browse Page Template 1216
Alarm Page Templates 1219
Process Analyst Page Templates 1224
Statistical Process Control Trend Page Templates 1225
File Page Templates 1225

Chapter 45: Creating a New Project 1227

Creating a Privileged User 1228
Running the Computer Setup Wizard 1229
Using Instant Trending 1229
Displaying a Project on Multiple Monitors 1230
Implementing Audible Alarms 1230
Creating Pages 1231
Creating new pages 1232
Creating Custom Menus for StruxureWare templates 1232
Using Environment Variables in StruxureWare Templates 1235

Using the Tab Style Page Templates 1237

Chapter 46: Introducing Tab Style Page Templates 1239

24
Contents

Where to Find Information 1239

Chapter 47: Using Pages and Templates 1241

Common Navigation Functionality 1242
Custom Tabbed Menus Toolbar 1242
Navigation Toolbar 1243
Alarm Toolbar 1245
Normal Page Template 1246
Blank Page Template 1246
Data Browse Page Template 1247
Alarm Equipment Tree-view Page Templates 1250
Common Functionality 1251
Alarm Page Templates 1256
Common Functionality 1258
Process Analyst Page Templates 1260
Statistical Process Control Trend Page Templates 1261
File Page Templates 1262

Chapter 48: Creating a New Project 1263

Creating a Privileged User 1264
Running the Computer Setup Wizard 1265
Security Setup - Control Menu page 1265
Using Instant Trending 1265
Displaying a Project on Multiple Monitors 1266
Implementing Audible Alarms 1266
Creating Pages 1267
Creating new pages 1268
Creating Custom Menus 1268
Defining page menus 1269
Defining template popup menus 1271
Using Environment Variables in Tab Style Templates 1271

Using the Library Control Include Project 1273

Chapter 49: Introducing the Library Control Include Project 1275

Chapter 50: Using the Library Controls 1277

Alarm Table Library Control 1278
Using the Alarm Table Genie 1280
Browse Table Library Control 1282
EquipTree Library Control 1284
PageTabs Library Control 1287
Scroll bar Horizontal Library Control 1289
Scroll bar Vertical Library Control 1290
Slider Library Control 1291

25
Contents

SQL Table Library Control 1292

Tabs Library Control 1294
Using the Tab Genie 1296
Table Library Control 1298
Using the Table Genie 1300
Table Row Library Control 1303
Tag Table Library Control 1303
Using the Tag Table Genie 1305
Tree Library Control 1309
Using the Tree Genie 1311
Using User Callback functions with the Library Control Genies 1314

Using the CSV_Include Project 1317

Chapter 51: Introducing CSV_Include 1319

Where to Find Information 1319

Chapter 52: Using Pages and Templates 1321

Normal Page Template 1322
Alarm Page Templates 1322
Common functionality 1323
Trend Page Templates 1323
Common functionality 1324
File Page Templates 1328
Admin Tools Page Template 1328
Common Toolbars 1329
Navigation Toolbar 1330
Alarms Toolbar 1332

Chapter 53: Creating a New Project 1335

Creating a Privileged User 1335
Running the Computer Setup Wizard 1336
Events Setup page 1336
Security Setup - Control Menu page 1337
Setting Up Instant Trending 1337
Displaying a Project on Multiple Monitors 1338
Implementing Audible Alarms 1338
Creating Pages 1339
Creating new pages 1340
Adding user assistance to a page 1340
Creating Custom Menus 1342
Menu Configuration tool 1342
Building custom menus 1343
Editing an item 1344
Creating an Alarms Group 1345
Creating a Trends Group 1346

26
Contents

Using Environment Variables 1347

27
Contents

28
Getting Started

This section contains information on Full-

ProductNameCitectSCADAv7.40 and describes the following:
Getting Technical Support
What's New in CitectSCADA7.x
Upgrading to CitectSCADA v7.40
About CitectSCADA
Tools
Components of a project
Typical system scenarios

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

Symbol Description

The addition of either symbol to a “Danger” or “Warning” safety

label indicates that an electrical hazard exists which will result in
or personal injury if the instructions are not followed.

This is the safety alert symbol. It is used to alert you to personal

injury hazards. Obey all safety messages that follow this symbol to
avoid possible injury or death.

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.

NOTICE
NOTICE used without a safety alert symbol, indicates a potentially hazardous situation
which, if not avoided, can result in property or equipment 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.

31
Safety Information

Before You Begin

UNINTENDED EQUIPMENT OPERATION

Do not use CitectSCADA or other SCADA software as a replacement for PLC-based control
programs. 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 con-
trol 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 emer-
gency stop and overtravel stop, power outage and restart.
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 Observe all accident prevention regulations and local safety guidelines. 1
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.

1. For additional information, refer to NEMA ICS 1.1 (latest edition) "Safety Guidelines
for the Application, Installation, and Maintenance of Solid State Control", and to NEMA
ICS 7.1 (latest edition) "Safety Standards for Construction and Guide for Selection, Instal-
lation and Operation of Adjustable-Speed Drive Systems" or their equivalent governing
your particular location.

32
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 FullProductNameCitectSCADA, consult the exten-
sive online Help to answer your questions. You can use the Contents list to find the
section you're interested 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 www.schneider-electric.com/citectscada. Upon receipt of your order for a
Maintenance 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
www.schneider-electric.com/citectscada.
If you are unsure of which contact details to use, email: [email protected].

33
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:
www.schneider-electric.com/citectscada

34
Chapter 2: What's New in CitectSCADA 7.x
This section describes new FullProductNameCitectSCADA features and enhancements
for v7.40.

Note: Throughout the documentation, FullProductNameCitectSCADA is referred to

as CitectSCADA

For the purposes of continuity, this section also describes the features that were added
for the CitectSCADA 7.0, 7.10 and 7.20 releases.
Introduced in 7.0
Introduced in 7.10
Introduced in 7.20
Introduced in 7.30
Introduced in 7.40
For details on how to upgrade an existing project to run in v7.40, refer to Upgrading to
7.40.

What's New in CitectSCADA 7.0

CitectSCADA 7.0 incorporates the following new features.
Introduced in 7.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:

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

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.40, refer to Upgrading.
See Also

What's New in CitectSCADA 7.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.

36
Chapter 2: What's New in CitectSCADA 7.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.

Note: This property is no longer available in CitectSCADA 7.20.

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)

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

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

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 in the Cicode Reference Guide
TagUnsubscribe in the Cicode Reference Guide

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.

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

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:
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.Clu- Sets which clusters this Alarm Server process con-

sterName.ServerName] nects to at startup
Clusters

[Alarm.Clu- Sets the CPU that the Alarm Server process is

sterName.ServerName]CPU assigned to

[Alarm.Clu- The list of events that this Alarm Server process ena-
sterName.ServerName]Events bles

[Alarm.Clu- Determines the Cicode function to run when Alarm

sterName.ServerName]Shut- Server process shuts down
downCode

[Alarm.Clu- Determines the Cicode function to run when Alarm

sterName.ServerName]Star- Server process starts up
tupCode

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]Use-
ConfigLimits.
Backup Parameters:

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

default during Backup.

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

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 configured

Citect servers using a network connection.

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

[Client]ShutdownCode Determines the Cicode function to run when DisplayClient

component shuts down.

[Client]StartupCode Determines the Cicode function to run when DisplayClient

component starts up.

[Client]Wait- Specifies that connection to a server will wait until it can estab-
ForConnectAtStartup lish 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]Mis- Specifies how many consecutive scheduled dial attempts can

sedScheduleTolerance be missed before the cache becomes stale

Driver Parameters:

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

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

General Parameters:

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

[General]Mul- Determines whether CitectSCADA runs as a multi-process or

tiprocess single-process application.

IOServer Parameters:

[IOServer.Clu- Sets the clusters that the I/O Server process will
sterName.ServerName]Clusters connect to at startup

[IOServer.Clu- Sets the CPU that the I/O Server process is

sterName.ServerName]CPU assigned to

[IOServer.Clu- The list of events that this I/O Server process ena-
sterName.ServerName ]Events bles

[IOServer.Clu- Determines the Cicode function to run when I/O

sterName.ServerName]Shut- Server process shuts down
downCode

[IOServer.Clu- Determines the Cicode function to run when I/O

sterName.ServerName]Star- Server process starts up
tupCode

Report Parameters:

[Report.Clu- Sets the clusters this Reports Server process will con-
sterName.ServerName]Clusters nect to at startup

[Report.Clu- Sets the CPU that this Reports Server process is

sterName.ServerName]CPU assigned to

[Report.Clu- The list of events that this Reports Server process

sterName.ServerName]Events enables

[Report.Clu- Determines the Cicode function to run when this

sterName.ServerName]Shut- Reports Server process shuts down
downCode

[Report.Clu- Determines the Cicode function to run when this

sterName.ServerName]Star- Reports Server process starts up
tupCode

Trend Parameters:

[Trend.Clu- Sets the clusters this Trends Server process will con-
sterName.ServerName] nect to at startup
Clusters

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

[Trend.Clu- Sets the CPU that the Trends Server process is

sterName.ServerName]CPU assigned to

[Trend.Clu- The list of events that this Trends Server process ena-
sterName.ServerName]Events bles

[Trend.Clu- Determines the Cicode function to run when Trends

sterName.ServerName]Shut- Server process shuts down
downCode

[Trend.Clu- Determines the Cicode function to run when Trends

sterName.ServerName]Star- Server process starts up
tupCode

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:

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

[Code]AlarmShutdown Determines the Cicode function to run when Alarm Server

component shuts down

[Code]AlarmStartup Determines the Cicode function to run when Alarm Server

component starts up

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

[Code]IOServer- Determines the Cicode function to run when I/O Server com-
Shutdown 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

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

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

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

[General]Citec- Checks if a project is currently running on the local machine

tRunningCheck when a compile is triggered

IOServer Parameters:

[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

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

[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

[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

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

Server Parameters:

[Server]Name The name of the CitectSCADA server

Trend Parameters:

[Trend]Block- Verifies that I/O problems causing gaps for a trend tag do not
ByIODevice 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 component

is assigned to

[Trend]Redundancy Enables/disables trend redundancy action

[Trend]Server Determines whether this computer is a Trends Server

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

gerRequestSubgroups requests

Cicode Functions in 7.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.

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

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

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.

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

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.

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

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

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.

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

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

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.

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

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

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.

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.

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

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.

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

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

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.

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

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

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

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

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

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

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.

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

CtAPI Functions in 7.0

The following section details the changes made to CtAPI functions in CitectSCADA 7.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:

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

56
Chapter 2: What's New in CitectSCADA 7.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

What's New in CitectSCADA 7.10

CitectSCADA 7.10 incorporates the following new features.
Introduced in 7.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
l New Alarm Field Enhancements
l New Time Synchronization Service
l New Equipment Database Functions and Forms
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 7.x

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

CitectSCADA Security Enhancements

The CitectSCADA 7.10 release includes changes that are designed to help reduce the
exposure of the product to external security threats. 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 needs to be configured and logged in to CitectSCADA to allow the display proc-
ess 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.[LAN] AllowLegacyConnections. (As part of Citect-
SCADA7.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
Securing Projects

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.

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

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

Note:CitectSCADA supports Microsoft® Office Excel®2013( 32 bit).

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

Enhanced Driver Installation

The installation of CitectSCADA prior to version 7.10 installed the communication driv-
ers automatically with the product. From version 7.10, the installation of these drivers is
performed at the final stage of the product installation using a separate installation proc-
ess. This installation process allows you to select individual drivers that you want to
install, specific to your system and its I/O Devices.

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

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.
From version 7.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
interface. This will allow you to present a more polished and consistent GUI to meet
individual 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.

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

Microsoft Windows Vista Support

CitectSCADA 7.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/Documents and Settings/All Users/Application Data/Schneider Elec-
tric/PowerSCADA Expert 7.xx/ folder. When installed on Windows Vista, configuration
and project files are by default stored in the ProgramData/Citect/CitectSCADA 7.xx/Pro-
gramData/Schneider Electric/PowerSCADA Expert 7.xx/ folder. Install locations are as fol-
lows:

File type Platform Install Path

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

files such as tect/CitectSCADA 7.xx/ConfigDocuments and Settings/All
the citect.ini Users/Application Data/Schneider Electric/PowerSCADA Expert
file 7.xx/Config

Vista ProgramData/Citect/CitectSCADA 7.xx/ConfigPro-

gramData/Schneider Electric/PowerSCADA Expert 7.xx/Config

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

tory tect/CitectSCADA 7.xx/UserDocuments and Settings/All
Users/Application Data/Schneider Electric/PowerSCADA Expert
7.xx/User

Vista ProgramData/Citect/CitectSCADA 7.xx/UserPro-

gramData/Schneider Electric/PowerSCADA Expert 7.xx/User

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

tory tect/CitectSCADA 7.xx/DataDocuments and Settings/All Users/Ap-
plication Data/Schneider Electric/PowerSCADA Expert 7.xx/Data

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

File type Platform Install Path

Vista ProgramData/Citect/CitectSCADA 7.xx/DataPro-

gramData/Schneider Electric/PowerSCADA Expert 7.xx/Data

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

tect/CitectSCADA 7.xx/LogsDocuments and Settings/All
All log files
Users/Application Data/Schneider Electric/PowerSCADA Expert
produced by
7.xx/Logs
drivers are
written to a Vista
sub-folder ProgramData/Citect/CitectSCADA 7.xx/LogsPro-
called 'Driv- gramData/Schneider Electric/PowerSCADA Expert 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").

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

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

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.40 provides the facility to
link alarms with a remote paging system for operators.
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.

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

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 7.10

This topic lists the parameters that have been added or changed in version 7.10 of Citect-
SCADA.
It includes:
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 the Parameters documentation.

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

Alarm Parameters:

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

Code Parameters:

[Code]Hal- When enabled will cause the Cicode to halt when any tag read
tOnInvalidTagData returns invalid data.

Client Parameters:

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

CtApi Parameters:

[CtAPI]Allow- When enabled current version of CTAPI server can accept con-
LegacyConnections nections from previous versions of CTAPI client.

[CtAPI]Allow- When enabled the Citect Web Service and the Citect OLEDB Pro-
LegacyServices vider can connect to the CTAPI server.

DDE Parameters:

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

[DDE] Allows tag writes to the Citect server via the DDE Poke command.
AllowWrites

Kernel Parameters:

[Kernel]Error- The total number of error buffers available for logging to the syslog.dat
Buffers file.

Lan Parameters:

[LAN]Allow- Set to allow previous versions of client to connect to the server.

LegacyConnections

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

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

[LAN]SecureLogin When set to 0 security measures are disabled and the system

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

acts as it did in versions prior to 7.10.

[LAN]Server- Set to disable default server login.

LoginEnabled

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

ODBC Parameters:

[ODBC] Set to enable ODBC connections.

Server

Page Parameters:

[Page]AllowH- Defines the default behavior for horizontal scrolling.

Scroll

[Page]AllowH- Defines the default behavior when displaying horizontal scroll bars.
ScrollBar

[Page]AllowV- Defines the default behavior for vertical scrolling.

Scroll

[Page]AllowV- Defines the default behavior when displaying vertical scroll bars.
ScrollBar

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]Start- Determines the period to wait for I/O Devices to come online before dis-
Timeout playing any data.

Cicode Functions in 7.10

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

New Functions

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

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.

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

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

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 7.20

CitectSCADA v7.40 incorporates the following new features.
Introduced in 7.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
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

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

l Server Side Online Changes

l Microsoft® Windows 7 Support
l Supportability Enhancements
l Tab Menu Templates
l Tag Extensions
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.40, refer to Upgrading to
7.20.
See Also
What's New in CitectSCADA 7.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

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

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

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.

UNINTENDED EQUIPMENT OPERATION

Prior to upgrading to CitectSCADA 7.20, identify and record

Super Genie instance page environment variables. After the
upgrade, reinstate the Super Genie instance page environment
variables.
Otherwise, existing Super Genie template environment variables
will override the variables, due to synchronization.
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.

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

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

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 (refer to the parameter documentation)is

now used to specify the necessary privilege level of a user to perform a shutdown
operation triggered by clicking the Close button of the project (default privilege level
is 8).

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

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 version 7.20
will assist you in finding and fixing design flaws in your project , which may have pre-
viously gone undiscovered due to only being able to run and test your system in single
process 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.40.
The project includes a "What's New?" menu to introduce some of the new features
offered in v7.40. 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.
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.

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

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.40 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.
You can install the OFSOPC Driver and its supporting documentation via the Driver
Selection page of the CitectSCADA v7.40 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.

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

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.

Persisted I/O Memory Mode

With the release of version 7.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. Per-
sistence is enabled using the Persist field in the extended section of the I/O Devices Prop-
erties 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

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

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 version 7.20, you could not load a page if the Cicode library has changed with-
out restarting the display client. In version 7.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

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

CitectSCADA 7.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 support
Windows Vista significantly reduced the changes that were necessary to support Win-
dows 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
Windows 7 from Widows XP be aware of the functional differences with Citect-
SCADAbetween XP and Vista, as described in New Locations for Configuration and
Project Files.

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

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 Easier access to config and project folders.
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
Viewing projects
Configuring logging
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

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

Tag Extensions
With the addition of Tag Extensions in CitectSCADA 7.20, the variable tag can now rep-
resent 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

Citect.ini Parameters in 7.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 entire list of the system param-
eters, refer to the Parameters documentation.
Alarm Parameters

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

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

sterName.ServerName]Dis-
ableConnection

[Alarm.ClusterName.ServerName] Specifies the client priority for the server connection.

Priority

[Alarm]ReloadBackOffTime Back-off time configured to control the pace of the

reload on an alarm server.

Client Parameters

[Client]Auto- When set to 1 the cache is cleared of any client login cre-
LoginClearPassword dentials for consistency with the [Server]Auto-
LoginClearPassword ini parameter.

[Client]DisableDisplay Sets whether to allow the client process to run in the background
without a visible window.

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

evicted.

[Client]Par- Tells a Client process to attempt to authenticate using the stored

tOfTrustedNetwork server password. It is automatically set by the Computer Setup
Wizard.

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

[Client]Stale- Staleness period tolerance

nessPeriodTolerance

CtAPI Parameters

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

ToFormat

CtDraw.RSC Parameters

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

ditSuperGeniePage not to open and edit a Super Genie page.

CtEdit Parameters

[CtEdit]Com- Indicates to the compiler an optional command, script or

pileSuccessfulCommand batch file to execute after a successful compile.

[CtEdit]Com- Indicates to the compiler an optional command, script or

pileUnsuccessfulCommand batch file to execute after an unsuccessful compile.

[CtEdit]Starter Specifies the directory where the starter projects are

located.

Debug Parameters

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

[Debug]Archive- Archives log files once the size specified by [Debug]MaximumFileSize

Files is reached.

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

egoryFilter

[Debug]Cat- Enables logging of categories declared by the [Debug]CategoryFilter

egoryFilterMode value.

[Debug]Ena- Enables or disables the logging mechanism.

bleLogging

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

imumFileSize

[Debug]Priority Allows you to filter logging messages according to their priority.

[Debug]Sever- Allows you to filter logging messages according to their severity.

ityFilter

[Debug]Sever- Enables logging of severities declared by the [Debug]SeverityFilter

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

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

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

[LAN]ReadOnlyLegacyConnections When set to 1 version 7.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

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

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

[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

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

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.

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

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

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.

[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] Determines whetherCitectSCADA will try to block optimize writes to I/O

BlockWrites devices.

Obsolete Parameters
AnmCursor Parameters

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

color of the cursor.

General Parameters

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

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

[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

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

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

cursor color to be specified.

CtAPI Functions in 7.20

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

New Functions

ctListItem Gets the tag element item data.

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

Modified Functions

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

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

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.

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.

86
Chapter 2: What's New in CitectSCADA 7.x

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

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

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

87
Chapter 2: What's New in CitectSCADA 7.x

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.

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.

88
Chapter 2: What's New in CitectSCADA 7.x

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.

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

89
Chapter 2: What's New in CitectSCADA 7.x

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.

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

90
Chapter 2: What's New in CitectSCADA 7.x

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

Logs an operator into the CitectSCADA system. Not available when logged
Login
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.

91
Chapter 2: What's New in CitectSCADA 7.x

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

What's New in CitectSCADA 7.30

CitectSCADA 7.30 incorporates the following new or modified features.
Introduced in 7.30:
l ActiveX Data Objects (ADO.NET)
l Alarm Enhancements
l GUI Enhancements
l Equipment Hierarchy
l Importing Equipment
l New Licensing Method
l OPC DA Server
l Software Update
l Supportability
l Tag Browsing
l Scheduler
For changes to:
l Citect.ini parameters, see Citect.ini Parameters in Version 7.30.
l Cicode functions, see Cicode Functions in Version 7.30.
l CtAPI functions, see CtAPI Functions in Version 7.30.

92
Chapter 2: What's New in CitectSCADA 7.x

For details on how to configure an existing project to run in 7.30 refer to Upgrading to
7.30.
See Also
What's New in CitectSCADA 7.x

ActiveX Data Objects(ADO)

CitectSCADA v7.40 features a new interface between SCADA and your SQL database
using ADO.NET. If your project uses legacy SQL Cicode commands, this is largely hid-
den functionality. The old Cicode commands have the same functionality, they just
achieve their goals in a different way. A number of new Cicode commands have been
introduced in the following categories:
l Creation/connection - functions that separate the creation of DB connection objects
from connection initialization
l Multiple recordsets per connection - functions that enable users to obtain and use
handles to recordsets
l Parameterization - functions that provide a more secure way of building SQL queries
l Multiple queries per connection - functions that enable users to obtain and use han-
dles to queries
See Using Structured Query Language for more information on how to connect to and
interact with SQL databases using the ADO functions. See Cicode Functions in Version
7.30 for new or modified Cicode functions.
In addition there have been some smaller changes. There are two new kernel tables for
database connections and recordsets. An example project page has been included on the
What's New tab to show how ADO functions can be used on a graphics page. There
have also been a few new additions to parameters. See Citect.ini Parameters in Version
7.30 for details.

Alarm Enhancements
There have been numerous improvements made to alarms in CitectSCADA, the notable
improvement being to the alarm server and database with the implementation of run-
time synchronization. Other improvements include:
l Alarm Server Redundancy
l Handling of event information with the introduction of a new sequence of events
page
l Ability to insert a new event into the event journal
l Ability to archive the event journal

93
Chapter 2: What's New in CitectSCADA 7.x

l Ability to create a Named filter and use it across multiple alarm display lists
l Sorting of alarms and events
l New dynamic alarm count at runtime
l User comments on events
l Can configure more than 65535 alarms for each type of alarm
l New alarm template with equipment tree view
Refer to the section Using the Tab Style Page Templates for more information on the new
alarm pages/ templates .
Refer to the topics Alarm Server Upgrade and Migrating Alarm Event History for infor-
mation you need to know before upgrading.
See Also
Using Alarms in SCADA

Equipment Hierarchy
The concept of "equipment" was introduced in 7.20 as a means of providing logical
groupings of SCADA objects such as tags, alarms etc. In the 7.30 release, it has been
expanded to be hierarchical, and to be more closely integrated with the functioning of
SCADA objects.
Each item in the equipment database can be assigned a place in a hierarchy of equip-
ment. The hierarchy is based on the equipment name, and each item of equipment is spe-
cifically identified to signify it's level in the hierarchy.
This provides the opportunity to browse, find, identify and quantify the values of tags
and other objects assigned to a piece of equipment using a number of new or modified
CtAPI and Cicode functions.
See Also
Defining an Equipment Hierarchy

GUI Enhancements
As part of CitectSCADA v7.40 the following enhancements have been made to the GUI:
l The tab style page templates include a new type of alarm page called the sequence of
events page in standard layout or incorporating the equipment tree view. You can
now create active, summary, and disabled pages in standard layout or with the equip-
ment tree-view.
l New library_controls include project. This project contains a series of genies you can
use in your graphic pages, such as tables, equipment tree-view panel, horizontal and
vertical scroll bars.

94
Chapter 2: What's New in CitectSCADA 7.x

l Enhanced grid control.

l The starter projects have been updated to use the equipment tree-view layout instead
of the standard layout templates.
Refer to the sections Tab Style Templates and Using the Library Controls Include Project
for additional information .
See Also
Using Alarms in SCADA

Importing Equipment
The concept of creating hierarchies of equipment has been introduced in 7.30 to provide
a way of browsing, finding, identifying and quantifying the values of tags and other
objects assigned to a piece of equipment.
In addition, equipment tags can be created by importing them in much the same way as
tags can be imported using TagGen. An XML template is used to specify the fields of
input and output databases, and define filters and transformation rules that create tags
from existing database fields.
The Update Equipment tool is used to update the equipment configuration based on
predefined templates.
See Also
Importing Equipment Using XML Templates

95
Chapter 2: What's New in CitectSCADA 7.x

Both the existing SafeNet licensing method and the new FLEXERA method now contain
the following features:
l Separate licensing for drivers used for importing tags, such as SpeedLink and Fas-
Linx is no longer required.
l There is no longer a distinction between Control Client or View-Only Client and their
web counterparts Internet Control Client or Internet View-Only Client.
For further information on the new licensing method, refer to Independent Point Count.
See Also
CiUSAFE dialog properties
Demo mode
Dynamic-point count licensing

Using an OPC DA Server

OPC (OLE for Process Control) is a set of communication standards maintained by the
OPC Foundation for the industrial automation industry. OPC provides a common plat-
form for applications to share data from typically disparate sources, such as PLCs and
databases, without the need to comprehend native protocols.
The OPC Data Access solution (OPC DA) provides specifications for client and server
applications that are focused on the continuous communication of real-time data. To this
end, CitectSCADA supports a runtime OPC DA server that implements the mandatory
OPC DA v2.05 and OPC DA v3 interface specifications.
This allows CitectSCADA to provide real-time data to any compliant OPC DA clients,
including applications such as AMPLA, OSI-PI and Historian.
In order to allow OPC DA Server to be accessed by the OPC DA Clients, the OPC DA
Server process must be configured in the SCADA project. This behavior is different to
releases 7.20 and earlier where no configuration step was required.

Note:
• The OPC DA Server does not fully support WriteVQT functionality, as a Citect-
SCADA I/O server does not allow quality and timestamp changes that are generated
from an external source.
• Connecting a CitectSCADA OPC DA client to an CitectSCADA OPC DA server is
not recommended, as the client was not designed to be used in this way. This mode
of operation has not been validated.

To determine which OPC DA interfaces are supported by the CitectSCADA OPC DA

Server, see the topic Supported OPC DA Server Interfaces in the reference section of this
chapter.

96
Chapter 2: What's New in CitectSCADA 7.x

See also
Configuring the OPC DA Server
Operating the OPC DA Server at runtime
OPC DA Server diagnostics
Reference Information

Schneider Electric Software Update

Schneider Electric Software Update is a software tool that has been designed to provide
the latest news and updates of Schneider Electric software.
You can adapt it to your individual requirements by:
l Configuring it to check for only those Schneider Electric software updates that you
are really interested in, even from PCs other than where any of your Schneider Elec-
tric software products are installed.
l Scheduling the intervals it checks for updates according to your needs
The Schneider Electric Software Update scheduler is automatically started as a Windows
Service with every start of your PC. It runs unobtrusively in the background.
The activation of the Schneider Electric Software Update application may be performed
in 3 different ways:
l Automatic start every time the scheduled period for checks has passed
l Manual start by the Start menu or the Schneider Electric Software Update shortcut on
the desktop
l By means of an installed Schneider Electric software: this can also performed auto-
matically, with every start of the software.

Supportability Enhancements
Further Supportability Enhancements have been added to CitectSCADA to harmonize
logging features of the product. Although the enhancements were primarily introduced
to assist Technical Support personnel with system analysis, they have resulted in many
benefits to the end user. These include:
l Separation of file logging from Drivers. Drivers will now progressively updated to
log to the SYSLOG.DAT file rather than a separate driver log. This may mean that
your SYSLO.DAT file may require to have its maximum size adjusted.
l A server Cicode function ServerDumpKernel() has been added to allow dumping ker-
nel data on a server process.
l A new column has been added to the CSAtoPSI kernel table indicating the number of
changes on a tag.

97
Chapter 2: What's New in CitectSCADA 7.x

l Logs are now available from PSItoCSA and PSIClient sub-systems.

l There is now the ability to enable /disable counters in various subsystems by adding
an INI parameter which lists the counter categories to be enabled.
l The timestamp format of the logs in RuntimeManager.log has been made consistent
with syslog.

Tag Browsing
You can now browse a list of variable tags owned by data sources at runtime. You can
also browse selected runtime and configuration fields of the tag via Cicode and CtApi,
and while browsing you can apply a filter using a set of predefined field names using
regular expressions.
See Also
Tag Browsing

Scheduler
The Scheduler is a calendar based programming tool that allows you to manipulate tag
values within a CitectSCADA project. It can be used to create a sequence of auto-
matically executed commands, delivering a valuable scheduling tool for applications.
See Also
Using Scheduler

Citect.ini Parameters in 7.30

This topic lists the parameters that have been added or changed in version 7.30 of Citect-
SCADA.

New Parameters

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

[Alarm]DefaultSOETimeRange Specifies the default time range, in days, for SOE views that
have no other time-based filter.

[Alarm]DefSOEFmt Specifies an SOE display format to use if the SOE Display

Format field is blank (in Alarm Categories).

[AlarmFilterRuleList.Active] Defines the name of rules to appear on the Simple Rule drop-
Rule<n> down list of the active alarm filter form.

98
Chapter 2: What's New in CitectSCADA 7.x

[AlarmFilterRuleList.Disabled] Defines the name of rules to appear on the Simple Rule drop-
Rule<n> down list of disabled alarm filter form.

[AlarmFilterRuleList.SOE] Defines the name of rules to appear on the Simple Rule drop-
Rule<n> down list of alarm summary filter form.

[AlarmFilterRuleList.Summary] Defines the name of rules to appear on the Simple Rule drop-
Rule<n> down list of alarm summary filter form.

[AlarmFilterRules]<Rule- Defines the filter expression represented by the rule name.

Name>

AlarmFilterRuleList].Rule<n> Defines the name of the common rules to appear on the Sim-
ple Rule dropdown list of all alarm filter form.

AlarmFilterRules Parameters

[AlarmFilterRuleList.Active] Defines the name of rules to appear on the Simple Rule drop-
Rule<n> down list of the active alarm filter form.

[AlarmFilterRuleList.Disabled] Defines the name of rules to appear on the Simple Rule drop-
Rule<n> down list of disabled alarm filter form.

[AlarmFilterRuleList.SOE] Defines the name of rules to appear on the Simple Rule drop-
Rule<n> down list of alarm summary filter form.

[AlarmFilterRuleList.Summary] Defines the name of rules to appear on the Simple Rule drop-
Rule<n> down list of alarm summary filter form.

[AlarmFilterRules]<Rule- Defines the filter expression represented by the rule name.

Name>

AlarmFilterRuleList].Rule<n> Defines the name of the common rules to appear on the Sim-
ple Rule dropdown list of all alarm filter form.

Alarm Process Parameters

Alarm.<ClusterName>.<ServerName> ArchiveAfter The archive after time

(Event Journal) is the
amount of time between
each archive of Event Jour-
nal data.

Alarm.<ClusterName>.<ServerName> CacheSize Defines the amount of

memory (in megabytes)
dedicated to the storage of
event data.

Alarm.<ClusterName>.<ServerName> ClientConnectTimeout Defines the amount of

time, in milliseconds, in
which the client can
attempt to make a con-
nection.

Alarm.<ClusterName>.<ServerName> Client- Defines the amount of

DisconnectTimeout time, in milliseconds, in
which the client can

99
Chapter 2: What's New in CitectSCADA 7.x

attempt to terminate a con-

nection to the server.

Alarm.<ClusterName>.<ServerName>ClientRequestTimeout Defines the amount of

time, in milliseconds, in
which the client can
request data from a server.

Alarm.<ClusterName>.<ServerName> FutureMessages Event Journal records that

have a time stamp with a
date and time in the future
can be stored historically.

Alarm.<ClusterName>.<ServerName> HeartbeatTimeout Defines how long a server

will wait before terminating
a link that has been used
for receiving heartbeat poll
requests from its pair
server, but is currently
idle.

Alarm.<ClusterName>.<ServerName> KeepOnlineFor The Event Journal Life is

the amount of time for
which the Alarm Server
stores event messages on-
line.

Alarm.<ClusterName>.<ServerName> MonitorConnectTimeout Defines the amount of

time, in seconds, that the
server will wait for a mon-
itor connection to occur.

Alarm.<ClusterName>.<ServerName> MonitorRequestTimeout Defines the amount of

time, in seconds, that the
server will wait for a
response from the other
server in the pair.

Alarm.<ClusterName>.<ServerName>QueryCPUUsage Defines the percentage of

processor use you want to
allocate to query searches.

Alarm.<ClusterName>.<ServerName> QueryRowLimit Defines the maximum

number of rows that can
be returned in the result
set for a single query.

Alarm.<ClusterName>.<ServerName>QueryTimeout Defines the amount of time

(in seconds) that is per-
mitted for query searches.

Alarm.<ClusterName>.<ServerName> StreamSize Defines the amount of data

that is included in each
event data file.

Alarm.<ClusterName>.<ServerName> SyncAllHistoricData On multi-server systems,

the Primary server and

100
Chapter 2: What's New in CitectSCADA 7.x

Standby server syn-

chronize their data so that
the Standby server con-
tains an accurate, up to
date backup of the Primary
server’s data.

Alarm.<ClusterName>.<ServerName>TransferConnectTimeout Defines the amount of

time, in seconds, that the
Primary server will wait for
a connection to occur.

Alarm.<ClusterName>.<ServerName> TransferInterleave Controls how often the data

synchronization is trig-
gered by the Primary to the
Standby Server.

Alarm.<ClusterName>.<ServerName>TransferInterval Defines the number of sec-

onds between each
attempt to update the data
on the Standby server.

BrowseTableView Parameters

[BrowseTableView]<BrowseType>.<ViewName>.ColWidths Sets the column widths in

pixels of the current data
browse table.

[BrowseTableView]<BrowseType>.<ViewName>.Fields Sets the field names of the

columns in the current
data browse table under
the View Name configured
on the page.

ClientParameters

[Client]PointCountRequired Specifies what license point count a client

requires.

General Parameters

[General]ClusterReplication Controls whether tag will be replicated in

a multi-cluster system.

[General]LicenseReservationTimeout Specifies the number of seconds to

reserve a license for a given IP address in
cases where a remote client connection is
lost.

Page Parameters

[Page]SOE- The name of the graphics page to display when you call up an sequence of
Page events (SOE) page via the Cicode function PageSOE().

SQL Parameters

101
Chapter 2: What's New in CitectSCADA 7.x

[SQL]Max- Defines the maximum number of DB connection objects.

Connections

Scheduler Parameters

[Scheduling]Per- Directs where the configuration data for the scheduler is stored.
sistPath

[Scheduling] Sets the delay from when the Scheduler’s server components are initial-
StartDelay ized to the point when Scheduler begins processing active schedule
entries.

Modified Parameters

Alarm Parameters

[Alarm]SaveP- This parameter is now used only to import alarm history from previous ver-
rimary sions of CitectSCADA.

[Alarm]Save- This parameter is now used only to import alarm history from previous ver-
Secondary sions of CitectSCADA.

[Alarm]Sum- The maximum number of alarm summary entries that can be held in mem-
maryLength ory. The maximum number for this parameter has been modified from
4096000 to 100000.

Language Parameters

Language]LocalLanguage Used to set the default language during start-up.

SQL Parameters

[SQL]Que- Sets the timeout period for SQL queries globally.

ryTimeout

Tab Style Template Parameters

[Format]For- Define the display format by name.

matName

Re-instated Parameters

None

Obsolete Parameters

[Alarm]Ack Determines whether CitectSCADA acknowledges current alarms on

startup.

[Alarm]Fil- If privilege is not checked, a user with no privilege (0) can browse and

102
Chapter 2: What's New in CitectSCADA 7.x

terViewByPrivilege view trends and alarms that require privilege 1. The v7.40 behavior is
the same as [Alarm]FilterViewByPrivilege = 0 in 7.20.

[Alarm]SavePe- Set the path to the primary save file.

riod

[Alarm]SaveStyle Determines whether alarms records are identified by their record

number or alarm tag.

[Alarm]StartTimeout Sets the timeout period for loading data from the primary Alarms
Server.

Intl Parameters

[Intl]s1159 If a 12 hour clock is set (see [Intl]iTime), this parameter sets the format of
the morning extension.

[Intl]s2359 If a 12 hour clock is set (see [Intl]iTime), this parameter sets the format of
the evening extension.

CtAPI Functions in 7.30

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

New Functions

ctFindNumRecords Get the number of records for a given browsing session

Modified Functions

CtFindFirst Searches for the first object in the specified table, device, trend, tag, or
alarm data which satisfies the filter string. Now accepts "Equipment" as
an argument.

CtFindFirstEX Performs the same as ctFindFirst, but with an additional new argument.
Now accepts "Equipment" as an argument.

Retrieves an object property or meta data for an object. Now accepts

CtGetProperty
"Equipment" as an argument.

Obsolete Functions

None

103
Chapter 2: What's New in CitectSCADA 7.x

Cicode Functions in 7.30

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

AlarmAckTag Acknowledge a specified alarm.

AlarmCount Counts the available alarms for the selected filter criteria.

AlarmCountList Counts the available alarms for the selected alarm list (selected by
its animation).

AlmBrowseAck Acknowledges the alarm tag at the current cursor position in an

active data browse session.

AlmBrowseClose Closes an alarm tags browse session.

AlmBrowseDisable Disables the alarm tag at the current cursor position in an active
data browse session.

AlmBrowseEnable Enables the alarm tag at the current cursor position in an active
data browse session.

AlmBrowseFirst Gets the oldest alarm tags entry.

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

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

AlmBrowseNumRecords Returns the number of records in the current browse session.

AlmBrowseOpen Opens an alarm tags browse session.

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

AlarmFilterClose Removes named filter from memory.

AlarmFilterEditAppend Appends the provided expression to the current filter session con-
tent without any validation.

AlarmFilterEditClose Removes the session from the memory.

AlarmFilterEditCommit Validates the filter built in this session and, if valid, applies the
filter to the list associated with the session.

AlarmFilterEditFirst Retrieves the first part of the filter.

AlarmFilterEditLast Retrieves the last part of the filter.

AlarmFilterEditNext Retrieves the next part of the filter.

104
Chapter 2: What's New in CitectSCADA 7.x

AlarmFilterEditOpen Creates a session for the historical list associated with the provided
animation number (aN).

AlarmFilterForm Displays a form for specifying filtering criteria for either an alarm
list or a named filter.

AlarmFilterOpen Creates a named filter.

AlmFilterEditPrev Retrieves the previous part of the filter.

AlmFilterEditSet Replaces the current filter session content by the provided expres-
sion without any validation.

AlarmGetFilterName Retrieves the name of the linked filter for the supplied AN.

AlarmResetQuery Clears the filter of the specified filter source. Used to reset the filter
set up by the Cicode function AlarmFilterForm().

LibAlarmFilterForm Displays a generic alarm filter pop-up for specifying filtering crite-
ria for either an alarm list or a named filter.

Equipment Functions

EquipSetProperty Sets the property of an item of equipment.

EquipStateBrowseClose Terminates a browsing session and cleans up the resources

used by the session.

EquipStateBrowseFirst Places the data browse cursor at the first record.

EquipStateBrowseGetField Returns the value of the particular field in a record to which

the data browse cursor is currently referencing.

EquipStateBrowseNext Places the data browse cursor at the next available record.

EquipStateBrowseNumRecords Returns the number of records that match the current filter
criteria.

EquipStateBrowseOpen Initiates a new session for browsing the equipment states

configured.

EquipStateBrowsePrev Places the data browse cursor at the previous record.

Page Functions

PageSOE Displays a category of sequence of events (SOE) entries on the SOE page.

Scheduler Functions

SchdClose Terminates a browsing session and cleans up the resources

used by the session.

SchdConfigClose Terminates a browsing session and cleans up the resources

used by the session.

SchdConfigFirst Places the data browse cursor at the first record.

SchdConfigGetField Returns the value of the particular field in a record to which

105
Chapter 2: What's New in CitectSCADA 7.x

the data browse cursor is currently referencing.

SchdConfigNext Places the data browse cursor at the next available record.

SchdConfigNumRecords Returns the number of records that match the current filter
criteria.

SchdConfigOpen Initiates a new session for browsing the schedules con-

figured.

SchdConfigPrev Places the data browse cursor at the previous record.

SchdFirst Places the data browse cursor at the first record.

SchdGetField Returns the value of the particular field in a record to which

the data browse cursor is currently referencing.

SchdNext Places the data browse cursor at the next available record.

SchdNumRecords Returns the number of records that match the current filter
criteria.

SchdOpen Initiates a new session for browsing the runtime schedules.

SchdPrev Places the data browse cursor at the previous record.

SchdSpecialAdd Adds a new special day group to the scheduler engine.

SchdSpecialClose Terminates a browsing session and cleans up the resources

used in the session.

SchdSpecialDelete Deletes an existing special day group.

SchdSpecialFirst Places the data browse cursor at the first record.

SchdSpecialGetField Returns the value of the particular field in a record to which

the data browse cursor is currently referencing.

SchdSpecialItemAdd Adds a new special day to the scheduler engine.

SchdSpecialItemClose Terminates a browsing session and cleans up the resources

used in the session.

SchdSpecialItemDelete Deletes an existing schedule.

SchdSpecialItemFirst Places the data browse cursor at the first record.

SchdSpecialItemGetField Returns the value of the particular field in a record to which

the data browse cursor is currently referencing.

SchdSpecialItemModify Modifies an existing special day.

SchdSpecialItemNext Places the data browse cursor at the next available record.

SchdSpecialItemNumRecords Returns the number of records that match the current filter
criteria.

SchdSpecialItemOpen Initiates a new session for browsing the special days.

SchdSpecialItemPrev Places the data browse cursor at the previous record.

106
Chapter 2: What's New in CitectSCADA 7.x

SchdSpecialModify Modifies an existing special day group

SchdSpecialNext Places the data browse cursor at the next available record.

SchdSpecialNumRecords Returns the number of records that match the current filter
criteria.

SchdSpecialOpen Initiates a new session for browsing the special day groups.

SchdSpecialPrev Places the data browse cursor at the previous record.

ScheduleItemAdd Adds a new schedule to the scheduler engine.

ScheduleItemDelete Deletes an existing schedule.

ScheduleItemModify Modifies an existing schedule.

ScheduleItemSetRepeat Adds recurrence information for an existing schedule to the

scheduler engine.

Sequence of Event Functions

SOEArchive Archives event journal.

SOEDismount Use to dismount archive volume.

SOEEventAdd Inserts a new event into the event journal.

SOEMount Use to mount archive volume.

SQL Functions

SQLCall Executes an SQL query on a database

SQLClose Closes a SQL connection between the DB connection object specified

by the function’s parameter and a database

SQLCreate Creates an internal DB connection object and returns a handle to the

object for use by the other DB functions

SQLDispose Disposes the DB connection object

SQLGetRecordset Executes an SQL query on a database

SQLGetScalar Executes an SQL query on a database

SQLIsNullField Checks presence of null value in field from a recordset

SQLNumFields Gets the number of fields or columns that were returned by the last
SQL statement

SQLOpen Opens an SQL connection between the DB connection object

SQLParamsClearAll Turns on a debug trace

SQLParamsSetAsInt Adds or replaces a parameterized query’s parameter as integer and

its value in the specified connection

SQLParamsSetAsReal Adds or replaces a parameterized query’s parameter as real and its

107
Chapter 2: What's New in CitectSCADA 7.x

value in the specified connection

SQLParamsSetAsString Adds or replaces a parameterized query’s parameter as string and

its value in the specified connection

SQLPrev Gets the previous database record from an SQL query.

SQLQueryCreate The function creates a new query and returns its handle

SQLQueryDispose The function disposes the query which handle is given as the argu-
ment

SQLRowCount Gets the number of rows in the recordset.

Timestamp Functions

StrToTimestamp Converts timestamp in a STRING format into a TIMESTAMP format

Tag Functions

TagBrowseClose Close an existing browsing session

TagBrowseFirst Move to the first record

TagBrowseGetField Get the specified field of a record.

TagBrowseNext Move to the next record

TagBrowseNumRecords Get the number of records for a given browsing session.

TagBrowseOpen Opens a new browsing session.

TagBrowsePrev Move to the previous record

Modified Functions

Alarm Functions

AlarmAck Acknowledges an active alarm.

AlarmCatGetFormat Returns the display format string of the specified alarm cat-
egory.Type has been extended to include SOE format.

AlarmDisable Disables an alarm.

AlarmDsp Displays alarms.

AlarmDspNext Displays the next page of alarms.Works with new SOE display type.

AlarmDspPrev Displays the previous page of alarms.Works with new SOE display
type.

AlarmEnable Enables a disabled alarm.

AlarmFirstTagRec Alarm 'Rec' functions listed are now executed in the client process,
AlarmFirstCatRec with the function MsgRPC no longer required when called remotely
AlarmFirstPriRec to the Alarm Server.

108
Chapter 2: What's New in CitectSCADA 7.x

AlarmFirstQueryRec
AlarmNextTagRec
AlarmNextCatRec
AlarmNextPriRec
AlarmNextQueryRec
AlarmAckRec
AlarmEnableRec
AlarmDisableRec
AlarmGetDelayRec
AlarmSetDelayRec
AlarmGetThresholdRec
AlarmSetThresholdRec
AlarmGetFieldRec

AlarmGetDsp Retrieves field data from the alarm record that is displayed at the
specified AN. Works with new SOE display type.

AlarmGetInfo Retrieves data on the alarm list displayed at a specified AN. New
type 12 added.

AlarmSetInfo Controls different aspects of the alarm list displayed at a specified

AN. Supports automatic refresh of the new SOE display type.

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

AlmSummaryOpen Opens an alarm summary browse session. Now supports Equipment

field.

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

Opens an alarm tags browse session. Now supports Equipment

AlmTagsOpen
field.

Accumulator Functions

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

AccumBrowseOpen Opens an accumulator browse session. Now supports Equipment

field.

Equipment Functions

EquipBrowseGetField Gets the field indicated by the cursor position in the browse session.
Now supports Parent and Composite fields.

EquipBrowseOpen Opens an equipment database browse session. Now supports Parent

and Composite fields.

EquipGetProperty Reads a property of an equipment database record from the

EQUIP.DBF file. Now supports Parent and Composite fields.

Format Functions

FmtOpen Opens a format template. mode has been extended to include SOE format.

109
Chapter 2: What's New in CitectSCADA 7.x

Security Functions

Login Logs a user into the CitectSCADA system, using CitectSCADA security and
gives users access to the areas and privileges assigned to them in the
Users database. New sLanguage parameter added.

UserLogin Logs a user into the CitectSCADA system, using either Windows security
or CitectSCADA security and gives users access to the areas and privileges
assigned to them in the Users database. New sLanguage parameter
added.

Server Functions

ServeGetProperty Returns information about a specified server and can be called from any
client.

ServerReload Reloads the server specified by cluster and server name.

Super Genie Functions

AssGetProperty Gets association information about the current Super Genie from the data-
source.

AssInfo Gets association information about the current Super Genie.

AssInfoEx Gets association information about the current Super Genie.

SQL Functions

SQLGetField Gets field or column data from a database record.

SQLInfo Gets information about a database connection.

SQLNoFields Gets the number of fields or columns that were returned by the last SQL
statement.

Tag Functions

TagGetProperty Gets a property for a variable tag from the datasource. Now supports
Equipment field.

TagInfo Gets information about a variable tag. Now supports Equipment field.

TagInfoEx Gets information about a variable tag. Now supports Equipment field.

Trend Functions

TrnBrowseGetField Gets the field indicated by the cursor position in the browse session.
Now supports Equipment field.

TrnBrowseOpen Opens a trend browse session. Now supports Equipment field.

Reinstated Functions

No functions have been reinstated for 7.30.

Deprecated Functions

110
Chapter 2: What's New in CitectSCADA 7.x

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

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

AlmTagsAck Acknowledges the alarm tag at the current cursor position in an active
data browse session.

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

AlmTagsClose Closes an alarm tags browse session.

AlmTagsFirst Gets the oldest alarm tags entry.

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

AlmTagsNumRecords Returns the number of records in the current browse session.

AlmTagsOpen Creates a session for the historical list associated with the provided
animation number (aN).

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

Removed Functions

AlmBrowseClear Clears the alarm tag at the current cursor position in

an active data browse session. Now obsolete.

AlarmClear Clears acknowledged, inactive alarms from the active

alarm list.

AlarmClearRec Clear an alarm by its record number. Now obsolete.

AlarmDelete Deletes alarm summary entries that are currently dis-

played. Now obsolete.

AlarmSetQuery Specifies a query to be used in selecting alarms for dis-

play. Now Obsolete. Use the new Alarm Filter Edit func-
tions.

AlarmSumAppend Appends a new blank record to the alarm summary.

Now obsolete.

AlarmSumCommit Commits the alarm summary record to the alarm sum-

mary device. Now obsolete.

AlmSummaryCommit Commits the alarm summary record to the alarm sum-

mary device. Now obsolete.

AlarmSplit Duplicates an alarm summary entry where the cursor

is positioned. Now obsolete.

111
Chapter 2: What's New in CitectSCADA 7.x

AlarmSumDelete Deletes alarm summary entries. Now obsolete.

AlarmSumFind Finds an alarm summary index for an alarm record and

alarm on time. Now obsolete.

AlarmSumFindExact Finds the alarm summary index for an alarm specified

by the alarm record identifier and alarm activation
time.

AlarmSumFirst Gets the oldest alarm summary entry. Now obsolete.

AlarmSumGet Gets field information from an alarm summary

entry. Now obsolete.

AlarmSumLast Gets the latest alarm summary entry. Now obsolete.

AlarmSumNext Gets the next alarm summary entry. Now obsolete.

AlarmSumPrev Gets the previous alarm summary entry. Now obso-

lete.

AlarmSumSet Sets field information in an alarm summary entry.

Now obsolete.

AlmSummarySetFieldValue Sets the value of the field indicated by the cursor posi-
tion in the browse session. Now obsolete.

AlarmSumSplit Duplicates an alarm summary entry. Now obsolete.

AlarmSumType Retrieves a value that indicates a specified alarm's

type. Now obsolete.

QueryFunction The user-defined query function set in AlarmSetQuery.

Now obsolete.

Miscellaneous Functions

SetLanguage Sets the language database from which the local translations of native
strings in the project will be drawn, and specifies the character set to be
used. Now obsolete. Use the Login(), UserLogin() and LoginForm() to set
the preferred language.

What's New in CitectSCADA 7.40

CitectSCADA 7.40 incorporates the following new or modified features.

112
Chapter 2: What's New in CitectSCADA 7.x

Note: Throughout the documentation, FullProductNameCitectSCADAis referred to as

CitectSCADA

Introduced in 7.40:
l Referencing a variable tag using Equipment.Item
l New Cicode functions to maintain a list of unique Pages "opened"
l New Equipment Editor
l New StruxureWare Templates
l OPC Factory Server (OFS) Security Updates
For changes to:
l Citect.ini parameters, see Citect.ini Parameters in Version 7.40.
l Cicode functions, see Cicode Functions in Version 7.40.
l CtAPI functions, see CtAPI Functions in Version 7.40.
For details on how to configure an existing project to run in 7.40 refer to Upgrading to
7.40.
See Also
What's New in CitectSCADA 7.x

Referencing a variable tag using Equipment.Item

In 7.40 you can now reference a variable tag using associated equipment and item (with
the equipment.item syntax). Known as object based referencing you can create true object
libraries with matching graphics and database components.
This means you can:
l Use equipment.item in place of variable tags in all expression fields in graphic pages.
l Use equipment.item to reference variable tags in Genie and Super Genie sub-
stitutions.
l Used equipment.item in the value field to represent a variable tag when associating
super genie substitutions via metadata.
l Pass equipment.item to Cicode functions in which the variable tag name is an argu-
ment.
l Pass equipment.item to CTAPI functions in which the variable tag name is an argu-
ment.

113
Chapter 2: What's New in CitectSCADA 7.x

Note: Only variable tags (and not Alarm or trend tags) can be referenced using Equip-
ment.Item syntax.

Tag Referencing as Strings

Variable Tag Properties

New Cicode functions to maintain a list of unique Pages "opened"

In 7.40, in addition to page history, a new type of page tracking, dubbed called a page
list, has been introduced to keep track of unique a list of unique pages that have been vis-
ited in a window. When a page is displayed, either via normal display, super genie dis-
play or with the Cicode PageTask() function, it will be checked against pages that are
have been already visited on in this window. If the page has not been visited, the param-
eters to display this the page will beare added to the page list. Once a page is in the list,
it can be recalled using Cicode functions.
The new Cicode functions have been added so you can:
l Iterate through pages stored in the list.
l Retrieve information of page stored in the list
l Remove a page from the list
l Recall a page stored in the list
See Also
Cicode Functions in v7.40

Equipment Editor Interface

In 7.40 you can add equipment types, create instances of equipment based on equipment
types, and edit and delete equipment in the equipment hierarchy in your projects using
the new equipment editor interface. With the equipment editor you no longer need to
write XML. Changes made are saved directly to the XML template. Equipment Instances
that are created are saved to the EQUIP.DBF.

Understanding Equipment in SCADA

New StruxureWare Templates

New StruxureWare templates have been included for use in StruxureWare designed sys-
tems. These are wide screen only and the new look and feel is consistent with other
StruxureWare products, assisting the operator when moving between applications.

114
Chapter 2: What's New in CitectSCADA 7.x

OPC Factory Server (OFS) Security Update

Schneider Electric® has become aware of a possible vulnerability related to XML Exter-
nal Entity (XXE) processing in CitectSCADA and OFS.
The vulnerability identified could lead to the disclosure of confidential information by
allowing access to local resources (files and internal resources) or have other system
impacts (e.g Denial of Service).
This vulnerability was discovered during cyber security research both by an external
researcher and by Schneider Electric internal investigations. There is no evidence that
this vulnerability has been exploited; however to address this vulnerability you need to
manually copy and paste selected files (listed below) depending on what is installed on
your machine.
l The OFS 3.40 Server and Configuration tool should be installed. (Optional OPC-UA
wrapper)
l If OFS3.40 is installed, the LARGE\Server folder content should be copied to the x:\P-
rogram Files\Schneider Electric\OFS\Server folder .
l The OFSConf folder content should be copied to the x:\Program Files\Schneider Elec-
tric\OFS\OFSConf folder. Archive the current OFS configuration before copying the
OFSConf folder.
l If UNITY PRO is not installed or if UNITY PRO with version < 6.0 is installed, the
SRCSDK51 folder content should be copied to C:\Program Files\Common
Files\Schneider Electric Shared\SRCSDK folder.
l If UNITY PRO with version >= 6.0 is installed, the SRCSDK60 folder content should
be copied to the C:\Program Files\Common Files\Schneider Electric
Shared\SRCSDK folder.
l If OPC-UA wrapper is installed, OPCUA folder content should be copied to the x:\P-
rogram Files\Schneider Electric\OFS\OPCUA folder.

Citect.ini Parameters in 7.40

This topic lists the parameters that have been added or changed in version 7.30 of Citect-
SCADA.

New Parameters

The following parameters are new in version 7.40 . For an entire list of the system param-
eters, refer to the Parameters documentation.

115
Chapter 2: What's New in CitectSCADA 7.x

CTEdit Parameters

[CTEDIT]DisplayEquipmentItem Used to control the population of the var-

iable tag list, or equipment item list in
graphics builder.

General Parameters

[General]TagDBReloadOnChange Determines whether the Variable Tags

database is checked for changes and
reloaded when a new page is displayed.

Page Parameters

[Page]MaxList The maximum number of pages that can

be placed on the page list stack.

Server Parameters

[Server]AllowAnonymousAccess Determines whether the EWS Server will

allow the EWS Client anonymous data
access.

Modified Parameters

Code Parameters

[Code]Stack The size of the Cicode stack. The default

has been changed from 127 to 256.

General Parameters

[General]TagDB Determines whether the Variable Tags

database is loaded at runtime. The Var-
iable Tags database needs to be loaded to
allow tags to be referenced with the Equip-
ment.Item syntax.

Obsolete Parameters

Cicode Functions in 7.40

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

New Functions

Page Functions

116
Chapter 2: What's New in CitectSCADA 7.x

PageListCount Gets number of pages in the page list of the current window.

PageListCurrent Gets index of the current page in the page list of the current window.

PageListInfo Gets information of a page at the specific index in the page list of current
window.

PageListDisplay Displays a page at the specific index in the page list of the current win-
dow, and moves the current index to the page. When a page is recalled,
the original parameters (such as cluster context, super genie asso-
ciations, PageTask arguments if applicable) used to display the page will
be restored.

PageListDelete Deletes a page at the specific index from the page list of the current win-
dow.

XML Functions

XMLClose Deletes an XML document in memory

XMLCreate Creates a new XML document in memory

XMLGetAttribute Retrieves the attribute value of the node from an XML doc-
ument in memory

XMLGetAttributeCount Retrieves the number of attributes (properties of a node.

Each attribute has a name and a value) within an XML doc-
ument in memory

XMLGetAttributeName Retrieves the name of an attribute (property of a node.

Each attribute has a name and a value) within an XML doc-
ument in memory

XMLGetAttributeValue Retrieves the value of an attribute (property of a node.

Each attribute has a name and a value) within an XML doc-
ument in memory

XMLGetChild Retrieves the child node for the specified parent node in
XML document in memory

XMLGetChildCount Retrieves the total number of child nodes for the specified
parent node in an XML document in memory

XMLGetParent Retrieves the parent node within the contents of an XML

document in memory

XMLGetRoot Retrieves the root node of an XML document in memory

XMLNodeAddChild Creates an element node with the specified Name and

Namespace and appends the node to the end of the list of
child nodes of specified parent node in the XML doc-
ument.

XMLNodeFind Selects a single node from the contents of an XML doc-

ument in memory

XMLNodeGetName Retrieves the name of the specified node

XMLNodeGetValue Retrieves the value of a node from the contents of an XML

117
Chapter 2: What's New in CitectSCADA 7.x

document in memory

XMLNodeRemove Removes specified XML node from its parent and XML doc-
ument

XMLNodeSetValue Sets the value of the specified node.

XMLOpen Loads an XML file from disk

XMLSave Saves an XML file to disk

XMLSetAttribute Sets the value of specified attribute of the node in the XML
document. If the attribute does not exist, it will be
created.

Modified Functions

Super Genie Functions

Associates a variable tag with a Super Genie. Now supports Equip-

Ass
ment.Item.

Tag Functions

TagGetProperty Gets a property for a variable tag from the datasource. Now sup-
ports Equipment.Item.

TagGetScale Gets the value of a tag at a specified scale from the datasource.
Now supports Equipment.Item.

TagInfo Gets information about a variable tag. Now supports Equip-

ment.Item.

TagInfoEx Gets information about a variable tag. Now supports Equip-

ment.Item.

TagRead Reads a variable from the I/O device. Now supports Equip-
ment.Item.

TagReadEx Reads the value, quality or timestamp of a particular tag from the
I/O device. Now supports Equipment.Item.

TagResolve Used to increment a reference count on a tag to keep it resolved,

making it readily available to a client. Now supports Equip-
ment.Item.

TagScaleStr Gets the value of a tag at a specified scale. Now supports Equip-
ment.Item.

TagSetOverrideBad Sets a quality Override element for a specified tag to Bad Non Spe-
cific. Now supports Equipment.Item.

TagSetOverrideGood Sets a quality Override element for a specified tag to Good Non
Specific. Now supports Equipment.Item.

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

Non Specific. Now supports Equipment.Item.

118
Chapter 2: What's New in CitectSCADA 7.x

TagSetOverrideQuality Sets a quality Override element for a specified tag. Now supports
Equipment.Item.

TagSubscribe Subscribes a tag for periodic monitoring and event handling. Now
supports Equipment.Item.

TagWrite Writes to an I/O Device variable. Now supports Equipment.Item.

Reinstated Functions

No functions have been reinstated for 7.40.

Deprecated Functions

No functions have been deprecated for 7.40.

Removed Functions

No functions have been removed for 7.40.

CtAPI Functions in 7.40

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

New Functions

No new functions have been added for 7.40.

Modified Functions

ctListAdd Adds a tag to the list. Now accepts "Equipment.item".

ctListAddEx Adds a tag to the list with a specified poll period. Now accepts "Equip-
ment.item".

ctTagGetProperty Gets the given property of the tag. Now accepts "Equipment.item".

ctTagRead Reads the current value from the given I/O Device variable tag. Now
accepts "Equipment.item".

ctTagReadEx Performs the same as ctTagRead, but with an additional new argument.
Now accepts "Equipment.item".

ctTagWrite Writes the given value to the I/O Device variable tag. Now accepts "Equip-
ment.item".

Performs the same as ctTagWrite, but with an additional new argument.

ctTagwriteEx
Now accepts "Equipment.item".

Obsolete Functions

No functions were made obsolete in 7.40.

119
Chapter 2: What's New in CitectSCADA 7.x

120
Chapter 3: Upgrading to CitectSCADA
Upgrading to v7.40 from v7.30

Equipment.Item
In v7.40 you can reference a variable tag using associated equipment name and item
name (equipment.item syntax). In this release trend tags and alarm tags are not sup-
ported. After upgrading some existing equipment / item names may no longer be
accepted due to new compiler rules, for example, root equipment names cannot be a
reserved word and item names cannot be tag extension keywords.
You can also insert Equipment.item references into expression fields using the insert tag
option available when configuring objects in the graphics builder; however if no equip-
ment has been configured in your system the list will be empty. You will need to con-
figure equipment or deselect the option 'Display equipment items when populating tag
list' in the Project Editor Options Dialog to populate the list with available tags.
StruxureWare Templates
Templates are Wide Screen only. Two resolutions are available in this release:
l 1366 x 768
l 1920 x 1080

Note: The drawing canvas available in the new SxW templates is similar to the
equivalent tab-style templates, thus making it easier for you to upgrade projects to
the new templates.

EcoStruxure Web Services Server

To invoke EWS Service Methods from EWS client requires certificate and user credentials
authentication.
The user of EWS Service should be a valid Citect user that is defined in System->Users
form.
The EWS Service uses ctapi call to access variable tags, as such , INI parameter [CtAPI]
Remote should be set to 1 if CitectSCADA is running in single process or multi-process
mode.

Upgrading to v7.30 from v7.20

Due to changes in behavior of existing features in CitectSCADA since v7.20, the fol-
lowing upgrade procedures should be reviewed before continuing.

121
Chapter 3: Upgrading to CitectSCADA

ADO Support
The SQL engine for database query was updated in v7.30, as a result some Cicode func-
tions were removed.
Alarm Enhancements
l [Alarm]SummaryLength
The maximum value of the [Alarm]SummaryLength parameter has been changed.
l Migrating alarm event history
v7.40 introduced an historical alarm storage repository. The existing historical data is
automatically migrated to the new repository, once, on first start of your alarm server.

l Alarm Server Upgrade

There are a number of changes to the way alarm servers are configured (including
ports, paths and redundancy architecture). Alarm Server and legacy alarm client inter-
operability options have changed. When doing a live migration, older alarm clients
will not connect to a new alarm server process.
l Alarm string translation changes
Alarm server records in this release only support a single translation per field. If
translations have been used in a previous version, some changes may be required.
Changes have been made to the available formatting options.
l AlarmSetQuery
Users using custom cicode for filtering (implemented with AlarmSetQuery) will need
to re-engineer their code to use the new filter functions.
l AlarmRec Functions
v7.40 required that the cluster be explicitly specified in multi-cluster systems. Multi-
cluster systems must re-engineer Cicode using these functions. The compiler will not
identify that change to code is required.
l Summary Page Behavior Change
The new SOE view of historical alarm records, is designed to replace the alarm sum-
mary view. The alarm summary page will no longer dynamically update whilst dis-
played. Existing alarm summary pages will need to be redisplayed in order to
retrieve the latest data. Comments can no longer be added or deleted directly from the
summary page. Comments can only be added from the new SOE page. Some Alarm
Summary Cicode functions have also been removed.
Default Trend Storage
l Storage Method
Trend records now have to explicitly define their trend storage method on the trend
tag configuration form. The compiler will raise an error if not defined. In previous ver-
sions, the default when not defined was “Scaled (2 byte)”8 byte. When upgrading,

122
Chapter 3: Upgrading to CitectSCADA

customers must set the trend storage method for blank entries to match the default
from the previous version.
Graphics
l Disable style behavior correction
Disable style behavior has been corrected in v7.40. It is recommended when using a
style other than "embossed" to check the disable style of all groups, genies, and sym-
bols sets at runtime.
Internet Display Client
l IDC
Support for the Internet Display Client (IDC) has been removed from this release. It is
recommended you consider the use of the Web Client or the Single File Runtime-only
Install. The Single File Runtime-only Install should be used in conjunction with the
Run/Copy configuration (INI) settings.
Localization
l Alarm string translation changes
Alarm server records in this release only support a single translation per field. If
translations have been used in a previous version, some changes will be required.
Changes have also been made to the available formatting.
l Using local language as native
Languages need to be explicitly defined in your project before they may be used.
l SetLanguage Cicode Function
Runtime language switching is now achieved using the Login() Cicode function. The
existing SetLanguage cicode function has been removed.
OPC Server
l OPC servers need to be explicitly defined in the server section of the project con-
figuration.
l The Program ID has changed. The OPC DA server, program ID is Schneid-
erElectric.SCADA.OPCDaServer.1. (Old name Citect.OPC.1 and Citect.OPCRemote.1).
The DCOM setting needs to be updated based on the new program ID.
System Migration
l Hardware Requirements
In v7.40 the minimum and recommended hardware requirements have increased.
Load test your system as part of your upgrade procedure to ensure that the hardware
in use is adequate.
l Alarm Server Upgrade
When doing a live migration, older alarm clients will not connect to a new alarm
server process.

123
Chapter 3: Upgrading to CitectSCADA

l Historian
Customers using Historian should upgrade their version to Historian to v4.40 before
upgrading to v7.30.
Security
l Reserved User Names
Additional reserved user names were introduced in v7.40. When adding users to
CitectSCADA these reserved names should not be used.
l User Name Restriction
User Names with a dot in the name are invalid.

Upgrading to v7.20 from v7.10

l Persisted I/O Memory Mode

It is recommended that data assigned to disk I/O devices be migrated to the new per-
sisted memory I/0 mode.
l Super Genies
Prior to upgrading to CitectSCADA 7.20, identify and record Super Genie instance
page environment variables. After the upgrade, reinstate the Super Genie instance
page environment variables. If not, existing Super Genie template environment var-
iables will override the variables, due to synchronization.
l Launch CitectSCADA
An automatic upgrade of your projects will occur when you initially start Citect-
SCADA
l Configure Tags to Use Clustering
Alarms, reports, trends, SPC tags, and accumulators can now be configured to run in
a specific cluster.
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 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.

Upgrading to v7.10 from v7.0

To upgrade an existing project to v7.40 from v6.x, perform each of the following pro-
cedures.

124
Chapter 3: Upgrading to CitectSCADA

You are not required to carry out these procedures if you are upgrading from version 7.0
or later to v7.40.
l Upgrade CTAPI Applications
Verify that CTAPI applications are upgraded before upgrading and running any
CitectSCADA 7.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.
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

125
Chapter 3: Upgrading to CitectSCADA

6.x before upgrading to version 7.x.

Upgrade CTAPI Applications

To set up CitectSCADA v7.40 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.40
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.
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.

126
Chapter 3: Upgrading to CitectSCADA

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.40 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.40, as
CitectSCADA does not support different versions running side-by-side. Additionally,
to use the v7.40 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.

Launch CitectSCADA
An automatic upgrade of your projects will occur when you initially start CitectSCADA.

127
Chapter 3: Upgrading to CitectSCADA

1. To launch CitectSCADA, click Start | All Programs | Citect | CitectSCADA 7.30 |

CitectSCADA ExplorerSchneider Electric | PowerSCADA Expert 7.30 | Pow-
erSCADA Expert Explorer. The following message will display:

2. Click Yes to confirm the upgrade.

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
Converting Memory Variables

129
Chapter 3: Upgrading to CitectSCADA

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.

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.

130
Chapter 3: Upgrading to CitectSCADA

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.

131
Chapter 3: Upgrading to CitectSCADA

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.

132
Chapter 3: Upgrading to CitectSCADA

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

133
Chapter 3: Upgrading to CitectSCADA

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. Check the "Migrate equipment database" if you have an existing database that you
want to migrate into this version. When upgrading from an earlier version, and the
"PARENT" field of the equipment table was used, you should select this check box.
Otherwise existing data from the PARENT field will be ignored. If runtime browsing
is used, the PARENT field will return the equipment parent (the substring of the
equipment name without the last '.' and anything after that). To retrieve information
that was stored in the previous "PARENT" field the "COMPOSITE" field should be
used.
9. Click Migrate to begin the migration process, or click Close to exit without per-
forming the migration.
10. 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.

134
Chapter 3: Upgrading to CitectSCADA

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.

11. 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)
12. Click the Close button to close the dialog.

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

135
Chapter 3: Upgrading to CitectSCADA

Configure Servers
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
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, that

is, for product version 6 or ear-
lier.

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

5482 N/A Alarm Server Database Port

For details on configuring each type of server refer to:

136
Chapter 3: Upgrading to CitectSCADA

l Alarm Server Definitions

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

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

137
Chapter 3: Upgrading to CitectSCADA

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

138
Chapter 3: Upgrading to CitectSCADA

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

Alarm Server Upgrade

When upgrading to CitectSCADA 7.30, legacy alarm servers and clients (those prior to
7.30) will be unable to communicate with the new alarm server. Only v7.40 alarm client
and servers will be able to communicate with each other.
Other changes have been made in how you configure the Alarm Server Database Port,
and Alarm Redundancy Architecture .

139
Chapter 3: Upgrading to CitectSCADA

See Also

Alarm Server Side Synchronization

Alarm Reload Behavior

Migrating Alarm Event History

Migration of alarm event history from 7.x or later versions is supported in v7.30. Alarm
event history migration is triggered automatically at runtime if :
1. A set of valid alarm history files (<CurrentProjectName>_<Cluster>_ALMSAVE.DAT
and <CurrentProjectName>_<Cluster>_ALMINDEXSAVE.DAT ) exist (defined using
the parameters [Alarm]SavePrimary or [Alarm]SaveSecondary). If both sets of alarm
history files exist, one set from the primary alarm server and one set from the
standby alarm server, the system uses the set of files with the latest timestamp.
2. Alarm database does not exist in the system. This implies that runtime is launched
initially or the database has been manually deleted. The alarm database is created
when runtime is first launched.

Note:When backing up your project, if you modify the name of the project you will
need to manually update the project name within the .Dat files so that the <Cur-
rentProjectName> portion of the .Dat files match the modified project name (<Cur-
rentProjectName>_<Cluster>_ALMSAVE.DAT and <CurrentProjectName>_
<Cluster>_ALMINDEXSAVE.DAT ).

To undo the migration of the alarm event history you can manually delete the database.

Note:Deleting the database will cause v7.30 alarm history to be lost.

To delete the database, delete the directory located in the CitectSCADA data directory
that has the same name as the project. The CitectSCADA data directory is defined in INI
parameter [CtEdit]Data.
For instance, if the project name is Example and data directory defined in the INI param-
eter is:
[CtEdit] Data=C:\ProgramData\Schneider Electric\CitectSCADA 7.30\Data
The alarm database directory would be C:\ProgramData\Schneider Elec-
tric\CitectSCADA 7.30\Data\Example.
See Also
Memory devices

140
Chapter 3: Upgrading to CitectSCADA

Upgrade queries that use custom alarm filters

For v7.40 the functions AlarmSetQuery() and Query() have been made obsolete and have
been replaced with new alarm filter edit functions.
AlarmSetQuery() and Query() functions from 7.20 cannot be automatically upgraded to
the new v7.40 alarm filter edit functions. You will need to review and manually replace
these functions with the new v7.40 alarm filter edit functions. For basic conversion exam-
ples of how these new functions can be used refer to the topic Converting Alarm-
SetQuery() functions to use the Alarm filter functions.

New Alarm Page Templates

As part of v7.40 new alarm tab style templates have been introduced. These new active,
disabled, hardware, summary and soe pages include an Equipment tree-view panel on
the left hand side of the page and scroll bars to enable you to view rows and columns
off screen. You can manually update existing alarm pages in your project to the new tem-
plate. This will allow you to view alarms that belong to equipment in your system and
to see at a glance unacknowledged alarms belonging to parent and/or child equipment.
To update your existing alarm pages:
1. In the Citect Graphics builder open the relevant alarm page.
2. Go to File -> Properties. The Alarm page properties dialog will open
3. Select the 'Name' drop down field. The name drop down field lists all the available
templates.
4. Select the relevant ‘name_equip’ template and click OK. For example, to update the
disabled alarm page template select the page 'disabled_equip'.

Alarm Database Upgrade

In previous versions alarm data was saved to .dat file and system synchronization only
occurred at start up.
In v7.40 the alarm database has been upgraded and synchronization now occurs peri-
odically.
Using the ActiveX Data Objects(ADO) the new alarm database also supports queries.

Alarm string translation changes

In v7.40 partial translation and multiple markers per sentence are no longer supported
for alarm related strings.

141
Chapter 3: Upgrading to CitectSCADA

Refer to Multi-Language Projects for more information

Alarm Summary Page Behavior

As part of v7.40 the behavior of the summary page has been modified. You need to man-
ually refresh the alarm summary page (as you do for the SOE page) to retrieve the latest
events before analyzing the data.

Alarm*Rec Functions changes

In v7.40 the following changes have been made to Alarm *Rec functions:
1. Alarm*Rec functions are now executed in the client process, and MsgRPC is not
required when called remotely to the alarm server.
Refer to Cicode Functions in 7.30 for a list of functions that have been modified.
2. Removal of client side record numbers for alarms. This means that alarm record
numbers are only unique in the context of a cluster, and for multi-cluster systems,
Alarm*Rec functions will return an error if the cluster is ambiguous. This may occur
when the Cicode has no cluster context and the optional ClusterName argument is
not passed to the Alarm*Rec function. When upgrading a multi-cluster project, it is
recommended that calls to Alarm*Rec functions include a ClusterName argument.

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

Compiler Errors
Before you configure your project to run in version 7.x, 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

142
Chapter 3: Upgrading to CitectSCADA

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.

143
Chapter 3: Upgrading to CitectSCADA

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

Software Protection
CitectSCADA now supports two different software licensing models to help maintain
license conformance:
l Sentinel Licensing products which are the legacy methods used by the product.
o Using a SafeNet hardware dongle
l A new licensing method which is introduced with v7.30.
o Using a FLEXERA license locked to PC attributes.
o Using a FLEXERA SafeNet hardware dongle
In both cases the hardware dongle is a physical key that plugs into either the parallel
port or USB port of your computer, and contains details of your user license, such as
type and I/O point count.
You may choose to use either the SafeNet licensing method, or the new FLEXERA
method
Both the existing SafeNet licensing method and the new FLEXERA method now contain
the following features:
l Separate licensing for drivers used for importing tags, such as SpeedLink and Fas-
Linx is no longer required.
l There is no longer a distinction between Control Client or View-Only Client and their
web counterparts Internet Control Client or Internet View-Only Client.
For further information on the new licensing method, refer to Independent Point Count.

145
Chapter 4: About CitectSCADA

See Also
CiUSAFE dialog properties
Demo mode
Dynamic-point count licensing

Floating Point License Manager

Floating licensing benefits both users and license administrators. Users make more effi-
cient use of fewer licenses by sharing them on the network.
The Floating Point License Manager is used to list available floating licenses which have
been provided by the FLEXNET license server. The details are displayed of each license,
such as product name, version, part number, point count, and license expiration.
From the list of available license you can activate any that you wish to use on you sys-
tem.
There are several other activities that you can undertake within the Floating Point
License Manager interface. The interface has its own dedicated on line help which you
can display from the Help item on the interface menu.
See Also
CiUSAFE dialog properties
Dynamic-point count licensing
Software Protection
FlexNet license server

FlexNet license server

The FlexNet license Server allows software licenses to be available (or float) anywhere on
a network, instead of being tied to specific machines. License administrators control who
uses the licensed applications and the machines where the licenses are available. The
licensed software is then managed by the Floating Point License Manager for a floating
license, and the License manager for a node-locked license..
The FlexNet license server consists of four required components:
l The FlexEnabled application, with the FlexNet Publisher static client library linked
into it.
l The license server manager, which handles the initial contact with the licensed appli-
cations, passing the connection on to the appropriate vendor daemon. It also starts
and restarts the vendor daemons.

146
Chapter 4: About CitectSCADA

l A vendor daemon, one process for each vendor who has a licensed product on the
network. The vendor daemons keep track of how many licenses are checked out, and
who has them. Licensed applications communicate with the vendor daemons
through TCP/IP network communications.
l A source for license rights, a license file installed by the license administrator. This
source contains information about the server machines and vendor daemons and has
at least one entry for each licensed product, specifying that product’s license details.
See Also
CiUSAFE dialog properties
Dynamic-point count licensing
Software Protection
Floating Point License Manager

Independent Point Count

On a given SCADA machine a local client acts as a license server. Upon reading its
[Client]ComputerRole INI parameter, it knows what type of license it is entitled to.
A remote client, needing a license, obtains its point count via TRAN subsystem from the
display client, residing on the machine that has access to the licensing information. The
count that it receives depends on its licensing entitlements (Computer Role).
A client can specify what point count it requires by [Client]PointCountRequired INI
parameter. If this parameter is not specified, the client will get the first available match-
ing point count. If the parameter is specified, but the required point count is not found
within the license, no point count (no license) is served to that client.
For example. if a license has
l 2 Full License entitlements with 10000 points and 20000 points.
l 2 View-Only License entitlements with 500 points each.
1. A local client specifies [Client]PointCountRequired=30000. When it starts, it gets shut
down with invalid point count message (because the license has no Full License
entitlement with 30000 points).
2. A local client specifies no [Client]PointCountRequired. When it starts, it gets 10000
point count.
3. A local client specifies [Client]PointCountRequired=20000. When it starts, it gets
20000 point count.
A remote client connects to it, requesting Full License with 40000 points. It gets no
license, since such a license is not available.
Another remote client connects to it, requesting Full License with 20000 points. It
gets no license, since such a license is not available (it is used by the local client).

147
Chapter 4: About CitectSCADA

Another remote client connects to it, requesting Full License with 10000 points or
with no point count specified (i.e. that remote client has no [Client]Point-
CountRequired in its INI file). It gets served the second available Full license.
Another remote client connects to it, requesting View-Only License with no point
count specified. It gets served one of the View-Only licenses with 500 points.
When any of the remote clients disconnect, the corresponding licenses served to them
earlier are reclaimed.
With the Sentinel licensing, each license has the same point count and a Sentinel key
will map to the new licensing as shown below.

Sentinel key with point count of 5000 New license model

run time users – 1 key 1 Full License – 5000 points

control clients – 3 key 3 Control Client License – 5000 points each

view only users – 2 key 2 View-Only Client License – 5000 points each

Point count special rule

A display client running in Full License mode (Client+Server or Control Client with Full
License) has a special rule for point count limits; if its full license entitlement is >= 500,
its client point count component is treated as unlimited.
Taking this special rule into account, the following describes the licensing scenario:
Assume a client with a dongle attached (acting as a local licensing server), the runtime
point count is calculated on the basis of:
l Server component (consolidated point count from Alarm, Report, & Trend servers)
l Client component (consolidated point count from OPC Server, CtAPI, and page dis-
plays, i.e. subscriptions)
Normally the overall runtime point count is calculated by taking the maximum of the
above two components; client and server. However, if the client is fully-licensed and the
point limit specified on the license is greater than 500 points, when calculating the over-
all runtime point count, the client component is disregarded and only the server com-
ponent is considered.
For Example:
l Alarm, Report, and Trend servers report 100 points (server component)
l CtAPI, OPC Server, and display pages use 200 points (client component)
l If the license entitlement is 499 points, the overall point count reported is 200 points
(maximum between 100 & 200)
l If the licenseentitlement is 500 points, the overall point count reported is 100 points
(since client component is disregarded)

148
Chapter 4: About CitectSCADA

See Also
CiUSAFE dialog properties
Demo mode
Dynamic-point count licensing
FlexNet license server
Floating Point License Manager

CiUSAFE dialog properties

The CiUSAFE dialog box has the following properties:
Serial Number
The serial number of the computer's hardware key. It will only appear if the key was
delivered after September 11 2000, or has been updated since this time. If this is not the
case, you can read the number from the label on the hardware key. You need to enter the
serial number at the Schneider Electric (Australia) Pty. Ltd. web site to update the key.
KeyID
Each time you launch CiUSAFE, a Key ID will display in the KEYID field. You might
need to provide the Key ID plus the serial number when updating the hardware key.
This depends on the status of the key in the CitectSCADA license database, and you are
prompted if the Key ID is required. Click Save KeyID to save the Key ID and serial
number to a text file, which you can refer to when visiting the Schneider Electric (Aus-
tralia) Pty. Ltd. web site.
Authorization Code
To update the hardware key, enter the 106-character authorization code. You are asked
for this code once you have entered the Key ID and serial number, and your license and
Customer Service agreement have been verified. Click Update to update your hardware
key.
Return Code
The Return Code indicates the result of the key update:

0 The key was updated successfully.

1,3 Either the KeyID or the Authorization code you entered is invalid.

2 Either the KeyID or the Authorization code you entered has been corrupted.

4, Either the KeyID or the Authorization code you entered is invalid.

9 No hardware key could be found.

149
Chapter 4: About CitectSCADA

To close the program, click Exit.

Demo mode
You can run CitectSCADA without the hardware key in demonstration (Demo) mode.
Demonstration mode lets you use every CitectSCADA feature normally, but with
restricted runtime and I/O.
In demonstration mode you can work in multi-process (with the networking model
selected as Stand alone) or single process mode.
The following demonstration modes are available:
l 15 minutes with a maximum of 50,000 real I/O.
l 10 hours with a maximum of 1 dynamic real I/O. This is useful for demonstrations
using memory and disk I/O. CitectSCADA starts in this mode if no hardware key is
available. If the system detects that you are using more than 1 real I/O point at run-
time then it will swap to the 15 minutes demo mode.

Note: Writing to any tag through DDE, CTAPI, or ODBC will cause that tag to con-
tribute to the dynamic point count even if it is a memory or disk I/O point. So if you
write to more than 1 point through these interfaces it will swap to the 15 minute
demo mode.

l 8 hours with a maximum of 42,000 real I/O. This is only available through special
CitectSCADA Integration Partners (CIP) keys.

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

150
Chapter 4: About CitectSCADA

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
component - if two server components use the same tags, say alarm and trend, the
tags will not be counted twice when the point count gets totaled, each unique point is
counted once only.
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. In CitectSCADA 7.30 a special case has been intro-
duced; if the server point count is greater than 500, the client component point count
is disregarded
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.
With the release of 7.30 further changes to licensing point count have been included,
with the introduction of the “One License” product licensing method.
These are listed below:
l If a given tag is used by both, say, trend and alarm servers each server reports actual
tags used (Cluster.TagName), so the same tag is not counted twice.
l A new INI parameter has been added to control IP addresses aging. It is used to indi-
cate how long to reserve a license for a given IP address in cases when a remote
client connection is lost. This does not apply to FULL licenses. The parameter is [Gen-
eral]LicenseReservationTimeout.

151
Chapter 4: About CitectSCADA

l In previous versions there was a single point count within the licensing model, now
there are multiple point counts as a pair of values: License Type – Point Limit.
See Also
Software Protection
CiUSAFE dialog properties
FlexNet license server
Floating Point License Manager
Demo mode

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.

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.

152
Chapter 4: About CitectSCADA

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.

153
Chapter 4: About CitectSCADA

154
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

155
Chapter 5: Tools

See Components of a project

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

156
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

157
Chapter 5: Tools

158
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

159
Chapter 6: Components of a project

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

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

160
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 Alarms

Analog Alarms

Time-stamped Alarms

Advanced Alarms

Multi-Digital Alarms

Time-stamped Digital Alarms

Time-stamped Analog Alarms

Refer to Adding a new alarm for information about each Alarm type.
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

Keyboard Key sequences with associated instructions

commands
See System Keyboard Commands

Reports Customized presentation of runtime data and special conditions

See Reporting Information

161
Chapter 6: Components of a project

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

See Including projects

162
Chapter 6: Components of a project

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

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

address- servers
es
See Network Address Definitions

163
Chapter 6: Components of a project

Alarms Servers that monitor alarms and display them on the appropriate
servers 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 Dedicated communications servers that exchange data between

servers I/O Devices and clients

OPC DA A runtime OPC DA server that implements all mandatory OPC DA

servers v2.05 and OPC DA v3 interface specifications
See Using an OPC DA Server

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 in the Cicode Reference Guide.

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

CitectVB- Basic scripting language.
A
See Introducing CitectVBA in the CitectVBA Reference Guide..

164
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

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

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

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

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

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

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

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

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

173
Chapter 7: Typical system scenarios

174
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
Using Alarms in SCADA
Configuring Events
Using Accumulators
Logging and Trending Data
Understanding Statistical Process Control
Reporting Information
Using Security
Using Labels
Using Devices
Understanding Equipment in SCADA
Exchanging Data with Other Applications
Using Genies and Super Genies
Working with Multi-Language Projects
Using an OPC DA server
Communicating with I/O Devices

175
Using the Communications Express Wizard
Building Your Project

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

Existing computer hardware

177
Chapter 8: Planning a Project

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.

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.

178
Chapter 8: Planning a Project

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

180
Chapter 8: Planning a Project

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
l Client-Server system
l Redundant server system
l Clustered control system

181
Chapter 8: Planning a Project

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 Implementing Clus-
tering.
See Also
Clustering context rules
Typical system scenarios

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.

182
Chapter 8: Planning a Project

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.

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.
When naming your project do not use spaces in the project name. Although Citect-
SCADA does not prevent you from using spaces in a project name, using spaces can
cause unpredictable results.

183
Chapter 8: Planning a Project

Projects
Setting up I/O Device Communication
Graphics components
Alarms
Data Collection
Users and Areas
System Components
Anti-virus software setup

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

184
Chapter 8: Planning a Project

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
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
Using Alarms in SCADA
Configuring 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

185
Chapter 8: Planning a Project

configure 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
specific 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 graph-
ics page.
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.

186
Chapter 8: Planning a Project

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 Equipment - Project Editor form allows access to the equipment database which aids
in automated configuration.
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 run-
time-only version of a project over the Internet from a remote location.
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

Anti-virus software setup

SYSTEM PERFORMANCE DEGREDATION

The "on access" scan in anti-virus products can lock files used by CitectSCADA, usually hav-
ing the effect of slowing CitectSCADA down whilst it waits for the scan of that file to finish.

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

187
Chapter 8: Planning a Project

INOPERABLE SYSTEM OR LOSS OF DATA

In some extreme cases, anti-virus software may (incorrectly) detect certain patterns within
data files as being viruses. Depending on the anti-virus configuration, this may result in
files being relocated or deleted, resulting in data being lost or the system being inoperable.

Failure to follow these instructions can result in injury or equipment damage.

It is recommended that the following directories are excluded from scanning by any anti-
virus products:
l Program Files installation directory (including files and sub directories)
l Data and Logs directories
l Any alarm server archive paths
The above exclusions are recommended for "on access" or "real time" scans that run con-
tinuously and scan each file that is read from or written to. Scheduled scans, which are
usually daily or once a week, should also have these exclusions added with the excep-
tion of the Program Files exclusion.
See Also
Building Your project

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

188
Chapter 8: Planning a Project

Setting up CitectSCADA as an OPC DA server

CitectSCADA supports a runtime OPC DA server that implements all mandatory OPC
DA v2.05 and OPC DA v3 interface specifications.
This allows CitectSCADA to provide real-time data to any compliant OPC DA clients,
including applications such as AMPLA, OSI-PI and Historian.
For information on how to set up an OPC DA Server for your CitectSCADA system, see
Using an OPC DA Server.

189
Chapter 8: Planning a Project

190
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 Understanding Projects within CitectSCADA
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

Understanding Projects within CitectSCADA

Along with the core content that is fundamental to all projects, CitectSCADA includes
purpose-built content that you can use when creating a new project. This content is deliv-
ered through two types of projects:
l Include projects
l Starter projects

191
Chapter 9: Administering Projects

In using either the ’include’ or starter projects you are able to set up a project more
quickly. The ‘include ‘and Starter Projects have distinct differences which are outlined
below.

Include Projects

Include projects contain pre-defined database records and graphics libraries that can be
used within your project.
Some examples of what is included in an Include project are page templates, symbols,
genies, and generic Cicode functions.

Note: If you modify the include projects for use as a runtime project, they will not
compile successfully. CitectSCADA upgrades install a new version of the CSV_
Include project, which will overwrite any changes you make to the project when this
happens.

Starter Projects

Starter projects contain pages, roles and other features, which vary depending on the tem-
plate you base your project on. You can select a starter project either based on the tab
style templates or based on the StruxureWare style templates. There are six pre-defined
starter projects with each of the starter projects containing:
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, SOE (Sequence of events), Disabled, Hardware based on the alarm
equipment tree-view templates in the tab style include project
l Process Analyst and !ProcessAnalystPopup based on the relevant templates found in
the Tab_Style_Include project.
l Manual Override and Control Inhibit pages based on the new templates in the tab
style include project
l The following Menu configuration defined:
@(Pages)
<the pages are automatically populated via project parameter [PAGE]AddDefaultMenu = 2>
@(Alarms)
@(Active Alarms)
@(Historical Events)
@(Disabled Alarms)
@(Hardware Alarms)
@(Trends)
@(Process Analyst)

192
Chapter 9: Administering Projects

@(Popup Process Analyst)

@(Tags)
@(All Variable Tags)
@(Manual Override)
@(Control Inhibit)

l The following servers:

l Alarm Server: AlarmServer1

l Report Server: ReportServer1

l Trend Server: TrendServer1

l I/O Server: IOServer1

The newly created project is compilable, and contains a basic level of built-in functions
such as viewing alarms and trends.

Type
Name of Description
project

CSV_include Include Windows XP styled project. Deprecated in 7.20.

Library_Con- Include Contains a series of genies that are common UI controls such as
trols a tree-view, data table and scroll bars. Cannot be compiled.

Include Include Template project with trending and alarm pages Cannot be com-
piled.

SxW_Style_1_ Starter Screen resolution 1080 HD (Full HD). Wide screen only. Includes
HD1080_title- the SxW_Include project. Can be compiled.
bar

SxW_Style_1_ Starter Screen resolution 768 HD (Full HD). Wide screen only. Includes
HD768_titlebar the SxW_Include project. Can be compiled.

Tab-Style Include Includes a set of templates styled for the Windows 7 envi-
Include ronment. Cannot be compiled.

Tab_Style_1_ Starter Screen resolution 1080 HD (Full HD). Includes the Tab style
HD1080_title- Include Project. Can be compiled.
bar

Tab_Style_1_ Starter Screen resolution SXGA Includes the Tab style Include Project
SXGA_titlebar Can be compiled.

Tab_Style_1_ Starter Screen resolution WUXGA Includes the Tab style Include Project
WUXGA_title- Can be compiled
bar

Tab_Style_1_ Starter Screen resolution XGA. Includes the Tab style Include Project
XGA_titlebar Can be compiled

The include projects are hidden from the project tree in Citect Explorer by default.
To show/hide an Include project:

193
Chapter 9: Administering Projects

1. Open the Citect Explorer.

2. Select Show Include Project from the View menu.
See Also
Creating a project
Using the StruxureWare Templates
Using the Tab_Style Page Templates
Using the Library_Controls Include Project
Using the CSV_Include Project

Creating a project
You can create a new project using an existing starter project or 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.
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.This can be one
based on the tab style or StruxureWare screen resolution projects or your own starter
project (.ctz file).
7. Click OK.
8. The newly created project will be listed in Citect Editor.
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 or StruxureWare templates, don't include
pages based on templates that use a different style, including the earlier CSV_Include
project. Doing so might affect functionality.

194
Chapter 9: Administering Projects

See Also
New Project dialog
Creating a New Tab Template Project
Understanding Projects within CitectSCADA
Using the Library_Controls Include Project
Using the StruxureWare Templates
Using the CSV_Include 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.
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.

195
Chapter 9: Administering Projects

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

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.

Viewing projects
To make locating and viewing project and configuration folders easier, CitectSCADA
now features a set of menu commands to open these folders directly from Citect
Explorer.
To open the Config folder:

1. Start Citect Explorer.

2. Choose Config Folder from the View menu.

196
Chapter 9: Administering Projects

To open a Project folder:

1. Start Citect Explorer.

2. Choose Current Project Folder from the View menu.
In addition you can open the Project Folder for a specific project by right clicking the
project name in the Citect Explorer Project List. Choose the Open Project Folder link
from the drop down menu.

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

197
Chapter 9: Administering Projects

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
"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):

198
Chapter 9: Administering Projects

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.

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

199
Chapter 9: Administering Projects

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

200
Chapter 9: Administering Projects

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

201
Chapter 9: Administering Projects

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.

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.

202
Chapter 9: Administering Projects

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

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.

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.

203
Chapter 9: Administering Projects

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.

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

204
Chapter 9: Administering Projects

configuration 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

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.

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 and minutes between

000:01 and 168:59 (inclusive) to specify the
period between synchronization that needs to

205
Chapter 9: Administering Projects

Field Description

occur. The default value is 24:00.

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 run-
ning 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 confirm
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 per-
forming 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

206
Chapter 9: Administering Projects

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

207
Chapter 9: Administering Projects

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 pass-
word. CitectSCADA writes the project to disk in a format that encodes the pass-
word 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

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:

208
Chapter 9: Administering Projects

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>

-m<ext> include extension

-x<ext> exclude extension

-e encrypt with password

-p<pass- encrypt/decrypt password

209
Chapter 9: Administering Projects

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

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

210
Chapter 9: Administering Projects

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.

NOTICE
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

211
Chapter 9: Administering Projects

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. To make these files active, and to update the current
Wizard or Time Synchronisation settings with the restored settings, copy the restored
files to the Config folder, replacing the currently used corresponding configuration
files.
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.

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.

212
Chapter 9: Administering Projects

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

Rec-
Development Com-
ommen- Server / Display Client WebClient
puter
dation

Good c:\user\ProjectMain d:\run\ProjectMain (<- \temp\-

RunPath) 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 (<- \temp\-

RunPath) citect\deployname\
ProjectMain

c:\user\Dev- d:\runA\ProjectInclude \temp\-

\ProjectInclude citect\deployname\
ProjectInclude

c:\user\Include c:\user\Include* \temp\-

citect\deployname\
Include

OK* c:\user\Dev\ProjectMain d:\run\ProjectMain (<- \temp\-

RunPath) citect\deployname\
ProjectMain

213
Chapter 9: Administering Projects

Deployment

Rec-
Development Com-
ommen- Server / Display Client WebClient
puter
dation

c:\user- c:\user- \temp\-

\Includes\ProjectInclude \Includes\P- citect\deployname\
rojectInclude* ProjectInclude

c:\user- c:\user- \temp\-

\Includes\Include \Includes\Include* 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.

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

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

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

215
Chapter 9: Administering Projects

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
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 "Some variable tags were not found" message window to appear when a var-
iable tag or tag reference is specified that does not exist in the database.
Prepare for Web deployment

216
Chapter 9: Administering Projects

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

217
Chapter 9: Administering Projects

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.40 now allows you to include undefined tags on your graphic pages,
this alert may be redundant and impractical. By deselecting this option, the alerts are
still included in the displayed count, but they are not added to the error log.
Display equipment items when populating tag list
This option is selected by default. Equipment.Item tag references will populate 'insert tag'
list when adding objects to a graphics page. If not set the variable tag list will be pop-
ulated.

Note: If this option is selected and no equipment has been configured, the list will be
empty.

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.

Note:You can also insert Equipment.item references into expression fields using the
insert tag option; however if no equipment has been configured in your system the
list will be empty. You will need to configure equipment or deselect the option 'Dis-
play equipment items when populating tag list' in the Project Editor Options Dialog
to populate the list with available tags.

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.

218
Chapter 9: Administering Projects

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.

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.

219
Chapter 9: Administering Projects

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:

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.

220
Chapter 9: Administering Projects

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
special 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.
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, symbol, or template and selecting Current Graphic as the Look in option
(see below).

221
Chapter 9: Administering Projects

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 doc-
ument 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 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 example, if the document type is a:

222
Chapter 9: Administering Projects

Column Description

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

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

223
Chapter 9: Administering Projects

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.
See Also
Replacing results

224
Chapter 9: Administering Projects

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

225
Chapter 9: Administering Projects

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.

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:

226
Chapter 9: Administering Projects

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

227
Chapter 9: Administering Projects

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.

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.

228
Chapter 9: Administering Projects

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?

229
Chapter 9: Administering Projects

230
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:

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

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

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

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

235
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.30C:\ProgramData\Schneider Electric\PowerSCADA
Expert 7.30

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

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

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

238
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]Save-
Secondary 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").

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

240
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

241
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

242
Chapter 10: Securing Projects

box with the Computer Setup Wizard, so that there will not be an unintentional can-
cellation of system startup.

243
Chapter 10: Securing Projects

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

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

246
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:

247
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

248
Chapter 11: Using CitectSCADA Security

Privilege 1

Comment An Operator with Privilege classification 1 can operate the conveyor

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.

Viewable Areas Priv-

Role Description
assigned ileges

Receiver controller Needed to monitor the 1,2,3 1,4,5

receiver area, print out
reports and track progress of

249
Chapter 11: Using CitectSCADA Security

Viewable Areas Priv-

Role Description
assigned ileges

supplies. Also will need to

control system elements that
have a privilege level of 1,4,
5.

Operations Man- Needed to monitor the Proc- 1,2,3,4,5,6,7,8,9 2,3,4,5

ager essing area of the plant. Needs
to be also able to control ele-
ments within processing. At
times will need to be able to
check on the Receivals area.

Despatch Handler Needs to be able to organize the 8,10,11,12 1,2,5,6

packing and distribution of final
product. Will need to track prod-
uct production to schedule dis-
patch tasks for packer.

Engineer Engineer is necessary to have 1,2,3,4,5,6,7,8,9,10, 1,2,3,4,

access to every area of the 11,12 5,6
plant, and will be able to operate
any system element.

Conveyor Operator Needs to be able to operate the 8 1

conveyor.

Mixer Operator Needs to have access to each 4,5,6,7 2

type of mixer operation. Will
have access to areas 4 to 7 and
will be able to operate any sys-
tem element with a privilege of
2.

Packer Needed to be able to package 12 6

goods

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

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"

251
Chapter 11: Using CitectSCADA Security

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

252
Chapter 11: Using CitectSCADA Security

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

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 15 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:

253
Chapter 11: Using CitectSCADA Security

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

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

254
Chapter 11: Using CitectSCADA Security

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

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 Equipment | 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 (Users using Windows Authentication only)
Enter the name of the group that you intend to link to the Windows security group. Ver-
ify that this name is the 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 you only
use the characters that are allowed for Windows group account name in Windows.

255
Chapter 11: Using CitectSCADA Security

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

Comment
Any useful comment. Enter a value of 48 characters or less.
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.

Extended forms fields

The following fields are implemented with extended forms (press F2). Note that some of
the fields listed below may be displayed in the previous section of the form.
View 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.

256
Chapter 11: Using CitectSCADA Security

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 send it regardless of whether 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.
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.
Priv1 Areas. . . Priv8 Areas
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
See Also
Adding groups and users in Windows security.

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.

257
Chapter 11: Using CitectSCADA Security

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

258
Chapter 11: Using CitectSCADA Security

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.
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-
Oper- tem element.
ator

No Yes Con- No No Can view the system

veyor element but cannot
Oper- operate it as role does
ator not have the nec-
essary privilege

No Yes Con- No Yes Can view the system

veyor (match- element and control it
Oper- ing) as role been granted
ator 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
Oper- is no longer assigned
ator to Area 0.

Yes No Con- Yes (match- No Role can view and con-

veyor ing) trol the system ele-
Oper- ment, as no privilege
ator restriction has been

259
Chapter 11: Using CitectSCADA Security

Area Priv Role Area Priv Security

set.

Yes Yes Con- Yes (match- Yes (not Can view the system
veyor ing) match- element in the rel-
Oper- ing) evant area but cannot
ator operate it as role does
not have the nec-
essary associated
privilege.

Can view the system

Con- element and control it
Yes
veyor Yes (match- within the relevant
Yes Yes (match-
Oper- ing) area, as role has been
ing)
ator 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

260
Chapter 11: Using CitectSCADA Security

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

261
Chapter 11: Using CitectSCADA Security

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
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.
Before adding a new user check the Reserved User Name list. This list details built-in
users included in CitectSCADA.
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.

262
Chapter 11: Using CitectSCADA Security

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
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 Privilege 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 individual records it
could confuse development or provide scope for inconsistencies and unexpected

263
Chapter 11: Using CitectSCADA Security

behavior if other field values are changed. When adding records in configuration, it is
therefore recommended that you remove duplicate Type values from additional user rec-
ords.
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.

Notes:To login a user, you need to use the Login() or LoginForm() Cicode functions.

See Also

Reserved User Names

When adding users to your SCADA system, the following users/user names have been
reserved and should not be used.
l Driver
l logic
l method call
l schedule
l system

Note: Avoid using these reserved user names for windows users. Attempting to
login with one will result in a hardware alarm being generated and the login will be
unsuccessful.

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.

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

265
Chapter 11: Using CitectSCADA Security

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.

266
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

267
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 (refer to
Parameter documentation).
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

268
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

269
Chapter 11: Using CitectSCADA Security

270
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
Launching runtime for the first time

Running the Computer Setup Wizard

To start the Computer Setup Wizard:

1. Open Citect Explorer.

2. In the project list area, select My Projects - designated by a computer icon.
3. Select a project from the list. If not previously compiled, compile the project.
4. Select the Computer Setup Wizard icon, or choose Tools | Computer Setup Wizard.
The Computer Setup Wizard is displayed.
5. Select Express Setup or Custom Setup.

271
Chapter 12: Configuring Your System

The pages that are displayed depend on the configuration of the machine and include:
l Project Configuration
l Computer Role Configuration
l Network Model
l Server Password Configuration
l Server User 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 EcoStruxure Web Services Server Setup *
l EcoStruxure Web Services Server User Setup *
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.

272
Chapter 12: Configuring Your System

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.

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]COPYcommands to main-
tain synchronization between the two projects.

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

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

Server This computer will be a standalone or networked I/O Server and Control
and Con- Client. This option is disabled if this computer has no Server components
trolClient assigned to it to run. Selecting this option enables the Multi-Process
check box.

Select the Multi-Process check box to separate your client and server com-
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.

Control This computer will only be a Control Client. This option is disabled if this
Client computer has been assigned a Server component to run. Selecting this
option enables the Full License check box.

Select the Full License check box if you want this Control Client to use a full
(server) license, as opposed to a client license. This sets the [Client]Full-
License parameter in the Citect.ini file to 1 (the default value is 0). Gen-
erally, you would not allocate a full server license to a client as there is no
difference in functionality between the two licenses. Allocate a full server
license if you have insufficient client licenses available, or for some other
specific need.

274
Chapter 12: Configuring Your System

View-only This computer will only be a View-only Client. This read only option is dis-
Client abled if this computer has been assigned a Server component to run.

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

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]Par-
tofTrustedNetwork INI parameter.
If a server process exists and networking has been enabled:

275
Chapter 12: Configuring Your System

The Configure Server Password checkbox is selected and unavailable.

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.

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.

276
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

DNS Parameters in the Parameters online help

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

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 detects 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-
con- mary server, or it can remain idle until called.
currently
with pri-
mary
Reports
Server

277
Chapter 12: Configuring Your System

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.

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

280
Chapter 12: Configuring Your System

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:

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.

281
Chapter 12: Configuring Your System

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

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
con- CitectSCADA at run time. Disabling this provides better security.
figuration
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.

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.

282
Chapter 12: Configuring Your System

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

283
Chapter 12: Configuring Your System

EcoStruxure Web Services Server Setup

Note: This screen is only available if an EcoStruxure Web Services Server has been
configured in your project. Configuration of this feature requires Windows admin-
istrative privileges. If logged on as an administrator you will need to register with
elevated privileges. In the Windows User Account Control prompt, click OK to pro-
ceed. If logged on as a non-administrator, you will be prompted to enter an admin
password.

To service requests from web service clients use this setup dialog to reserve the URL of
the EcoStruxure Web Service on the computer.
Click on the Register button.This will reserve the URL for all users on the computer. You
need to register the URL once. If the URL is not registered, EcoStruxure Web Services
Server will need to be run as administrator on the computer.
If the URL is successfully registered, the message "URL reservation successfully added"
will be displayed. If the message "URL reservation add failed, Error: 183. Cannot create a
file when that file already exists." is displayed, the URL has already been registered.

Note: This will register the EWS for all users. If you do not want the URL available
to all users you can manually control access by using the Windows utility netsh.exe.
Only users for whom the URL has been reserved will be able to start the web service.
For more information refer to Modifying the URL Reservation.

See Also
General Options Setup

Modifying the URL Reservation

To delete, browse or manually control the reserved URL of the EcoStruxure Web Service
on the computer use the Windows utility netsh.exe.

Note: For registration information refer to the topic EcoStruxure Web Services Server
Setup.

To delete a URL reservation

1. Click Start, point to All Programs, click Accessories, right-click Command Prompt
and click Run as Administrator on the context menu that comes up. Click Continue

284
Chapter 12: Configuring Your System

on the User Account Control (UAC) window that might ask permissions to continue.
2. Type in netsh http delete urlacl url=<urlNamespace> in the command prompt win-
dow. Where <urlNameSpace> = https://-
<ewsServerAddress>:<ewsServerPort>/DataExchange e.g.
http://localhost:2086/DataExchange.
3. If the reservation is deleted successfully, the following message is displayed, 'URL res-
ervation successfully deleted'.
To display URL reservations

1. Click Start, point to All Programs, click Accessories, right-click Command Prompt
and click Run as Administrator on the context menu that comes up. Click Continue
on the User Account Control (UAC) window that might ask permissions to continue.
2. Type in netsh http add urlacl url=<urlNamespace> user=<machine name>\<security
group name> in the command prompt window. Replace <machine name> with the
computer name or Windows domain on which the group is created and <security
group name> with the name of the security group.
3. If the reservation is created successfully, the following message is displayed, 'URL res-
ervation successfully added'.

See Also
General Options Setup

EcoStruxure Web Services Server User Setup

Note: This screen (in the computer setup wizard) is only available if the EcoStruxure
Web Services Server has been configured in your project.

NOTICE
NOTICE It is recommended that you do not set the [Server]EWSAllowAnonymousAccess
INI parameter to 1.If set unauthorized access to tag data may occur. Enable access only if
your EWS Client supports Anonymous authentication and no other.

285
Chapter 12: Configuring Your System

Use this dialog to enable/disable anonymous access. If enabled an EWS Client can
retrieve data from the EWS Server without supplying user credentials.
Select the option Allow Anonymous Access. When enabled the [Server]EWSAl-
lowAnonymousAccess INI parameter will be set to 1.
When selected the CtApi User Credentials box will become active. Enter a user name
and password. The user name and password will be used by the EWS Server to connect
to CtApi.

Note: Anonymous requests from EWS client will have read only access to the data.
The EWS method SetValue will not be supported for anonymous requests.

See Also
General Options Setup

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.

286
Chapter 12: Configuring Your System

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

OPC Alarms and Click the Register button to register alarm servers defined in a
Events project to be accessed via a third party OPC client.
Note: This registration requires administrative privileges. If already
logged on as an administrator you will be asked to allow the program
to run with elevated privileges. Click OK to proceed. If logged on as a
non-administrator, you will need to provide an admin password before
being asked to allow program to run with elevated privileges.
On Windows XP, deselect the option "Protect my computer and data
from unauthorized program activity" if the "Run As" message box is
displayed then click OK.

Firewall Settings and CitectSCADA

Citect Runtime needs to be in the exception list for the current network. If the alarm
server is not functional, or if hardware alarm, "No Server could be found", for report
server, trend server, IO server or alarm server, is raised, you should check the firewall
settings to see if communication between Citect Runtime and the network is not blocked.
During installation you can enable the installer to add Citect Runtime to the exception
list for the current network automatically. If the computer is moved to another network,
or the network settings are modified you will need to check whether Citect Runtime is in
the exception list for the new network, and if necessary manually update the exception
list.

287
Chapter 12: Configuring Your System

Launching Runtime for the first time

During installation, if you chose to modify Windows firewall settings later when you
run Citect Runtime for the first time, a "Windows Security Alert" prompt will pop up.
There are three checkboxes, Domain networks, Private networks and Public networks. At
least one checkbox is selected by default which is based on the current network setting.
For additional information refer to the topic Network Communications Overview in the
Installation guide.

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 Rules
of Clustering.
Cluster context, therefore, is the default cluster used for tag resolution and execution of
expressions and Cicode functions. In the case of tags and tag references, a cluster is
explicitly supplied by prefixing the tag name or tag reference 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.

Note: CitectSCADA will automatically resolve tags without a cluster context spec-
ified if every tag name in the project is unique. See Resolving cluster context with
unique tag names.

See Also
Assigning graphics page objects to a cluster at Runtime

Resolving cluster context with unique tag names

CitectSCADA will allow tags or tag references without a cluster context specified to be
automatically resolved if every tag name in the project is unique.
This means if you use a unique naming convention for your tags, you will be able to con-
figure a multi-clustered system without having to specify cluster context.
For any tags that are not unique, #COM will be displayed if cluster context can not be
determined.

Note: This capability is enabled by default via the parameter [General]TagDB.

290
Chapter 13: Implementing Clustering

See Also
Assigning graphics page objects 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.
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.

291
Chapter 13: Implementing Clustering

The next diagram demonstrates circumstances which do not correctly follow the clus-
tering rules.

292
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 following cluster properties:

Option Description

Cluster Name The name of the cluster. The name needs to be unique to the project and
not contain spaces.

Comment Any useful comment. This property is optional and is not used at run-
time.

293
Chapter 13: Implementing Clustering

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 configured. The
name needs to be unique to the project and not contain spaces.

Address The IP address or computer name of the machine or network card being
configured. For machines with dual network cards, add a network
address for each card in each machine to which you want to com-
municate. See Network Redundancy for information.

Any useful comment. This property is optional and is not used at run-
Comment
time.

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.

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:

294
Chapter 13: Implementing Clustering

Option Description

Cluster Name The name of the cluster to which this Alarm Server will 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 Name The name of the server. The name needs to be unique to the project
and any included projects, 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 Primary. The Primary and Standby
servers need to run on different computers, and only one Primary and
one Standby can be defined per cluster. Mode determines which server
will be assigned the highest arbitration priority. The arbitration priority
is used to work out which server will continue to be 'main' after a 'main-
main' situation has occurred.

Network The network address(es) of the server being configured. To specify

Addresses dual network connections to the server, use a comma delimited list. See
Network Redundancy.

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

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

Archive Schedules archiving to occur every ' number' of days. If set, archiving will
every occur automatically, after the alarm server has started.

Archive Path Define where the archived data will be stored.

Archive Pre- Required prefix to the archive folder.

fix

Legacy Allows legacy connections to the server

Port

Database The port the server database will listen on. You can leave this field blank if you
Port are running only one Alarm Server on the machine, in which case the default
port number will be used.

295
Chapter 13: Implementing Clustering

3. Click the Add button to append a new record, or Replace if you have modified a rec-
ord.
See Also
Alarm Server Side Synchronization
Reports Server Definitions

Alarm Server Side Synchronization

In v7.40 with the implementation of a primary (main)/standby (non-main) alarm server
model, synchronization has changed. With this new model the concepts main-main, and
duty mode have been introduced.
Synchronization occurs when the primary server establishes or re-establishes a con-
nection with the standby server. Synchronization takes place on startup and then peri-
odically during runtime while connection exists between the Primary and stand by
servers. During synchronization the Primary server (or main) updates the data on the
standby sever as required with alarm action and event data.
Each time the alarm primary server connects to the standby server, the synchronization
process will take place. This will allow primary server to update the standby server with
the most recent copy of the primary server's data.

Note: Synchronization occurs only if the primary and standby alarm servers are run-
ning and connected.

To configure synchronization between the primary and standby alarm server refer to the
[Alarm.<ClusterName>.<ServerName>] parameters [Alarm.<Cl-
usterName>.<ServerName>] parameters in the CSE help reference.
See Also
Alarm Server Definitions

Main-Main Scenario
If the standby alarm server loses its connection with the primary alarm server, a 'main-
main' situation may occur, where both servers communicate and process data from the
I/O server. On reconnection the data on both servers will need to be synchronized. With
duty mode enabled by default, the servers determine what data to merge. In most
instances the data with the latest timestamp is kept while the other is discarded.

296
Chapter 13: Implementing Clustering

UNINTENDED EQUIPMENT OPERATION

In a 'main-main' situation do not make any configuration changes to your system until the
primary and standby server is reconnected. Configuration changes made to the system dur-
ing a 'main-main' situation may cause the system to become inoperative.

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

Deciding which server will be ‘Main’ after a 'Main-Main' scenario

When the connection between the servers is restored, the servers arbitrate to determine
which server continues as main and which server becomes the standby.
In CitectSCADA, when configuring the alarm server you select which server is primary
and which is standby. By default the server configured as primary is given the highest
priority, thus when the servers arbitrate to determine which becomes main, the primary
server will revert to being the main server.
See Also
Duty Mode
Alarm Server Side Synchronization
Alarm Server Definitions

Duty Mode
Duty mode enables a standby server to transfer data to a primary server following a
'main-main' situation.
When the connection between the servers is restored, the servers arbitrate to determine
which server switches to standby.
In CitectSCADA duty mode is enabled by default, and helps prevent the data on the
server that is deemed to be the standby (after the arbitration process) from not being
accessible. In duty mode the timestamps of the data on the servers are compared. The
data with the recent timestamp is kept and is merged into the data on the primary
server and the remainder of the data is discarded.
When the primary server receives the more recent data, from the standby server, it
merges the data with its own data and then sends an update to the standby server. This
allows for primary and standby server to operate with synchronized data sets.
See Also
Duty Mode
Alarm Server Side Synchronization

297
Chapter 13: Implementing Clustering

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 will belong. If there is
Name 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 to the project and
Name not contain spaces.

Network The network address(es) of the server being configured. To specify dual
Addresse- network connections to the server, use a comma delimited list. See Network
s Redundancy.

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.

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

298
Chapter 13: Implementing Clustering

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 Name The name of the cluster to which this Trends Server will 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 Name The name of the server. The name needs to be unique to the project and
not contain spaces.

Network The network address(es) of the server being configured. To specify

Addresses dual network connections to the server, use a comma delimited list. See
Network Redundancy.

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.

Comment Any useful comment. This property is optional and is not used at run-
time.

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.

299
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
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 Name The name of the cluster to which this I/O Server will belong. If there is
only one cluster defined in the project, you can leave this field blank.
The I/O Server will default to the defined cluster. 16 characters max-
imum.

Server Name The name of the server. The name needs to be unique to the project and
any included projects, and not contain spaces. 16 characters max-
imum.

Network The network address(es) of the server being configured. To specify

Addresses dual network connections to the server, use a comma delimited list. See
Network 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 run-
time. 48 characters maximum.

Extended forms fields

The following fields are implemented with extended forms (press F2).

300
Chapter 13: Implementing Clustering

Note: Servers listen on legacy ports only if the INI parameter [LAN]Ear-
liestLegacyVersion 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 graphics page objects to a cluster at Runtime

CitectSCADA includes functionality that allows you to assign the objects on a graphics
page to a specific 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.

Note: CitectSCADA will automatically resolve tags without a cluster context spec-
ified if every tag name in the project is unique. See Resolving cluster context with
unique tag names.

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:

301
Chapter 13: Implementing Clustering

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

302
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 Reports, and Trends Server Redundancy
l Alarm 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
Reports, and Trends Server Redundancy
How CitectSCADA handles file server redundancy
How CitectSCADA handles FTP server redundancy
Redundancy of Standalone Systems

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

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

305
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

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

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

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

309
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:

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

311
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:
l If LAN 1 is suddenly inoperative, each component in the cluster can easily maintain
connection by using LAN 2.

312
Chapter 14: Building Redundancy Into Your System

l In turn, if LAN 2 becomes inoperative, LAN 1 remains in operation.

Server Redundancy

For information about server redundancy, see Reports and Trends Server Redundancy
and Alarm Server Redundancy.
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, "AlarmPrimaryLAN1,
AlarmPrimaryLAN2".
See Also
Network redundancy

Reports and Trends Server Redundancy

Redundancy of 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 com-
ponent, effectively enabling you to specify a complete and unique network connection
from a client to a server. See Network Redundancy.
Consider the following diagram:

313
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 Trend and Report servers, when the inoperative primary server returns online,
the client will remain with the standby unless the primary has a higher priority.
l For Reports, and Trends Server redundancy, clients connect to either the Reports, or
Trends primary server or standby server. On startup, clients try to establish a con-
nection 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 pri-
mary server becomes available, any clients connected to the standby server remain
connected to the standby server unless the primary has a higher priority. If the
standby server becomes inoperative the client will revert to the primary server. The
priority is set using the connectivity parameters described below.
In v7.40 Alarm Server Redundancy has been modified to be a main/standby model.
Refer to Alarm Server Redundancy for more information.

314
Chapter 14: Building Redundancy Into Your System

Connectivity Parameters

The client sub system runs in every SCADA client or server process. It connects to all
servers within all clusters that are enabled, allowing any process to send data requests
to any other server, either through internal systems or Cicode function calls.
Two Citect.ini parameters allow you to configure how the client sub system will manage
its connections to redundant pairs of Reports or Trends servers.
These parameters are [Type.ClusterName.ServerName]Priority and [Type.Clu-
sterName.ServerName]DisableConnection, where Type is the relevant server type (Report
orTrend). The default setting for these parameters provides behavior as described above,
in that if the client sub system is redirected to a standby server it will retain a connection
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.
The connectivity parameters can be set at the system level using the Parameters form of
the project, or specifically for each pc in the local Citect.ini file.
For a detailed explanation of these parameters see:

[Report.ClusterName.ServerName]Priority
[Trend.ClusterName.ServerName]Priority
[Report.ClusterName.ServerName]DisableConnection
[Trend.ClusterName.ServerName]DisableConnection

in the Parameters online help

See Also
Alarm Server redundancy
Reports Server redundancy
Trends Server redundancy
File server redundancy
FTP server redundancy

Alarms server redundancy

In v7.40 to improve alarm server redundancy you can now configure a main/standby
pair. To keep with the terms used in previous versions of CitectSCADA the main server
is called the primary server.

315
Chapter 14: Building Redundancy Into Your System

With a primary/standby pair only one server (the primary) updates the database. How-
ever, the display client is able to communicate with both the primary and standby
servers.
On starting up the display client will always attempt to connect to the ‘main’ (primary)
server. By default the alarm server which starts first will become ‘main ‘.
In the event the primary server becomes inoperative (including loss of communication
with the IO Server), the standby server takes over the duties of the primary server and
will process Alarm data and update the database. When the inoperative server resumes
operations, it will communicate with the other alarm server (which is now the main)
and become the standby server.

316
Chapter 14: Building Redundancy Into Your System

During synchronization, the primary server updates the standby server. This ensures
that the standby server contains data that accurately represents the data on the primary
server.

Note: Before starting your system for the first time (i.e. the database is empty) the pri-
mary and standby server should be connected. If not connected when the system
starts, the primary and standby servers may create distinct ids for the same objects.

If you want to choose which server the display client will communicate with use the
[Alarm.<ClusterName>.<ServerName>]Priority. This parameter assigns a higher priority
to either the primary or standby server. In this instance the client on starting up will
communicate with the server assigned the highest priority, regardless if the other server
started first and is therefore the main.
See Also
Reports Server Redundancy
Alarm Server Side Synchronization

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.

317
Chapter 14: Building Redundancy Into Your System

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

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

318
Chapter 14: Building Redundancy Into Your System

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:\Documents and Settings/All
Users/Application Data/Schneider Electric/CitectSCADA v7.40/User
(Vista and later C:\ProgramData/Schneider Electric/CitectSCADA v7.40/User).
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 cor-
rectly set.

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

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.

319
Chapter 14: Building Redundancy Into Your System

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

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

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

322
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
programs. 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:

323
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;

324
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…);

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

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

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

IO Server parameters

328
Chapter 15: Communicating with I/O Devices

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]MaxEventsQueued
l [IOServer]MaxEventsDrop
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

329
Chapter 15: Communicating with I/O Devices

The Express Communications Wizard provides default values and a setup tai-
lored to the communications requirements of a selected I/O Device.

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

330
Chapter 15: Communicating with I/O Devices

l Using an Ethernet card

l Using a Proprietary board/intermediary software

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.

331
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

332
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

333
Chapter 15: Communicating with I/O Devices

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

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

334
Chapter 15: Communicating with I/O Devices

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.

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.

335
Chapter 15: Communicating with I/O Devices

Note: You only need to define the TCP/IP board once. You can then add several ports
that use the same CitectSCADA 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.
l -Ia.b.c.d: defines remote IP address to connect to.
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. IP address joins a multicast group listening
for UDP multicast packets. For the parameter to work configure the -LP local port
switch, so the driver selects the correct port on the multicast IP to listen on.
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 -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.
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

336
Chapter 15: Communicating with I/O Devices

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.

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.

337
Chapter 15: Communicating with I/O Devices

Creating a communications test project

To verify that CitectSCADA can bring your I/O Devices online, it is recommended you
create a test project.
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.

338
Chapter 15: Communicating with I/O Devices

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

339
Chapter 15: Communicating with I/O Devices

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

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.

340
Chapter 15: Communicating with I/O Devices

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

341
Chapter 15: Communicating with I/O Devices

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

342
Chapter 15: Communicating with I/O Devices

Options Description

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:

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.

343
Chapter 15: Communicating with I/O Devices

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

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

344
Chapter 15: Communicating with I/O Devices

Option Description

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.

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

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.

345
Chapter 15: Communicating with I/O Devices

Option Description

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

346
Chapter 15: Communicating with I/O Devices

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

347
Chapter 15: Communicating with I/O Devices

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

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.

348
Chapter 15: Communicating with I/O Devices

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

349
Chapter 15: Communicating with I/O Devices

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.

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.

350
Chapter 15: Communicating with I/O Devices

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

351
Chapter 15: Communicating with I/O Devices

7. In the Startup mode field select the type of I/O Device redundancy:

Primary Enable immediate use of this communications chan-

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

Stand- This channel will remain unused until the I/O Device
byWrite configured with the primary channel becomes
inoperative. Write requests sent to the primary chan-
nel are also sent to this channel.

Note: Do not use this mode for scheduled I/O

devices because there is the possibility that the
Standby I/O device write queue will never be
cleaned up. When writing to a scheduled I/O device
which it is not communicating, write requests are
queued up until communication resumes. In case of
using I/O device redundancy and StandbyWrite
mode, Primary and Standby I/O devices have their
own queues of pending write requests. If I/O device
communication is controlled automatically by the
communication schedule, then both queues are
flushed when the schedule dial-time occurs. Where
manual communication is controlled by the IODe-
viceControl Cicode function, only the Primary I/O
device write queue is flushed and the Standby I/O
device write queue will never be cleaned up.

Note: To use Standby or StandbyWrite modes, you need to

also configure a Primary I/O Device with the same I/O Device
name, number and address.

8. In the Priority field type the order standby devices are promoted in if a primary I/O
Device becomes inoperative during runtime. 8 characters maximum.
If there is more than one standby I/O Device configured for a cluster, you can use
this field to give precedence to a particular standby device. If this field is left
blank, priority will be automatically allocated to the device during project com-
pilation, based on the priority settings of other standby devices and/or the order
the devices were configured in.
See I/O Device promotion.
9. In the Memory field, specify whether the I/O Device runs in Memory mode. 8 char-
acters maximum. The default value is FALSE. If you select TRUE, the I/O Device will
be created in memory and its values stored in memory at runtime. This may be

352
Chapter 15: Communicating with I/O Devices

useful if you are testing your system, before connecting physical I/O Devices, as mem-
ory mode stops CitectSCADA from communicating with physical I/O Devices. See
Using Memory Mode.

Note: If a device is configured with Memory set to TRUE, the Port Name and
Address fields can be left blank as they will not be used by the compiler or the I/O
server at runtime.

10. In the Comment field, type in any useful comment. This field is optional and is not
used at runtime.
11. Click Add to add a new record, or Replace to replace an existing one.
See Also

Fields implemented with extended forms (press F2).

Communicating with Dial-up Remote I/O Devices

I/O Devices Properties Extended

Extended forms fields

The following fields are implemented with extended forms (press F2).
Linked
Determines whether or not the I/O Device is linked to an external data source. If you link
to an external data source, CitectSCADA is updated with any changes made to the exter-
nal 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
database or you can delete them from CitectSCADA's variable tags database altogether.
If an I/O Device is linked to an external data source the Database Type, External Data-
base, Connection String, Tag Prefix and Live Update fields will be greyed out.
Database Type
The format of the data referenced by the external data source.
External Database
The path and filename of the external data source for the I/O Device. Alternatively, you
can enter the IP address/directory, computer name, or URL of a data server, etc. (for
example "C:\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").
Click Browse to select a path and filename.
Connection String

353
Chapter 15: Communicating with I/O Devices

Enter a connection string to provide connection details for the data source. This is sim-
ilar to an ODBC connection string. For example:

UserID = XXX; Password = YYY

ServerNode=111.2.3.44; Branch=XXX

Not every data source needs a connection string.

Tag Prefix
The prefix that will be inserted in front of the names of linked tags in CitectSCADA's var-
iable tags database (for this I/O Device only). To change the prefix, delete it first, perform
a manual refresh, then add the new prefix.
Automatic Refresh
Determines whether the linked tags in CitectSCADA's variable 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, dis-
play the variable using the Variable Tags form, modify 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

Note: This field is only available if you have installed one of the CitectSCADA Fast-
Linx products.

Controls whether or not the linked tags in CitectSCADA and an external tag database
will be synchronized if either database is changed. To enable live linking, choose Yes
from the Live Update menu.
When Live Update is enabled and the variable tag database is accessed (for example,
during project compilation or when a drop-down list is populated), CitectSCADA queries
the external tag database to 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 automatically into the external tag data-
base.
Log Write

354
Chapter 15: Communicating with I/O Devices

Enables/disables the logging of writes to the I/O Device. When enabled, writes are logged
to the SYSLOG.DAT file in the logs folder of the CitectSCADAUser and Data folder
selected during installation, also specified in the INI file as [CtEdit]Logs. See Tag Func-
tions for information about TagWriteEventQue and logging tag data.

Note: Logging writes to every I/O Device may slow communications as the Citect-
SCADA system will be writing large amounts of data to disk. However, logging of
writes is useful when debugging a system.

Log Read
Enables/disables the logging of reads from the I/O Device. When enabled, reads are
logged in the CitectSCADA SYSLOG.DAT file.

Note: Logging reads to every I/O Device may slow communications as the Citect-
SCADA system will be writing large amounts of data to disk. However, logging of
reads is useful when debugging a system.

Cache
Enables/disables data caching. When enabled, a cache of the I/O Device's memory is
retained at the I/O Server, thus improving communications turn-around time.

Note: Data caching has to be enabled for scheduled I/O Devices, but disabled for
memory or disk I/O Devices.

Cache Time
The cache time specified in milliseconds. When caching is enabled, data that is read
from a I/O Device is stored temporarily in the memory of the I/O Server. If another
request is made (from the same or another client) for the same data within the cache
time, the CitectSCADA I/O Server returns the value in its memory - rather than read the
I/O Device a second time. Data caching results in faster overall response when the same
data is needed by many clients.
A cache time of 300 milliseconds is recommended.
The Cache Time for a scheduled I/O Device is automatically calculated. You can view a
scheduled I/O Device's cache time using the Kernel Page Unit command.
Background Poll
Specifies that tags for a particular device are continuously polled at a minimum back-
ground poll rate. The options are True or False. Set this field to True if you are operating
on a slow network, with a slow device, or where tags may normally only be polled
infrequently.

355
Chapter 15: Communicating with I/O Devices

Background Rate
When Background Poll is set to True, specifies the minimum rate by which the device
will be polled. You may select any predefined value from the drop-down list, or enter
your own in the format of HH:MM:SS. If you do not enter a value, the default value of
30 seconds will be used.
Min Update Rate
The DataSource will send tag update value notifications to subscription clients after a
pre-defined period of time expires. You may select any predefined value from the drop-
down list, or enter your own in the format of HH:MM:SS. If you do not enter a value, the
default value of 0 seconds will be used and no update value notifications will be sent.
Staleness Period
Staleness period represents total number of seconds that will elapse after the last update
before extended quality of the tag element is set to "Stale". You may select any predefined
value from the drop-down list, or enter your own in the format of HH:MM:SS. If you do
not enter a value, the default value of 0 seconds will be used and tag elements will not
be set to "Stale".

Note: For further information on Minimum Update Rate and Staleness Period refer to
Reading and Writing Tags.

Scheduled
Determines whether the I/O Device is configured for scheduled communications. This is
normally set using the Express Communications Wizard.

Note: If you do not specify a schedule for a dial-up remote I/O Device, the connection
will be established at startup and will remain connected until shut-down.

See Scheduled Communications.

Time
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 will not wait until the next day to begin com-
municating. It will operate as if your project had been running since before the start time.
Connect Action (254 Chars.)
Cicode to be executed once communication with the I/O Device has been established
(and before any read or write requests are processed).
Period

356
Chapter 15: Communicating with I/O Devices

The time between successive communication attempts. The period needs to be long rel-
ative to the driver's watchtime and the [Dial]WatchTime. If necessary, decrease these
watchtimes or increase Period to help ensure that Period is more than double the watch-
times.
Examples (based on a Synchronize at time of 10:00:00):
1. 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.
2. If you enter 12:00:00, 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, and so on.
The I/O Server 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.
3. If you enter 3 days, and start your project at 9 a.m. on a Wednesday, 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.
4. 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.
Select On Startup for a persistent connection. To disconnect a persistent connection, you
need to call the IODeviceControl() function with type 8.
Disconnect Action (254 Chars.)
Cicode to be executed once communication with the I/O Device has been terminated
(and after read and write requests are processed).
Phone Number (64 Chars.)
The telephone number that needs to be dialed to initiate contact with the I/O Device. (i.e.
for dial-up remote I/O Devices)
Caller ID (32 Chars.)
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 send the
caller ID, not the modem. This is because using the modem to send the ID will send
the same ID no matter which I/O Device the call is relevant to. This makes it difficult

357
Chapter 15: Communicating with I/O Devices

for you to identify the I/O Device that triggered the call.

By using the I/O Device to send the ID, the I/O Server will receive a unique caller ID for
each I/O Device. However, some I/O Devices are not capable of sending caller IDs. If you
are multi-dropping, use I/O Devices that can send caller IDs.
Persist
Set to TRUE or FALSE to indicate if the persistence of the tag cache file is on or off.
Default is TRUE and the data will be written to the XML file as described in "File Name"
below. If one of the primary/standby I/O devices (identified by the same network
number) has persistence set to FALSE, then every device has it turned off.
Persist Period
Indicates how often to persist the XML cache file to disk. Default is 10 minutes
(00:10:00). Normally, the period used is the highest value specified for one of the pri-
mary/standby I/O devices (identified by the same network number).
File Name
Indicates the path to the file on disk where the XML cache will be stored. You can spec-
ify just the path or the path with the actual file name. The default is Data directory using
the format <ClusterName>.<IOServerName><ClusterName>.<IODeviceName>.cache. If
the location cannot be created, then either the default path, default file name or both is
used. Normally, the path used is the first non-empty path specified for one of the pri-
mary/standby I/O devices (identified by the same network number).
See Also
Communicating with Dial-up Remote I/O Devices

Working With Device Drivers

Drivers enable CitectSCADA to communicate with the devices in your system. Every
communication setup in CitectSCADA needs drivers to implement the protocol and
transport. Often this means two separate drivers, but in some cases both are combined
into one driver – termed a ‘board’ driver.
CitectSCADA has over 140 device drivers available, enabling communication with a
vast array of production devices across several communication types. These include
generic drivers that support industry-standard protocols such as OPC and Modbus.
The driver you will need to communicate with a particular device is determined by:
l the device itself
l the communication protocol the device supports

358
Chapter 15: Communicating with I/O Devices

l the communication channel used to connect the device to the CitectSCADA I/O
Server.
To add a particular device to your CitectSCADA project, you will need to determine the
driver necessary to support it. If the particular driver is not installed with your current
version of CitectSCADA, you will have to obtain a driver pack and install it separately.

Note: The word ‘driver’ is often used when referring to communications. A driver is
a component piece of software that implements a protocol or transport (or both). Driv-
ers are modular, such that new drivers can be easily ‘plugged-in’ to existing systems.

See Also
Determining Which Driver To Use
Installing a Driver Pack

Determining Which Driver to Use

To connect a device to CitectSCADA, you will initially need to determine which driver is
necessary to support communication with the I/O Server. In most cases, you can use one
of the following methods:
l a native driver, engineered specifically for the device
l a generic driver, available for devices that support industry-standard protocols such
as Modbus or DNP
l an OPC Server, with communication taking place via a third-party application
initially check if a native driver is available. To do this, go to the Supported Devices
page in the Driver Reference Help and locate the device you are trying to connect to.
The list is sorted alphabetically by manufacturer name. (To access the Driver Reference
Help, select Driver Help from the Help menu in Citect Explorer and Project Editor.)
If the device is not included on the list, consider the communication capabilities of the
device to determine if it supports any industry-standard protocols, such as Modbus,
DNP, COMLI or SNMP. If this is the case, you may be able to use one of the generic
CitectSCADA drivers that support these standards.
Similarly, you can use OPC to connect a device to CitectSCADA, however this will
require the purchase of a third party application to establish an OPC Server. If you take
this approach, use an OPC Server application recommended by the manufacturer of the
device you are trying to connect.
If these options do not provide an appropriate solution, you can contact Technical Sup-
port for this product.

359
Chapter 15: Communicating with I/O Devices

Note: Check the Citect Driver Web at http://www.Citect.com/driverweb for infor-

mation about driver updates and new driver pack releases.

Installing a Driver Pack

If a necessary driver is new, or has been recently updated, it may not be included among
those installed with your current version of CitectSCADA. If this is the case, you will
need to obtain a Driver Pack and install it separately. See the Citect Driver Web at
http://www.citect.com/driverweb.
You need to install a driver pack on the computer that will connect to the target device.
This computer needs to be configured as a CitectSCADA I/O Server. It needs to be also be
installed on any machines where the CitectSCADA project is compiled.
Before installing the driver pack, close your CitectSCADA runtime environment and
Citect Explorer. You need administrator permissions for the I/O Server PC.
To install a driver pack:

1. Save the driver pack to an appropriate location on the I/O Server PC.
2. Double-click the EXE file to launch the installation.
3. Follow the instructions provided by the installation Wizard.
4. You are prompted to select the CitectSCADA installation folder. If you installed Citect-
SCADA in a different folder to the default, browse to that location. An alert message
will alert you if you have selected the wrong folder.
5. Click Finish to complete the installation.
After you have installed a Driver Pack, the associated help will be automatically merged
into the Driver Reference Help.

Note: If you are installing a driver pack on an older version of CitectSCADA that pre-
cedes the initial release of the driver, the supporting help may not appear auto-
matically in the Driver Reference Help. If this is the case, you can locate the driver
help in the CitectSCADA bin directory. The help file will be named <driv-
ername>.chm.

The Driver Update Utility

The Driver Update Utility is a tool that determines whether an update is available for
the CitectSCADA drivers you have installed on a computer. It achieves this by scanning
a PC and comparing the locally installed drivers with those available on the Citect
Driver Web.
When a scan is finished, a merged list of drivers is displayed. Each will fall into one of
the following categories:
l Recommended Updates: drivers that you have installed for which there is a newer
version available.
l Newly Available: drivers that you do not have installed that were recently released.
l Installed And Current: drivers that you have installed that match the latest version
available.
l Unofficial Version Installed: drivers that you have installed that are newer than the
version available on the DriverWeb. This would usually mean that you are running a
tech preview or field test version, or you have a Hotfix installed.
Once you have viewed the list, you can download a driver update (or any of the new
drivers) directly from the Update Utility.
Installation
The Driver Update Utility operates independently to CitectSCADA and is installed sep-
arately. The installer is available in the Extras directory on the CitectSCADA installation
disk, or you can obtain a copy from the Citect DriverWeb at http://ww-
w.citect.com/driverweb.

Note: The Driver Update Utility needs an Internet connection to operate successfully.
It uses a secure 128-connection when connecting to the DriverWeb.

Using the Driver Reference Help

Each driver, whether it is installed with CitectSCADA or as part of a driver pack, is sup-
ported by the Driver Reference Help.
This where you will find the specific reference information related to each driver. This
information includes:

361
Chapter 15: Communicating with I/O Devices

l the device(s) each driver supports

l the address used to identify and locate a device
l any necessary device setup information
l the information necessary to configure a device in your CitectSCADA project
l the data types each driver supports
l parameters you can use to customize a driver
l driver-specific errors
Much of this information you will need to establish communication with a device; some
of it is more suited to advanced engineering tasks and troubleshooting.
To access the Driver Reference Help, select Driver Help from the Help menu in Citect
Explorer and Project Editor.
If you familiarize yourself with the processes explained in Setting Up Communications,
you will be instructed on how to use this information to configure devices within a
CitectSCADA project.

Customizing Communication Using Citect.ini Parameters

UNINTENDED EQUIPMENT OPERATION

l Do not under any circumstances change or remove any of the undocumented

Citect.ini parameters.
l Before deleting sections of the Citect.ini file, confirm that no undocumented param-
eters will be deleted.
Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

Note: Always seek the advice of Technical Support personnel regarding undoc-
umented features.

Citect.ini parameters can be used to tune the performance of a CitectSCADA driver and
perform runtime maintenance diagnostics.
You can customize the way CitectSCADA communicates with the a driver (and even
individual PLCs) by creating or editing the section of the Citect.ini file named after a spe-
cific driver, for example, [MODBUS].
There are some ini parameters that are common to every CitectSCADA driver, as well as
custom parameters unique to each driver.

362
Chapter 15: Communicating with I/O Devices

See the Driver Reference Help (Help menu | Driver Help) for the ini parameters related
to each driver, and their default values.
When CitectSCADA starts at runtime, it reads configuration values from the Citect.ini
file that is stored locally. Therefore, any configuration settings needs to be included in
the Citect.ini file located on the computer acting as the I/O Server to the devices in the
system.
By default, CitectSCADA looks for the Citect.ini file in the CitectSCADA project\bin direc-
tory. If it can't find the file there, it searches the default Windows directory.

Using a Disk I/O Device

In addition to connecting to actual I/O devices, CitectSCADA supports the configuration
of disk I/O devices, which exist only within your computer. The value of each variable
in the disk I/O device is stored on your computer's hard disk.

Note: With the release of version 7.20, a feature called persistence can be applied to
I/O devices in memory mode. 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 information.

Once configured, disk I/O devices appear exactly as any other I/O device in your system,
but are not connected to any field equipment. Disk I/O devices can contain any type of
variable supported by CitectSCADA, and you can configure them to emulate any sup-
ported I/O device. You can also specify a generic protocol for a disk I/O device.
A disk I/O device is useful when the status of your plant needs to be restored after a
planned or unplanned system shutdown. You can configure your system to continually
update a disk I/O device with the subset of variables that defines the status of your
plant. When you restart your system after a shutdown, CitectSCADA can restore this
status immediately.
You can also use disk I/O devices for storing predefined data that needs to be recalled
immediately when a process is necessary (for example, in a simple recipe system).

Note: If you create a RAM disk in the computer for the disk I/O device, you are not
required to create or copy the disk file to the RAM disk. CitectSCADA automatically
creates a disk file on startup. Do not set up your Disk I/O device on a RAM disk if
you want the data written to it to survive a power cycle of the Servers.

Redundant Disk I/O Devices

Using Memory Mode

Disk I/O Device setup

To set up communications with a device, follow the basic steps given in the I/O Device
setup procedure below.
Sometimes you might need to edit the communications forms directly. They require the
following specific information.
l You are not required to complete a Boards dialog box.
l You are not required to complete a Ports dialog box.
l Complete the I/O Devices dialog box as follows.
Perform the setup by entering the following information:

Text Box Required information

I/O Device A name or your Disk I/O Device, for example: DISK_PLC. Each I/O
name Device needs to have a unique name in the CitectSCADA system.

I/O Device A unique number for the disk I/O Device (1-4095). Each I/O Device
number needs to have a unique number in the CitectSCADA system.

I/O Device The path and filename of the disk file, for example:
address
[RUN]:DSKDRV.DSK

If you are using redundant disk I/O Devices, specify the path to both
the primary file and the Standby file in the configuration of both disk
I/O Devices.

For example, if this is the primary disk I/O Device, enter:

Primary_File, Standby_File

If this is the Standby Disk I/O Device enter:

Standby_File, Primary File

Primary_File is the name (and path) of the primary disk I/O Device
file. You may use path substitution in this part of the field.

Standby_File is the name (and path) of the Standby Disk I/O Device
file. You may use path substitution in this part of the field.

Notes:

l If the specified disk I/O device file is not found, CitectSCADA

creates a new (empty) file with the specified filename.
l To use redundant disk I/O devices, you need to use a network

364
Chapter 15: Communicating with I/O Devices

Text Box Required information

that supports peer-to-peer communication.

l Disk files need to have write permission (on both primary and
standby servers).
l The frequency with which CitectSCADA writes data to the disk I/O
device(s) is determined by the [DiskDrv]UpDateTime parameter.

I/O Device To use the CitectSCADAgeneric protocol, enter: GENERIC

protocol
- or -

To select a specific protocol supported by CitectSCADA, see the I/O

Devices online Help.

I/O Device You need to use: DISKDRV

port name

I/O Device Any useful comment.

comment

I/O Device If not using redundant disk I/O Devices, leave this property blank.
startup
mode If you are using redundant disk I/O Devices, use either:

Primary: Enable immediate use of this disk I/O Device

StandbyWrite: This disk I/O Device will remain unused until the com-
puter with the primary disk I/O device configured becomes inoperative.
Every write request sent to the primary disk I/O Device is also sent to
this disk I/O Device.

To use StandbyWrite mode, you need to also configure an I/O disk

device in the primary server. Both I/O Devices need to have the same
I/O Device name and number.

I/O Device Leave these properties blank.

Log Write,
Log Read,
Cache and
Cache Time

See Also
Redundant Disk I/O Devices
Disk I/O Device Errors

Redundant Disk I/O Devices

If using a network, you can configure a redundant disk I/O Device to minimize the poten-
tial for data loss (in the event the server becomes inoperative). This diagram illustrates
the use of redundant disk I/O Devices:

365
Chapter 15: Communicating with I/O Devices

When the system is operating, CitectSCADA reads and writes runtime data to the disk
I/O Device configured in the primary server. It also writes runtime data to the disk I/O
Device configured in the standby server. (CitectSCADA maintains both disk I/O Devices
identically.)
If the primary server becomes inoperative, the Disk I/O Device in the standby server is
activated without interrupting the system. When the primary server becomes active,
CitectSCADA automatically returns control to the primary server, and copies the Disk
I/O Device from the standby server to the primary server. The Disk I/O Device in the
standby server reverts to its standby role.
To define a redundant disk I/O Device:

1. Configure a new disk I/O Device

2. Select StandbyWrite for the Startup Mode.
For redundant disk I/O Devices, you need to use Microsoft Networking (or another peer-
to-peer network), and the hard disk of the standby server (the directory where the disk
I/O Device file is stored) needs to be shared. Use Windows Explorer to set the directory to
shareable.
See Also
I/O Devices Properties
Performance Considerations
Disk I/O Device Errors

Disk I/O Device Errors

The following errors, listed in order, are specific to the CitectSCADADISKDRV driver

366
Chapter 15: Communicating with I/O Devices

Errors Message

48 Error Opening DiskFile

49 Error in DiskFile Header

50 DiskFile Header contains invalid variable

51 DiskFile out of memory error

52 Read Error in DiskFile

53 Write Error in DiskFile

54 Seek Error in DiskFile

55 Error creatng queue

56 Error creating thread

57 Error creating event

See Also
Disk I/O Device Setup
Redundant Disk I/O Devices

Using Memory Mode

When configuring an I/O Device, you have the option to set them to memory mode. This
means that the I/O Device will be created in memory and its values stored in memory at
runtime.
Refer to I/O Devices Properties for more information on how to configure an I/O Device.
Devices using memory mode are not connected to any hardware and write their values
to a cache. The I/O Device values can be read by many processes. The difference between
a local variable and a device in Memory Mode is that an I/O Device in Memory Mode
will reside in the I/O Server's memory and will observe standard networking and redun-
dancy rules of a standard I/O Device.
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.
An I/ODevice with Memory set to TRUE or FALSE will behave differently in instances
where Variable Tags share the same address.
For example:
Define a MODNET IODevice:
1 - INT1 (INT Tag)
2 - DIG1 (DIG Tag for bit0 of INT1)
3 - DIG2 (DIG Tag for bit1 of INT1)
At runtime the Display Client will show:

367
Chapter 15: Communicating with I/O Devices

1. IODevice Memory mode = FALSE, at runtime setting DIG1 = 1, DIG2 = 1, INT1 = 3,

modifiyng DIG1 and/or DIG2 affects INT1.
2. IODevice Memory mode= TRUE, at runtime setting DIG1 = 1, DIG2 = 1, INT = 0 or
cached value, modifiyng DIG1 and/or DIG2 does not affect INT1.
In both instances the Override and Control Mode settings for each tag (INT1, DIG1,
DIG2) did not affect the other tag. Setting INT1 in Override or Control Inhibit mode did
not set DIG1 or DIG2 in Override or Control Inhibit mode.
As with local variables, values in an I/O Device using only memory mode are not
retained when you shut down. However, if you set the Persist field to TRUE in the in the
extended section of the I/O Devices Properties dialog their values will be retained. For
more information on local variables, refer to Configuring Local Variables.
See Also
I/O Devices Properties
Persisted I/O Memory Mode

Using Persisted I/O Memory Mode

Since the release of version 7.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.
You can also create a persisted memory I/O device using the Express Communications
Wizard. When this type of device is selected, the wizard creates a new I/O device with
the Address and Port Name properties left blank, Memory set to “TRUE”, and Persist
set to “TRUE”. The File Name field is left empty to allow runtime to generate a default
cache file name. This file will be located in the [DATA] directory.

Migrating Disk I/O devices

When applied to I/O Devices in memory mode, persistence provides an improved alter-
native to a disk I/O device, as synchronization is supported in scenarios where a server
becomes unavailable for a period of time.
Many customers use disk I/O devices to provide system-wide global variable tags that
are managed by I/O servers and are persisted to disk to maintain their latest values.
Disk I/O devices take advantage of the standard I/O system redundancy features, such
that, if one I/O server is unavailable, another can provide client(s) with tag values. They
also perform a level of synchronization by using features such as standby write and by
providing redundant paths to the persisted binary data files, so that, at startup of an I/O
server, the latest value can be read into the system from the latest modified data file.

368
Chapter 15: Communicating with I/O Devices

However, there is no synchronization when network connections are inoperative and

regained, resulting in several scenarios in which redundant disk I/O devices can end up
with different values for the same tag. For this reason, it is recommended that data
assigned to disk I/O devices be migrated to the new persisted memory I/O mode avail-
able in version 7.20.
To migrate disk PLC devices to persisted I/O memory mode:

1. Perform the procedures listed in Upgrading to CitectSCADA 7.20, as is appropriate.

2. On the I/O Device dialog, for disk I/O devices set Background Poll to TRUE and set
Persist to TRUE (the default setting).
3. Start the I/O server up and wait for a few minutes so that the background poll
updates every tag.
4. Shutdown the I/O server.
5. On the I/O Device dialog, for disk I/O devices set Background Poll back to FALSE, set
Memory to TRUE and clear out the Port Name field as it is not necessary for Memory
Mode.
6. Restart the I/O server to finish the migration to persisted memory I/O mode, with
your devices now containing your original values from the disk I/O device.
See Also
Using Memory Mode

Troubleshooting Device Communications

Debugging device communications involves the following processes:
l gathering system information about current communication status
l analyzing the available information to identify problems
The information needed to facilitate this is available from the following resources:
l hardware alarms
l driver errors
l log files (system, trace, debug and driver logs)
This information can be analyzed directly to identify problems, or you can use the Citect-
SCADA Kernel to perform low-level diagnostic and debugging operations.
There are also procedures you can follow to debug low-level communications protocols,
such as COMx and TCP/IP.
See also
Gathering communications information
Debugging communications

369
Chapter 15: Communicating with I/O Devices

Gathering information about device communication

If you cannot establish communication with a device, check the following resources for
evidence of a problem:
l Hardware alarms
l CitectSCADA log files
l Driver errors
l Citect Kernel

Hardware Alarms

When an error occurs in a CitectSCADA operation, a hardware alarm is generated. Hard-

ware alarms are typically displayed on a dedicated page within a project, allowing an
operator to monitor the status of a system's infrastructure.
Hardware alarms will indicate if break in communications has occurred, if Cicode can't
execute, if a server becomes inoperative, and so on. If you are having problems com-
municating with a device, initially check the hardware alarms page for evidence of an
error.
See Hardware Alarms.

CitectSCADA log files

CitectSCADA supports a number of log files that track operational status during run-
time.
The primary log file, syslog.dat, contains a log of system information; from low-level
driver traffic and Kernel messages, to user-defined messages.
The Log Read and Log Write fields in the I/O Devices Properties dialog determine if log-
ging is enabled for each I/O device.
Driver logs are also available. These relate to the operation of a particular driver and are
named accordingly. For example, the ABCLX driver is logged in 'ABCLX.dat'. However
some driver logs may be in differing locations, refer to the help for a particular driver to
confirm the location.
For a description of the available log files and where they are stored, see Log files.

Driver errors

There are two types of driver errors that are logged to syslog.dat:
l generic
l driver-specific

370
Chapter 15: Communicating with I/O Devices

Generic errors are common to many drivers, and are mapped to general hardware
errors.
Driver-specific errors are unique to a particular driver. A driver will convert a specific
error into a generic error so that it can be recognized by the hardware alarm system.
However, if further investigation is necessary, you can refer to a description of the orig-
inal error in the Driver Reference Help. This includes a description of the errors asso-
ciated with each driver.
See the Driver Error Messages in the CitectSCADA Technical Reference Guide.

Citect Kernel

The Citect Kernel is a gateway into the internal workings of CitectSCADA at runtime,
and is provided for diagnostics and debugging purposes.
The Kernel can display several different diagnostic windows each providing an active
view of the CitectSCADA runtime system.
The Citect Kernel Driver window, launched via the Page Driver Kernel command, dis-
plays information about each driver in the CitectSCADA system. The statistics it
presents include read requests, physical reads, digital reads per second, register reads,
cache reads, error count, timeouts, and so on.
See Using the Citect Kernel.
See also
Debugging communications

Debugging I/O Devices and Protocols

Before commissioning any system, test communications between CitectSCADA and the
I/O Devices. Many people leave this last, only to uncover communication issues that
they cannot resolve.
The following information is provided to encourage you to test your communications
thoroughly before it becomes a time critical-element in the job. It will also help you to
debug communications and protocol conditions yourself.
See Also
Creating a communications test project
Debugging a COMx driver
Debugging a TCP/IP driver
Debugging a protocol driver using serial communications
Debugging proprietary board drivers
Contacting Technical Support

371
Chapter 15: Communicating with I/O Devices

Debugging a COMx driver

A COMx driver is the board driver typically used for serial communications. Since ver-
sion 2.01, the COMx driver allows you to dump debug information.
Three files are produced for each com port: a write file, a read file and status file. The
debug files are configured by settings in the Citect.ini and are written and are written to
the path specified in [CtEdit]Logs.
The following Citect.ini entries are used:

Parameter Default Comments

WritePortName (no value) Port name as defined in the Ports form

WriteFileSize 1000 Size in KB

WriteDebugLevel 0 1 to enable debugging, 0 to disable

ReadPortName (no value) Port name as defined in the Ports form

ReadFileSize 1000 Size in KB

ReadDebugLevel 0 1 to enable debugging, 0 to disable

StatusPortName (no value) Port name as defined in the Ports form

StatusFileSize 1000 Size in KB

StatusDebugLevel 0 1 to enable debugging, 0 to disable

CharTimeOut 11 CharTimeOut specifies the maximum acceptable

time (in milliseconds) to elapse between the arrival
of two characters on the communication line. During
a ReadFile operation, the time period begins when
the first character is received. If the interval
between the arrival of any two characters exceeds
this amount, the ReadFile operation is finished and
any buffered data is returned. A value of zero indi-
cates that interval time-outs are not used.

PassIfAnyInitPortsPass 0 Set to 1 if you wish to start when a COMx port is

missing.

Example

[COMx]
WritePortName=PORT_1,PORT_2
WriteDebugLevel=1
WriteFileSize=2000
ReadPortName=PORT_1
ReadDebugLevel=1
ReadFileSize=1000
StatusPortName=PORT_2
StatusDebugLevel=1

372
Chapter 15: Communicating with I/O Devices

StatusFileSize=10

The above example would:

l Log to "write" files up to 2000 kb of the data sent by the CitectSCADA driver to both
PORT_1 and PORT_2;
l Log to a "read" file 1000 kb of the data received by the CitectSCADA driver from
PORT_1; and
l Log up to 10 kb of status data from PORT_2 to a "status" file.
This would also result in the following text files being created:
l WPORT_1.dat
l WPORT_2.dat
l RPORT_1.dat
l SPORT_2.dat
In general, the format for the file names is "R", "W" or "S" followed by the Port name
requested, followed by ".dat". The file names represent the corresponding "Read", "Write"
and "Status" files.

File formats
The Write file will adopt the following format:

LINE 1 WRITE Debug file Started PORTNAME Debug Level 1 DOW MONTH DOM
HH:MM:SS.sss

LINE 2 HH:MM:SS.sss

LINE 3 Out W In X nBytes Y Status Z

LINES AA BB CC ..
4...

where:

W&X= Values of buffer pointers

Y= Number of bytes written

Z= Return status of the WriteFile

AA BB CC = Values in hex of each byte written

Example:

373
Chapter 15: Communicating with I/O Devices

WRITE Debug file Started PORT1_BOARD1 Mon Dec 15 16:07:.998

16:07:09.810
Out 0 In 8 nBytes 8 iStatus 997
0e 02 00 00 10 00 00
16:07:10.802
Out 8 In 16 nBytes 8 iStatus 997
0e 02 00 00 00 10 00 00
..

The Read file will adopt the following format:

LINE 1 READ Debug file Started PORTNAME Debug Level 1 DOW MONTH DOM
HH:MM:SS.sss

LINE 2 HH:MM:SS.sss

LINE 3 Out W InRx X nBytes Y Status Z

LINES AA BB CC ..
4...

where:

W&X= Values of buffer pointers

Y= Number of bytes read

Z= Number of characters remaining in the buffer

AA BB CC = Values in hex of each byte written

Example

READ Debug file Started PORT1_BOARD1 Mon Dec 15 16:07:07.998

16:07:09.830
Out 0 In 0 nBytes 8 iStatus 0
0e 02 00 00 00 10 00 00
16:07:10.822
Out 0 In 8 nBytes 8 iStatus 0
0e 02 00 00 00 10 00 00

The Status file will adopt the following format:

STATUS Debug file Started PORTNAME Debug Level 1 DOW MONTH DOM
LIN- HH:MM:SS.sss
E1

374
Chapter 15: Communicating with I/O Devices

HH:MM:SS.sss
LIN-
E2

modemStatus X
LIN-
E3

Example

STATUS Debug file Started PORT_1 Debug Level 1 Wed Nov 05

15:28:55.310
15:29:55.950
modemStatus 34
..

More parameters might be added later, so check the COMx information and the Citect
Knowledge Base regularly.
See Also
Debugging a TCP/IP driver

Debugging a TCP/IP driver

A TCP/IP driver is the low-level driver that is used for any TCP/IP communications. It
might be over Ethernet, Token Ring or Arcnet. This driver communicates between Citect-
SCADA and Winsock, so it uses the normal networking functionality of Windows. The
parameters used for TCP/IP are:
l [TCPIP]Log
Dumps the traffic between the CitectSCADA TCPIP.DLL and Winsock to a text file
called TCPIP.DAT in your Logs directory. The size of the log is governed by the
LogsSize parameter
Allowable Values:
1 - Enables logging
0 - Disables logging
Default value = 0
l [TCPIP]LogSize
Sets the default maximum size (in kilobytes) of the TCP/IP driver's log file before
wraparound occurs.
Allowable Values: any integer
Default value: 200

375
Chapter 15: Communicating with I/O Devices

l [TCPIP]LogTxRx
Log actual data Tx & Rxs besides setup info.
Allowable Values:
1- Enables logging of Tx & Rx
0 - Disables logging
Default value -= 0
l [TCPIP]NoBufferSleepTime
Sleep time in ms to wait AFTER getting a WSAENOBUFS (no system buffers mes-
sage) before reading another buffer. There is no need to adjust this.
Default value: 0
l [TCPIP]PortName
PortName to log.
Default value: * (by default every port is traced)
l [TCPIP]Timeout
Defines the timeout period between connection retries.
Default value: 1000 (ms)
l [TCPIP]PortName.MulticastAddress
This parameter allows you to implement the TCPIP driver option "-
Maa.bb.cc.dd"in the Citect.ini file. This may be necessary if you have run out of
characters in the Special Options field of the Ports Form, which is limited to 16
characters.
You need to specify the following in the Citect.ini file:

[TCPIP]PortName.MulticastAdress = aaa.bbb.ccc.ddd

where:
PortName = the name of the port as entered in the Ports Form
aaa.bbb.ccc.ddd = the multicast Class D IP address
See TCP/IP driver special options reference.

Procedure for debugging TCP/IP

Use the following steps for debugging:
1. Check if you can PING your target I/O Device. If you can't, CitectSCADA cannot talk
to it. To do this open up a Command Window and type PINGaaa.bbb.ccc.ddd where
a.b.c.d is the IP address of the I/O Device you are trying to connect to. If PING does

376
Chapter 15: Communicating with I/O Devices

not work, you need to go back to your Windows Networking and fix that.
2. Keep using your Simple As Possible Project (SAPP).
3. Delete any old tcpip.dat files.
4. Set the Debug=1 and Log=1 parameters in your Citect.ini file.
5. Start the project. From the information in the maximized Main window of the Kernel
and the TCP/IP Debug window, you can see if CitectSCADA is sending requests to
your I/O Device to initialize communications with it.
If there are no requests being sent, your software is improperly configured, and check
that there were no errors on startup of CitectSCADA. If there were errors on startup, look
them up in the Help. Also check that your computer is an I/O Server (and that it
matches the one in your project). To do this run the Computer Setup Wizard, and con-
figure the computer for a standalone configuration.
If there are requests, you can see communications between CitectSCADA and Winsock in
a separate window, which displays the requests made by CitectSCADA to connect to the
I/O Device and the corresponding response from the I/O Device. Any errors have a Win-
sock Error code that you can look up in the Microsoft Knowledge Base. If you see a Con-
nection OK message, CitectSCADA will be able to come online.
See Also
Debugging a protocol driver using serial communications

Debugging a protocol driver using serial communications

To debug a protocol driver that uses serial communications, do the following:
1. Keep using your Simple As Possible Project (SAPP).
2. Set the "DebugStr=* all" for your protocol.
3. Backup and delete both the syslog.dat and syslog.bak files. The system will recreate a
fresh version of this file the next time CitectSCADA is started.
4. Start the project. From the information you can see in the maximized Main window
of the kernel be able to see if CitectSCADA is sending requests to your I/O Device to
initialize communications with it.
If there are no requests being sent then your software is improperly configured, and
check that there were no errors on Startup of CitectSCADA. If there were errors on
startup look them up in the Online Help. Also check that your computer is an I/O Server
(and that it matches the one in your project). To do this run the Computer Setup Wizard,
and configure the computer for a standalone configuration.
If there are requests being sent but no reply, then CitectSCADA is trying to communicate.
When CitectSCADA is sending requests but getting no reply, these are the most common
causes:

377
Chapter 15: Communicating with I/O Devices

l The request CitectSCADA is sending is not getting to the I/O Device - Check the
Address field in the I/O Devices form, and verify that it is correct. If the I/O Device is
one that needs a unique identifier (such as a node address), or you need some type of
routing path, then verify that it is correct.
Check that you have the same parameters in the Ports form that the I/O Device is
using. If you have 8 data bits and the I/O Device uses 7 data bits, communications
will not work.
Check that your cable is OK. The easiest way to do this is to create a new project
and use the Loopback protocol. You can use this to verify the Tx and Rx lines'
integrity by placing a jumper on these lines. Initially test this with a jumper
between pins 2 and 3 on your PC. Then plug in your cable and test again with the
jumper between the Tx and Rx lines. Keep moving the jumper until it is at the
end of your communications bus. You can find more information on using the
Loopback protocol in the Citect Knowledge Base.
Even if the Loopback protocol shows no errors, your cable might still be respon-
sible for the loss of communications. CitectSCADA usually places a far higher con-
stant load on serial communications than programming software does, this
usually means that CitectSCADA will require much more stringent handshaking
than the programming software. So it is possible that the cable you use to program
your I/O Device works fine for programming, but not for CitectSCADA. Check the
Wiring Diagram for your Protocol in the help.
Another major cause of improper cable connections is 9-pin to 25-pin converters.
Many of these converters are made specifically for serial mice. These typically
only use the Tx, Rx and Ground signals. If you use one of these converters they
do not support any handshaking and will most likely not work for your Protocol.
If the above checks OK, use the parameters for COMx (as mentioned above) to
create log files. Examine these log files and verify that what CitectSCADA thinks it
is sending is actually what it is sending. The log files produced by using these
parameters get their information from a lower level than CitectSCADA and show
you exactly what is going through the COMx driver.
l The Response from the I/O Device is not getting to CitectSCADA - This is unlikely
and usually caused by cabling that is damaged, has insufficient bandwidth, or is con-
nected improperly.. Check your cabling as above. Also, check that you are specifying
everything you need within CitectSCADA. Many protocols require CitectSCADA to
send a unique identifier in its request packet. If this identifier is incorrect then the
response cannot get back to CitectSCADA.
l The I/O Device does not understand the Request - Every CitectSCADA protocol can
check if an I/O Device is running. Typically the protocol attempts to read data from
the I/O Device, usually a status register or other register that is there. However, many
pseudo-standard protocols, such as Modbus, do not conform to the exact

378
Chapter 15: Communicating with I/O Devices

specification for that protocol. Many protocols supplied with CitectSCADA have
some extra parameters to allow you to choose the specific initialization request from
CitectSCADA. These can be found in either the Online Help or the Knowledge Base.
Check with the manufacturer of your I/O Device to confirm that it will respond to the
request that CitectSCADA sends. If you are unsure of the request being sent for initial-
ization, use DebugStr=* to get the actual variable address that CitectSCADA is asking
for in its initialization.
Check the protocol you are using. CitectSCADA may have many different pro-
tocols for communicating to an I/O Device. PLCs such as the AB PLC5 can use dif-
ferent serial protocols, depending on the method you are trying to use. Make sure
you are using the correct one. If you are unsure, try the other possible protocols.
l The I/O Device is not functioning properly - There is usually some sort of software
from the I/O Device manufacturer that can be used to diagnose any problems with
the I/O Device.
See Also
Debugging proprietary board drivers

Debugging proprietary board drivers

Proprietary board drivers (such as the Allen Bradley KTX card, Modicon SA85 card,
Siemens TIWAY card, and so on) have their own low-level drivers. Each driver has
debugging parameters to make it easier to debug device behavior. Check the Citect-
SCADA Knowledge Base and Help for parameters. The Knowledge Base has articles
describing how to debug these board drivers.
The debugging process is exactly the same as with a serial connection:
1. Keep using your Simple As Possible Project (SAPP).
2. Set any debugging parameters for the protocol and board drivers.
3. Start CitectSCADA with clean log files.
4. Find any errors and then look them up in the manufacturer's documentation.

Serial Port Loop-Back Test

You can use the serial port loop-back test to test your serial hardware configuration. This
test can be used with any COM port, whether it is local, or on a multi-port serial board
(such as a Digiboard). The test can be performed internally or externally with loop-back
cable attached.
See Also

Test Setup

379
Chapter 15: Communicating with I/O Devices

Serial Port Loop-Back Cable

Test setup
1. Do not configure any other protocols. Temporarily delete other boards and units
while performing this test.
2. Configure a unit for each port to be tested. Make the I/O Devices form look as follows:
l Name: <unique name for the I/O Device>
l Number: <unique network number for the I/O Device>
l Address: NA
l Protocol: LOOPBACK
l Port Name: <the "Port Name" in the Ports form>
3. The following Citect.ini options are supported:
l [LOOPBACK]
LoopBack - Set this to 1 if internal loop-back is to be performed (make sure this is
deleted after running the test). When set to 0, a loop-back connector which ties
pins 2 and 3 together is necessary at each port.

Note: The COMx driver does not support internal loop-back. The external loop-
back is the default mode.

Size - Sets the maximum frame size. The length of each frame transmitted is ran-
dom between 1 to 'Size'-1. The default size is 512.
4. Start up CitectSCADA. Each port will transmit a frame of random length. This proc-
ess is repeated when the entire frame is received.
5. Open the kernel, type "page driver" and press Enter. Type V to set the display mode
to 'verbose'. The following statistics appear:
l Number of characters transmitted.
l Number of frames transmitted.
l Number of characters received.
l Elapsed time in milliseconds.
l Characters received per second.
l Start time in milliseconds.
l Total number of errors.
l Error code of last detected error.

Note: The total number of errors should be 0. If the number of errors reported is
not zero, your serial hardware is not operating properly.

380
Chapter 15: Communicating with I/O Devices

Serial port loop-back cable

The diagram below shows the loop-back connections to use with RS-232.

The diagram below shows the loop-back connections to use with RS-422 or RS-485.

Contacting Technical Support

If your debugging efforts do not succeed within a reasonable amount of time, contact
Technical Support for this product and provide the following information:
l a Solution Request which you can obtain through Technical Support.
l syslog.dat, syslog.bak, tcpip.dat, or COMx log files.
l A copy of the SAPP, and the Citect.ini file.
See Getting Technical Support.

381
Chapter 15: Communicating with I/O Devices

Performance Considerations
Many external factors influence the performance of control and monitoring systems. The
capabilities of the computer, the I/O Device(s), and the communication pathway between
them are obvious factors. The faster they can transfer data, the faster your system oper-
ates. (CitectSCADA always attempts to maintain a data transfer rate as fast as the I/O
Device hardware can support.) The data transfer rate is hardware dependent: once you
have installed the hardware, your ability to influence this characteristic is limited.
However, there is one area where you can directly affect the performance of your run-
time system: the arrangement of data registers in the I/O Device(s).
See Also
Caching data
Grouping registers
Remapping variables in an I/O Device

Caching data
On large networked systems with many clients, you can improve communications turn-
around time by using memory caching.
When caching is enabled, data that is read from an I/O Device is stored temporarily in
the memory of the I/O Server. If another request is made (from the same or another
client) for the same data within the cache time, the CitectSCADA I/O Server returns the
value in its memory, rather than rereading the I/O Device. Data caching results in faster
overall response when the same data is necessary by many clients.
A cache time of 300 milliseconds is recommended. Avoid using long cache times (in
excess of 1000 milliseconds), as this may negatively impact the timely delivery of infor-
mation to the system.

Note: Do not use data caching for disk I/O devices as they implement a cache them-
selves.

How data caching works

Data caching prevents unnecessary rereads of I/O Device data within a short period of
time. Unnecessary reads can be generated when more than one client requests the I/O
Server to read data from a PLC or similar I/O Device within a short (typically 300 ms)
period of time.

382
Chapter 15: Communicating with I/O Devices

Normally, upon request from a client, an I/O Server reads status data from an I/O
Device, and passes it back to the requesting client.
If the server receives subsequent requests from other clients before the original data is
returned to the first client, it optimizes the read by automatically sending the original
data back to requesting clients. (Page General Blocked Reads shows this count).
If a client requests the same data immediately after the server returned the data to a
client, the server rereads the device unnecessarily.
Setting the data cache time to 300 ms (or similar) prevents identical repetitive reads
within that cached time frame. If further clients request the identical data from the same
server up to 300 ms after the server has sent that data to an earlier client, the cached
data on the server is sent immediately in response to the subsequent requests.

Note: Multiple clients don't have to be separate CitectSCADAs on a network. They

may be the alarms and trend clients in the same computer, so this optimization will
affect even a single node system.

CitectSCADA also uses read-ahead caching. When the data in the cache is getting old
(close to the cache time), the I/O Server will re-request it from the I/O Device. This opti-
mizes read speed for data that is about to be re-used (frequent). To give higher priority to
other read requests, the I/O Server requests this data only if the communication channel
to the I/O Device is idle.

Keeping a persistent record of the data

To keep a persistent copy of cached device data, you can save the I/O Server's cache to
disk. For every [IOServer]SavePeriod, the data is saved to s, one for each cached device.
Saving the data to disk will, in most circumstances, allow you to shut down and restart
the I/O Server without having to contact each I/O Device again to get its current values.
Instead, you can read the values from the device's persistence cache.

Note: When read-through caching is enabled for a remote or scheduled I/O Device,
the persistence cache for that device is saved to disk when the active I/O Server dis-
connects from the device. This occurs regardless of the value set in [IOServer]SavePe-
riod. You can enable read-through caching by setting the parameter [Dial]
ReadThroughCache.

Analog status common to more than one Graph-

Digital status unique to Graphics Page 2
ics Page

384
Chapter 15: Communicating with I/O Devices

Analog trends (for data logging) on largest time-

base (for example 10 secs)

Digital status unique to Graphics Page n

Digital status common to more than one Graph- Analog trends (for data logging) on smallest
ics Page timebase (for example 1 sec)

All other digital status, for example for logging. Analog alarms

Analog status unique to Graphics Page 1

Analog status unique to Graphics Page 2

While memory constraints and the existing PLC program might impose limitations,
grouping registers into discrete blocks, even if they are not consecutive blocks, will
improve system performance.
When designing your system, allow several spare registers at the end of each block for
future enhancements.
See Also
Remapping variables in an I/O Device

Remapping variables in an I/O Device

Some PLCs allow you to remap (or copy) an I/O Device variable to another register
address. CitectSCADA allows you to remap to:
l Group registers more efficiently to increase performance.
l Allow CitectSCADA to interpret a variable type (for example, an analog variable) as a
different variable type (for example, a digital variable). For example, you can create
additional digital addresses if an I/O Device has run out of digital addresses.
To remap a variable in your PLC, you need to design (or modify) the logic in the PLC to
associate both addresses. CitectSCADA can then read or write the variable to and from
the remapped address instead of the physical address.

385
Chapter 15: Communicating with I/O Devices

You can also reassign one type of variable (for example, an integer) to another type of
variable (for example, a digital variable).

386
Chapter 15: Communicating with I/O Devices

To remap in CitectSCADA, first create the variables in your project as you would nor-
mally. Then you can set up the remapping, specifying that any variable with an address
in the desired range will be remapped. The I/O Server will redirect the addresses at run-
time as per the remapping instruction.

Note: Not every PLC and/or CitectSCADA driver supports remapping. It is not rec-
ommend unless necessary. Contact Schneider Electric (Australia) Pty. Ltd. Support if
you need to evaluate whether the PLC and/or driver support remapping.

To remap a variable in CitectSCADA:

1. Open Project Editor.

2. Choose Communication | Remapping. The Remapping dialog box appears.

Option Description

CitectSCADA variable The first remapped (CitectSCADA) variable defined in the var-
iable tags database (using the Tags dialog box); for example:
Motor_1_Run.

(79 characters maximum). Alternatively, use the direct <Unit

Name>|<Address>| format (using values specific to your I/O
Device); for example: IODev|X1|.

The address entered here is remapped. At runtime the I/O

387
Chapter 15: Communicating with I/O Devices

Option Description

Server will read/write data through the physical address

instead.

Length The number of remapped variables. CitectSCADA reads

enough physical variables to remap this number of variables
(10 characters maximum).

The length needs to be less than the maximum request length

of the protocol. The protocol overview displays the maximum
request length of the protocol.

Physical Variable The first physical variable in the PLC, for example: ReMa-
pIntV7. (79 characters maximum).

This variable does not need to be defined in the variable tags

database. You can use the <Unit Name>|<Address>| format
(using values specific to your I/O Device). For example,
IODev|V7|.

Remap Read Determines whether to perform the remapping for reads. Set
to TRUE or FALSE.

FALSE - Read normal (not remapped) variables. The actual

address of the CitectSCADA variables will be read directly
from the I/O Device, instead of through the Physical Variable.
(Use this mode if your I/O Device does not support remap
reads.)

TRUE - Read remapped variables (through the physical var-

iable).

Remap Write Determines whether to perform the remapping for writes. Set

to TRUE or FALSE.

FALSE - Write to normal (not remapped) variables. The actual

address of the CitectSCADA variables will be written directly in
the I/O Device, instead of through the physical variable. (You
need to use this mode if your I/O Device does not support
remap writes.)

TRUE - Write to remapped variables (through the physical var-

iable).

Comment Any useful comment (48 characters maximum).

3. Complete the dialog box, and then click Add.

Note: To determine if the device supports remapped reads or writes, see the I/O
Device data type Help.

388
Chapter 15: Communicating with I/O Devices

Variable Tag Name Motor_1_Running_Feedback

Data Type Digital

I/O Device Name Area1

Address M1

Variable Tag Name Motor_1_Overload

Data Type Digital

I/O Device Name Area1

Address M3

Variable Tag Name Motor_4_ Running_Feedback

Data Type Digital

I/O Device Name Area1

Address M4

389
Chapter 15: Communicating with I/O Devices

Variable Tag Name Motor_4_ Running_Feedback

Data Type Digital

I/O Device Name Area1

Address M16

The address M2 is not used. Skipping addresses does not affect performance.
Remapping database
The remapping is defined as follows.

CitectSCADA Variable Area1|M1|

Length 16

Physical Variable Area1|R10|

Remap Read True

Remap Write False

The physical variable is an integer data type; it does not need to be defined in the var-
iable tags database (but it can be).

Advanced Driver Information

This section provides advanced information about drivers.
See Also
Variable (Digital) Limitations
Validating distributed project data for tag-based drivers
Write Delay Issue

Variable (digital) limitations

Devices often have memory areas that are of a designated data type, like Byte, Integer, or
Word. Some protocols do not support the reading and writing of data in these memory
areas using a different data type. This situation is most common in the case of reading
and writing of individual bits within the data types like Bytes, Integers, and Words.

390
Chapter 15: Communicating with I/O Devices

In this case, reading individual bits within these larger data types is done by reading the
designated data type and getting the CitectSCADA driver to sub-divide it into individual
bits. Writing to bits within the larger data types is more complicated, as writing to one
bit within the larger data type will at the same time overwrite the other bits within that
same data type. To prevent overwriting existing bits when writing a new bit value, a
'read-modify-write' scenario can be used to write to a bit within the larger data type.
Using this approach, the CitectSCADA driver will read the larger data type, modify the
appropriate bit within the larger data type, and then write the larger data type back to
the device.
While the 'read-modify-write' approach is necessary to avoid overwriting existing bits in
the registers of larger data types, it can create an issue if the device being written to is
also configured or programmed to modify these same registers. For example, if a PLC
device modifies the registers of one of its larger data types after the CitectSCADA driver
has read these same registers, but before CitectSCADA has written the modified value,
the changes made by the PLC will be overwritten. This outcome can be avoided if Citect-
SCADA and any devices using these data types are configured so that only one or the
other has write access at any given time.
This 'read-modify-write' method has a serious operational concern: if the device modifies
the larger data type after the CitectSCADA driver has read it, but before CitectSCADA
has written the new value, any changes made by the device are overwritten. This issue
could be serious in a control system, and it is recommended that the device and Citect-
SCADA be configured so that only one of these systems writes to the data types of this
kind.

UNINTENDED EQUIPMENT OPERATION

When the read-modify-write method will be used to alter a data type's bit values, configure
your system so that Citect and the host device do not have simultaneous write access to the
affected memory ranges.

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

Consider the following example:

1. The initial state of a PLC register is 0x02h.
2. The CitectSCADA driver reads the value of this register (effectively making a copy) in
preparation for a change to bit 3.
3. However, before the driver writes its change back to the PLC, the PLC code changes
the value of bits 0 and 4 of this register to 0x13h.

391
Chapter 15: Communicating with I/O Devices

4. The CitectSCADA driver then changes bit 3 of its copy of the register to 0x0Ah. When
it writes to the PLC, it overwrites the PLC's copy of the whole register (not just the
changed bit). Because the PLC code modified bits 0 and 4 in the interval between
CitectSCADA's read and write, these changes are overwritten.

Validating distributed project data for tag-based drivers

CitectSCADA uses numeric index values to uniquely identify the variable tags in a
project. They are used as a reference point when requesting data from the I/O Server for a
tag-based driver.
These index values are automatically generated when a project is compiled. Cir-
cumstances may arise where a distributed project has index values that represent dif-
ferent tag addresses on different computers. For this reason, CitectSCADA has a number
of automatic checks in place that validate a project's tag index values and flag any dis-
crepancies.
An initial security check takes place on client machines at a unit level, allowing a tag
index mismatch to be isolated to a particular client before any requests are sent to the I/O
Server. This confirms that the unit address, the unit type, the raw data type and the tag
address match for index values across the client and server machines. Any dis-
crepancies found are flagged by a hardware alarm on the client machine.
Each page is also checked to confirm that it was compiled against the current version of
the variables database. There is also a check performed whenever a tag-based driver
loads the variable database to test whether it matches the current tag addresses. The
parameter TagAddressNoCase allows you to adjust the case-sensitivity of these checks.
In addition, CitectSCADA will also check if a project is currently running on the local
machine when a compile is attempted, as this is one of the circumstances that may lead
to mismatched index values.
If the project uses a tag-based driver and is currently in runtime, CitectSCADA will stop
the compiler and generate an error in the error database noting that Citect32.exe was still
running. The .ini parameter [General]CitectRunningCheck allows you to override this fea-
ture, however it is recommended that you leave it enabled so that your tag index values
are assigned as intended.

Write delay effects

CitectSCADA performs writes to the I/O Device asynchronously (that is, when you write
to the I/O Device, the write takes time to get to the I/O Device, during which Citect-
SCADA continues to perform other operations). If the other Cicode assumes that the
write has completed immediately, you might encounter some side effects such as incon-
sistencies in the value of a variable tag across two Cicode threads.

392
Chapter 15: Communicating with I/O Devices

If you have the following Cicode:

PLC_VAR = 1234;
Prompt("Variable is " + PLC_VAR : ####);

the first line is a write to the PLC.

When CitectSCADA executes the first line, it generates a request to the I/O Server to write
the value 1234 into the PLC variable PLC_VAR. CitectSCADA then executes the next line of
Cicode before the PLC write is completed. CitectSCADA does this so that the Cicode is
not stopped while waiting for a slow I/O Device. As the write to the PLC has not com-
pleted, you might think that the next line of Cicode will display the last value of PLC_VAR
and not the value 1234. However, this Cicode will display the correct value (1234)
because whenever CitectSCADA writes to the PLC, it first updates its local copy of the
variable: any following Cicode will get the correct value.
Sometimes this solution will not work as CitectSCADA might keep multiple copies of an
I/O Device variable, and only update the one associated with the current Cicode. The
other variables will contain the old value of the I/O Device variable until they are
refreshed (with a read from the I/O Device). There is a separate data area for each dis-
play page, Cicode file, for alarms, trends and reports. If you write to an I/O Device var-
iable from a page keyboard command, the copy of the I/O Device variable associated
with that page will be updated; however, the copy associated with other pages and the
Cicode functions is not updated until the next read (as determined by the [Page]ScanTime
parameter). If you call a Cicode function that assumes the write has completed, it will
get the last value.
The workaround is to write to the I/O Device variable in the Cicode function. Every
Cicode function shares the same I/O Device variables, so the writes will operate as
expected.

FUNCTION
TestFunc(INT nValue)
PLC_VAR = nValue;
END

Another side effect of the delays inherent in asynchronous writes to I/O devices is that
you might assume that CitectSCADA has successfully written to the I/O Device, when in
fact the write operation might not yet have been completed or even attempted. In such
cases, it is still possible that a hardware- or configuration-based error will prevent the
success of the write operation. While such an unsuccessful write operation will generate
an error, your Cicode cannot be notified or use the IsError() function because the Cicode
has continued to execute past the initial I/O device write command. Therefore, when it is
important to check the success of a write operation before allowing code execution to con-
tinue, you might insert the function TagRead() after the write and then verify the value of

393
Chapter 15: Communicating with I/O Devices

the variable. TagRead() forces Cicode to re-read the I/O Device variable so that you can
check the new value. TagRead() is a blocking function. It blocks the calling Cicode task
until the operation is complete.

PLC_VAR = 1234;
sTestStr = TagRead("PLC_VAR");
IF sTestStr <> 1234 THEN
Prompt("Write not completed");
END

Here the data will be read from the physical PLC, not from the I/O Server cache, as the
I/O Server will invalidate any cached data associated with a PLC write. This will allow
you to test for a completed write. Please be aware that other Cicode tasks running at the
same time will not be waiting on the TagRead, so they might see the old or new value,
depending on if they are using the same copy of the PLC variable. You can also stop
CitectSCADA from writing to the local copy of the variable by using the function Code-
SetMode(0, 0).

Communicating with Remote Devices via Modems

A dial-up remote I/O Device is one which is connected to CitectSCADA through a PSTN
(Public Switched Telephone Network), and is accessible through pre-selected and pre-con-
figured modems.
Once connected, CitectSCADA can write to, and read from, dial-up remote I/O Devices
just as it does with any other I/O Device: local or remote.
Communications can be:
l On request: initiated by CitectSCADA using IODeviceControl() or by the remote I/O
Device (for instance, to report an alarm condition).
l Periodic: for instance, to transfer the logged events for a period.
l Persistent: for instance, to monitor and control the water level at a remote dam.
The only limiting factor would be an inability to connect a modem to an I/O Device due
to incompatible communications capabilities. Many I/O Devices have fixed settings and
can only communicate at a pre-set rate determined by the manufacturer. If a modem can-
not match these settings, communication cannot be established.
To make communications setup easier, you can connect dial-up remote I/O Devices with
identical communications to the same modem and port. Where I/O Devices are con-
nected to the same modem, CitectSCADA can communicate with each I/O Device one
after the other using the same phone connection, rather than hanging up and re-dialing.
This reduces the number of necessary telephone calls and increases the speed and effi-
ciency of communications.

394
Chapter 15: Communicating with I/O Devices

You need to have at least one modem at the I/O Server end, and at least one at the I/O
Device end.
See Also
Modems at the I/O Server
Modems at the I/O Device
I/O Device constraints for multi-dropping
Configuring multidrop remote I/O Devices
I/O Server redundancy for dial-up remote I/O Devices
Troubleshooting dial-up remote I/O Device communications

Modems at the I/O Server

To decide how many modems to use at the I/O Server end, decide what function each
modem will perform. A single modem can do any one of the following functions:

Dial- Makes calls to remote I/O Devices in response to a CitectSCADA request; for
out example, scheduled, event-based, operator request, and so on. Also returns
calls from remote I/O Devices.

Dial- Only receives calls from remote I/O Devices, identifies the caller, then hangs up
in immediately so it can receive other calls. CitectSCADA then returns the call
using a dial-back or dial-out modem.

Dial- Only returns calls from remote I/O Devices.

back

Dial- Receives calls from remote I/O Devices and makes scheduled calls to remote I/O
in Devices.
and
dial-
out

Dial- Receives and returns calls from remote I/O Devices.

in
and
dial-
back

Your modem setup depends on your system requirements. When making your decision,
consider the following guidelines:
l If you need to communicate with multiple remote I/O Devices at once, you will need
a separate modem for each I/O Device. Otherwise you'll have to wait as I/O Devices
are contacted one after the other, and incoming calls may be held up.
l If you have scheduled requests to I/O Devices and you also need to urgently return
calls from remote I/O Devices that dial in, you will need at least one modem for each

395
Chapter 15: Communicating with I/O Devices

of these functions. For example, if you have a large number of remote I/O Devices
and you require fast responses by CitectSCADA, provide an additional modem at the
I/O Server. This would reduce the chances of it being engaged when an I/O Device
dials in (say, with an urgent alarm).
l In a big system with many remote I/O Devices or a system where calls from remote
I/O Devices can be time sensitive, it's a good idea to dedicate at least one modem to
Dial-Back. This will give you quick responses to Dial-In calls (from remote I/O
Devices). It also means your dial-out schedules won't be disrupted (if you use the
same modem for returning calls and scheduled calls, the scheduled calls are forced to
wait until the dial-back call is complete).
See Also
Modems at the I/O Device
Example configurations for modems at the I/O Server

Modems at the I/O Device

You can have multiple I/O Devices connected to a single modem if they have the same
communication requirements (phone number, baud rate, data bits, stop bits, and parity).
A separate port and modem needs to be used for each remote I/O Device with different
communication requirements.
When deciding how many modems to use, consider the following:
l Once an I/O Device has been contacted, the connection can be retained for other I/O
Devices in the group. If the I/O Server needs to request data from another I/O Device
with the same communication details, it will wait until the current request has been
completed, then it will use the same connection to make the second request.
l You can configure your modem to initiate telephone calls (call CitectSCADA), and/or
receive telephone calls. This is done independently of CitectSCADA.

Note: Wherever your modem is, you need to verify that its Data bits, Parity, Stop
bits, and Serial Port Speed settings are compatible with the remote I/O Device as
defined by the device's manufacturer or your communications link will not work.

Example configurations for modems at the I/O Server

The examples below demonstrate how to set up the modems at your I/O Server to accom-
modate different combinations of I/O Devices.
Example 1

396
Chapter 15: Communicating with I/O Devices

All your remote I/O Devices have the same communication requirements (data bits, stop
bits, parity, and baud rate) - 19200 8 E 1.
You don't expect any important calls from your I/O Devices, or you only have a few
remote I/O Devices. This means you can use a single modem at the I/O Server end. This
modem would be set up to answer and return incoming calls and make scheduled and
other CitectSCADA initiated calls.
To configure your modem, define it in Windows. Assuming that the logical modem is
called 'Standard Modem', configure it as follows:

Port Modem Name Max. Speed Data Bits Par- Stop

ity Bits

Standard Modem 19200 8 E 1

COM-
1

You would then configure it in CitectSCADA as a dial-out modem and dial-in modem:

Modem Name Dial-out Dial-in Dial-back

Standard Modem TRUE TRUE FALSE

Example 2
In this example, your I/O Devices use a total of two different communication spec-
ifications - 9600 7 O 1 and 19200 8 E 1.
You don't expect important calls from I/O Devices or you have only a few I/O Devices.
This means you can get by with a single modem at the I/O Server end. This modem has
to receive and return calls from I/O Devices as well as initiate calls (dial out) to I/O
Devices.
To configure your modem, you need to first define it in Windows (through the Windows
Control Panel). Remember, you're not just defining the physical modem here. You have
to define a separate Windows (virtual) modem for each communication specification.
So far, this gives you two virtual modems - one for 9600 7 O 1 and one for 19200 8 E 1.
However, Windows won't let you define both of these modems as dial-in. It only lets you
define one dial-in modem per port. If you choose the first, it won't be able to receive calls
with the second, and vice versa.
This means you have to set up a separate virtual modem that can answer calls no
matter which communication specification is used. This modem would be set with a
generic communication specification of 9600 8 N 1.

397
Chapter 15: Communicating with I/O Devices

So in Windows, you'll end up with three logical modems (two for Dial-Out and one for
Dial-In). Assuming that the logical modems are called 'Standard Modem' to 'Standard
Modem #3', you would configure them as follows:

Por- Modem Name Max. Data Bits Par- Stop

t Speed ity Bits

Standard Modem 9600 7 O 1

CO-
M1

Standard Modem 19200 8 E 1

CO- #2
M1

Standard Modem 9600 8 N 1

CO- #3
M1

You would then configure the modems in CitectSCADA as follows.

Modem Name Dial-out Dial-in Dial-back

Standard Modem TRUE FALSE FALSE

Standard Modem #2 TRUE FALSE FALSE

Standard Modem #3 FALSE TRUE FALSE

Example 3
In this example, there are five different communications frameworks - 9600 7 O 1, 19200
8 E 1, 4800 8 N 1, 9600 8 N 1, and 19200 8 N 1.
If you expect important calls from I/O Devices or you have many I/O Devices, you
would set up three modems at the I/O Server end:
l One on COM3 dedicated to receiving calls from 9600 7 O 1 I/O Devices.
l One on COM2 for dialing out to 4800 8 N 1, 9600 8 N 1, and 19200 8 N 1 I/O
Devices.
l One on COM1 for dialing out to 9600 7 O 1 and 19200 8 E 1 I/O Devices.
The two dial-out modems would return calls as well as initiate calls in response to
scheduled requests, and so on.

398
Chapter 15: Communicating with I/O Devices

To configure your modems, you need to first define them in Windows (through the Win-
dows Control Panel). Remember, you're not just defining the physical modem here. You
have to define a separate Windows (virtual) modem for each communication frame-
work.
Assuming that the logical modems are called 'Standard Modem' to 'Standard Modem
#6', you would configure them as follows:

Por- Modem Name Max. Data Bits Par- Stop

t Speed ity Bits

Standard Modem 9600 7 O 1

CO-
M1

Standard Modem 19200 8 E 1

CO- #2
M1

Standard Modem 4800 8 N 1

CO- #3
M2

Standard Modem 9600 8 N 1

CO- #4
M2

Standard Modem 19200 8 N 1

CO- #5
M2

Standard Modem 9600 7 O 1

CO- #6
M3

You would then configure the modems in CitectSCADA as follows:

Modem Name Dial-out Dial-in Dial-back

Standard Modem TRUE FALSE FALSE

Standard Modem #2 TRUE FALSE FALSE

Standard Modem #3 TRUE FALSE FALSE

Standard Modem #4 TRUE FALSE FALSE

399
Chapter 15: Communicating with I/O Devices

Standard Modem #5 TRUE FALSE FALSE

Standard Modem #6 FALSE TRUE FALSE

Example 4
In this example, your I/O Devices use three different communication frameworks: 9600 7
O 1, 19200 8 E 1, and 9600 8 N 1. However, in this example, you are expecting impor-
tant calls from I/O Devices, so you need a modem dedicated to returning calls.
Here you need to configure your modems like this:
l One modem on COM1 to dial remote I/O Devices (for scheduled calls, and so on).
l One modem on COM2 to receive calls from remote I/O Devices.
l One dedicated modem on COM3 to return these calls.
To configure your modems, first define them in Windows (through the Windows Control
Panel). Remember, you're not just defining the physical modem here: you need to define
a separate Windows (virtual) modem for each communication framework. This means
you have to configure:
l Three logical modems on the port to which the physical dial-out modem is attached.
l One logical modem on the port to which the physical dial-in modem is attached.
l Three logical modems on the port to which the physical dial-back modem is
attached.
Assuming that the necessary total of seven logical modems are called 'Standard Modem'
through to 'Standard Modem #7', configure these modems as follows:

Port Modem Name Max. Data Bits Par- Stop

Speed ity Bits

Standard Modem 9600 7 O 1

COM-
1

Standard Modem 19200 8 E 1

COM- #2
1

Standard Modem 9600 8 N 1

COM- #3
1

Standard Modem 9600 8 N 1

COM- #4

400
Chapter 15: Communicating with I/O Devices

Standard Modem 9600 7 O 1

COM- #5
3

Standard Modem 19200 8 E 1

COM- #6
3

Standard Modem 9600 8 N 1

COM- #7
3

You would then configure the modems in CitectSCADA as follows:

Modem Name Dial-out Dial-in Dial-back

Standard Modem TRUE FALSE FALSE

Standard Modem #2 TRUE FALSE FALSE

Standard Modem #3 TRUE FALSE FALSE

Standard Modem #4 FALSE TRUE FALSE

Standard Modem #5 FALSE FALSE TRUE

Standard Modem #6 FALSE FALSE TRUE

Standard Modem #7 FALSE FALSE TRUE

I/O Device constraints for multi-dropping

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. This makes it difficult 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 Device is capable of issuing caller IDs. If multi-
dropping, use I/O Devices that can issue caller IDs.
To configure dial-up remote I/O Devices for communication with CitectSCADA:

401
Chapter 15: Communicating with I/O Devices

1. Run the Express Communications Wizard.

2. Complete the wizard, selecting the relevant I/O Server, then the I/O Device, creating
each new instance when necessary.
3. On the Scheduling page of the wizard, select the Connect I/O Device to PSTN check
box.
4. Select an appropriate schedule for CitectSCADA to communicate with the remote I/O
Device. (For a persistent connection - whenever CitectSCADA is running - select On
Startup.) For example (all based on a Synchronize at time of 10:00:00):
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; that is, 10 p.m., then again at 10 a.m. of the following day,
and so on.
l If you enter 12:00:00 and start your project at 4 p.m., the I/O Server will com-
municate with the I/O Server at 10 p.m., then again at 10 a.m., of the following
day, and so on. CitectSCADA will assume that communications were estab-
lished at 10.a.m., so will continue as if they had been, communicating once
every 12 hours after 10 a.m.
l If you enter 3 days and start your project at 9 a.m. on a Wednesday, the I/O
Server will communicate with the I/O Device at 10 a.m., then once every 3 days
after that; that is, 10 a.m. on the following Saturday, then at 10 a.m. on the fol-
lowing Tuesday, and so on.
l If you enter the 6th of December in the Repeat every field 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, and so on.
5. Select On Startup for a persistent connection. To disconnect a persistent connection,
call the IODeviceControl() function with type 8.
6. Type in the phone number necessary for CitectSCADA to dial the remote modem
attached to the remote I/O Device. Include any pre-dial numbers necessary to obtain a
connection to an outside PSTN line (dial tone) before dialing (for example, 0 (zero)) -
if appropriate.
7. On the next wizard page, if the device is configured to dial-in to CitectSCADA, create
a unique identifying caller name for the remote I/O Device so that it can be identified
by CitectSCADA.
8. Follow the instructions on the next page of the wizard and click Finish.
See Also
Configuring multidrop remote I/O Devices

402
Chapter 15: Communicating with I/O Devices

Configuring multidrop remote I/O Devices

Multidropping remote I/O Devices from the same remote modem enables CitectSCADA
to communicate with each I/O Device one after the other, using the same phone con-
nection, rather than hanging up and re-dialing.
Although you can configure multidrop remote I/O Devices using the Express Com-
munications Wizard, we recommend that you do it manually. The wizard would create
a new port for each I/O Device. This would mean you couldn't have any more than 255
I/O Devices.
1. Run the Express Communications Wizard to configure the first device.
2. Configure every other I/O device manually.
3. Open the Citect Project Editor.
4. Select Communications | I/O Server and scroll to the I/O Server that will be com-
municating with the I/O Device.
5. Select Communications | I/O Devices.Complete the dialog box.
6. To increase the efficiency and capacity of your system you can allocate the same port
name to I/O Devices with the same communication settings.

Note: If you are multi-dropping and you want to be able to dial in to the I/O
Server, 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. This makes it difficult 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 Device are capable of issuing caller IDs. If
multi-dropping, use I/O Devices that can issue caller IDs.
To set up a modem connected to your dial-up remote I/O Devices:
You can connect multiple I/O Devices to the same modem. This means CitectSCADA
can communicate with these I/O Devices one after the other using the same phone con-
nection, rather than hanging up and re-dialing. This will reduce the number of necessary
telephone calls and increase the speed and efficiency of communications.
1. Connect the modem to a PC with a telephony program installed (for example Hyper-
Terminal or PhoneDialer). This is where you will configure the modem to answer
calls from CitectSCADA and/or initiate calls.
2. If the modem is necessary to make calls to CitectSCADA, configure it to initiate the
phone call to a pre-determined CitectSCADA I/O Server Dial-In type modem (fol-
lowing manufacturer instructions).

403
Chapter 15: Communicating with I/O Devices

3. Depending on your hardware either the modem or an intelligent PLC can be respon-
sible for initiating calls to CitectSCADA and identifying the caller. Whichever is
responsible needs to have a caller ID set. The caller ID can be any combination of
alpha-numeric characters and/or the character '_' (underscore).
Some modems have dip-switch settings, and some have initiation strings which
can include auto-dial-up numbers that are stored within the modem's non-volatile
memory. Consult the manual provided with the modem for exact details.
You can use either the Express Communications Wizard or the I/O Devices form
to set the caller ID for an I/O Device.
If 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, making it difficult to
identify which I/O Device 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 Device is capable of issuing caller
IDs. If you are multi-dropping, use I/O Devices that can issue caller IDs.
4. Set the modem's Data bits, Parity, Stop bits, and Serial-Rate to match manufacturer
specifications for communication with the I/O Devices.
Some modems do not allow you to manipulate their communications settings via
methods such as extended AT commands or dip switches. If this is the case, the
only way of setting the necessary values is to communicate with the modem using
the values (for example, via HyperTerminal). Once this is done, the modem
remembers the last values used to communicate with its serial port.
5. Connect the modem to the I/O Devices.
To configure a modem at the I/O Server you need to set it up in Windows and then set it
up in CitectSCADA.
If every one of your I/O Devices are the same, you only have to do this once for each
modem. However, if your I/O Devices talk using different communication specifications
(data bits, parity, stop bits, and serial-rate), your modem has to be able to talk using each
of these details as well. To set this up, you have to create a modem in Windows and
CitectSCADA for each specification. (See Example configurations for modems at the I/O
Server)
To set up a modem in Windows

1. Each modem connected to a CitectSCADA I/O Server PC needs to FIRST be con-

figured within Windows using Start | Settings | Control Panel | Phone and Modem
Options.
2. Select the Modems tab, and click Add to launch the Install New Modem wizard.

404
Chapter 15: Communicating with I/O Devices

3. Check the box labeled Don't detect my modem; I will select it from a list, then click
Next.
4. Select Standard Modem Types in the list of manufacturers.

Note: Do not select a brand name modem from the Manufacturers list, even if the
name of the modem you're installing is included in the list. Do not click Have
Disk.

5. Select the Standard xxxx bps modem rate from the list of models to exactly match
the bit per second rate of the I/O Device that is going to be communicating via this
modem. Check the device to determine the device communication rate. If you are still
unsure, select the 9600 bps model. This can be changed later if necessary.
6. Do not click Have Disk. Click Next.
7. Select the COMx Port that the modem is connected to. Click Next.
8. Click Finish. Windows displays the modem in the list of modems on the Modems
Properties form.
9. No option was given for the selection and setting of the Data bits, Parity, or Stop bits
information. The Modems wizard automatically defaults to 8-none-1 for Standard
Modem types. To change these settings to match the Data bits, Parity, Stop bits
requirements of the remote I/O Device, select a modem in the list, then click the Prop-
erties button.
10. Click the Advanced tab and click Change Default Preferences.
11. Click the Advanced tab at the next dialog to gain access to the Data bits, Parity, Stop
bits settings for the modem.
12. Change the Data bits, Parity, and Stop bits settings using the drop-down options, so
that they exactly match those being used by the remote I/O Device and its remote
modem. Don't change any advanced settings. (The default is Hardware flow control.)
13. Click OK. If a modem of the same rate is installed to the same port as an existing
modem, Windows asks for confirmation that you want to install the same thing more
than once. Click Yes to install a duplicate copy of the modem.
14. Preconfigure the modem(s) to be used at the remote dial-up I/O Device(s). These will
be used to test modem configuration settings in the next step.
15. With CitectSCADA not running, confirm that the local and remote modems will prop-
erly communicate with each other by using a terminal communications program
such HyperTerminal or PhoneDialer (both supplied with Windows).
Once the modem(s) are set up and tested with proven communications in Windows,
they can then be set up in CitectSCADA.
To set up a modem in CitectSCADA:

405
Chapter 15: Communicating with I/O Devices

Before completing this procedure, verify that you have set up your modem in Windows
(as described above).
1. Open the Citect Project Editor.
2. Select Communications | I/O Server and scroll to the I/O Server the modem is
attached to.
3. Select Communications | Modems. The Modem Properties dialog will appear.

Option Description

Server Name (16 The name of the I/O Server to which the modem is attached.
Chars.)

Modem Name (64 The name of the modem you are configuring (as it appears in the
chars.) Windows Control Panel | Phone and Modem Options).

Comment (48 Any useful comment.

Chars.)

Use this modem to Determines whether this modem will be used to initiate calls from
make outgoing calls the I/O Server to a dial-up remote I/O Device. (Dial-Out)

This may include calls that are scheduled, event driven, or in

response to I/O Devices that dial in.

Use this modem to Determines whether this modem will be used to receive calls from
answer incoming a dial-up remote I/O Device. (Dial-In)
calls

The following fields are implemented with extended forms (press F2).

Use this Determines whether this modem will be used to initiate calls from the
modem to I/O Server to a dial-up remote I/O Device in response to a call received
call back I/O from the I/O Device. (Dial-Back)
Devices

4. Complete the dialog box.

Note: CitectSCADA allows you to set up a maximum of 256 modems on the I/O
Server for communication with remote dial-up I/O Devices. Before it can suc-
cessfully establish communication, any targeted remote I/O Devices need to also
be properly configured within CitectSCADA on the I/O Server.

406
Chapter 15: Communicating with I/O Devices

I/O Server redundancy for dial-up remote I/O Devices

You can change the number of rings the I/O Server will wait before answering the call
(using the [Dial]RingCount parameter). If you are using redundant I/O Servers, the pri-
mary I/O Server will be called by default. However, by setting [Dial]RingCount to a dif-
ferent value on each of the I/O Servers, you can make the standby I/O Server answer the
call if the primary does not.
Consider the following setup:

If you set the ring count to 3 on IOServer1 and 4 on IOServer2, IODev_1 will attempt to
call IOServer1. If IOServer1 has not answered the call after 3 rings, IOServer2 will
answer it.
See Also
Troubleshooting dial-up remote I/O Device communications

Troubleshooting dial-up remote I/O Device communications

The challenges most often encountered when using a dial-up remote I/O Device involve
communications speed, parity, and control signals from the connected equipment. If
changing the speed and parity does not resolve a communications interruption, evaluate
the modem's answering codes and command echoing.

407
Chapter 15: Communicating with I/O Devices

Following is a list of settings that might be helpful in resolving dial-up communications

interruptions. (Since not every modem supports the same in commands in the same
way, this is only a guide. Consult the modem manual for exact details.)
On the modem at the PC end

ATV1 //Enables long-form (verbose) result codes

ATQ0 //Result codes are sent on the RS-232 connection
ATE0 //Commands sent from the computer are not echoed back to the RS-232 connection
AT&C1 //DCD will follow carrier on the line
AT&K0 //Handshaking OFF
ATW0 //Upon connection, only DTE speed is reported
AT%C0 //Compression OFF
AT&D0 //DTR always on

If the modem at the PC end is configured so that calls are automatically answered even
when your CitectSCADA project is off, data being reported from the I/O devices may be
lost. Therefore, it is recommended that you turn off the PC modem's auto-answer feature
before taking your project offline. To do this, set the following parameter to zero:

ATS0 = 0 // Auto answer OFF

Be aware, however, this will also impact applications that might use the modem other
than CitectSCADA, as the modem cannot answer a call while CitectSCADA is not driv-
ing its functionality.
On the modem at the I/O Device end

ATV0 //Enables short-form result codes

ATQ1 //No result codes are sent on the RS-232 connection
ATE0 //Commands that are sent from the computer are not echoed
back to the RS-232 connection
AT&C1 //DCD will follow carrier on the line
AT&K0 //Handshaking OFF
ATW0 //Upon connection, only DTE speed is reported
AT%C0 //Compression OFF
AT&D0 //DTR always on
ATS0 //Set to greater than 0 (sets the number of rings necessary before the modem
answers
an incoming call).

Alternative (backward compatibility) method of persistent connection

If you are setting up your modem to dial a dial-up remote I/O Device, follow the pro-
cedures described in Communicating with Dial-up Remote I/O Devices. This method is
available for backward compatibility.

408
Chapter 15: Communicating with I/O Devices

Scheduled Communications
CitectSCADA allows you to schedule communications with your I/O Devices (regardless
of the type of connection: modem, radio link, etc.). For example, if you have multiple I/O
Devices on a single network or line, you can schedule reads so that the important I/O
Devices are read more often than less important I/O Devices. Alternatively, a water sup-
plier with radio link connections to dam level monitors might schedule hourly level
reads from CitectSCADA in order to conserve band-width.
See Also
Specifying a schedule
Writing to the scheduled I/O Device
Reading from the scheduled I/O Device

Specifying a schedule
To configure scheduled communications with an I/O Device, you need to flag it as a
"Scheduled" device. This is done using the Express Communications Wizard. If your I/O
Device is not capable of scheduled communications, the scheduling options will not be
presented by the wizard.

Note: Scheduled communications will not work for drivers that are designed to han-
dle Report-By-Exception protocols. For communicating with your I/O Device outside
of schedule use the IODeviceControl function.

To schedule communications with an I/O Device:

1. Select the Project Editor (or press the Project Editor icon).
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. Follow the instructions to work through the screens, selecting the relevant I/O Device,
and so on. When the scheduling screen displays, check the Connect I/O Device to
PSTN box, even if your I/O Device is not connected via a modem (but leave the
Phone number to dial and Caller ID fields blank).
5. Fill out the schedule fields to achieve the desired schedule. For example (all based on
a Synchronize at time of 10:00:00).
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.

409
Chapter 15: Communicating with I/O Devices

l If you enter 12:00:00, and start your project at 4 p.m., the I/O Server will com-
municate with the I/O Server at 10 p.m., then again at 10 a.m. of the following
day, etc. i.e. it will assume that communications were established at 10 a.m., so
it continues as if they had been, communicating once every 12 hours after 10
a.m.
l If you enter 3 days, and start your project at 9 a.m. on a Wednesday, 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 dur-
ing 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, and so on.
6. Select On Startup for a persistent connection. To disconnect a persistent connection,
you need to call the IODeviceControl() function with type 8.
7. If your I/O Device is not connected via a modem, you need to go to the Ports form
(select Ports from the Communication menu) and change the Port number to the
actual number of the COM port.
See Also
Writing to the scheduled I/O Device

Writing to the scheduled I/O Device

Whenever an I/O Device is actively communicating (as per its schedule), you can write
to it directly. However, if you try to write to it when it is not communicating, your write
request will be queued until it is. For example, you might decide to schedule one write
per hour. If someone at a Control Client changes a tag's value during that hour, that
change will not be written to the I/O Device until the hour has expired.
As write requests are not written to the I/O Device until it is communicating, confirm
that pending writes have been completed in full before shutting down.

Note: Don't control hardware using a scheduled I/O Device, as the exact state of the
hardware may not be known. Although you can read the state from the cache, it may
have changed since the cache was created.

410
Chapter 15: Communicating with I/O Devices

UNINTENDED EQUIPMENT OPERATION

Do not use a scheduled I/O device to control hardware in a system managed by Citect-
SCADA.

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

See Also
Reading from the scheduled I/O Device

Reading from the scheduled I/O Device

When the I/O Server initiates communication with the I/O Device, it immediately writes
any queued write requests, then reads the I/O Device's tags. These values are then stored
in a cache so that you can still access them between communications.

Note: Because the I/O Server reads tags on initiation of communication, the license
point count is increased, even though some of the tags read may not actually be
used.

Keeping data up-to-date during prolonged connections

Normally, communication is terminated as soon as every read and write request is com-
plete. Sometimes, however, you may want to prolong the communication (for example
by calling the IODeviceControl() function with Type 7).
In this situation (if Read-Through Caching is disabled), when client computers request
device data from the I/O Server, it retrieves the data from its cache, not from the I/O
Device. This occurs even though the I/O Server maintains a connection to the device.
To retrieve fresh data from the I/O Device, you can force a periodic read using Cicode, or
change the cache timeout by setting the IODeviceControl() function to Type 11.
For example:

INT hTask;
// Initiate communications and read tags.
// Sleep time will depend on how fast your
// modems connect.
FUNCTION
DialDevice(STRING sDevice)
INT bConnected = 0;
INT nRetry = 5;

411
Chapter 15: Communicating with I/O Devices

hTask = TaskHnd("");
IODeviceControl(sDevice, 7, 0);
Sleep(20);
WHILE bConnected <> 1 AND nRetry > 0 DO
bConnected = IODeviceInfo(sDevice, 18);
nRetry = nRetry - 1;
Sleep(10);
END
IF bConnected = 1 THEN
WHILE TRUE DO
Sleep(2);
IODeviceControl(sDevice, 16, 0);
END
END
END
// Kill the read task and terminate the connection.
FUNCTION
HangupDevice(STRING sDevice)
TaskKill(hTask);
IODeviceControl(sDevice, 8, 0);
END

You can also force the I/O Server to read data directly from an I/O Device by enabling
Read-Through Caching. With [Dial]ReadThroughCache set, while the I/O Server is con-
nected to a device it will supply data to requesting clients directly from the device. The
cache is not updated during this time, but is refreshed with the most recent device data
just before the server disconnects.

Note: If using modems, you might need to adjust or deactivate the inactivity timer in
your modems to stop them from disconnecting while no data is being read. The inac-
tivity timer is controlled by the S30 register. If your modem doesn't support this reg-
ister, please consult your modem's manual.

Avoiding unnecessary multiple reads of I/O Device data

To avoid unnecessary reads of an I/O Device, you can use data caching to temporarily
store data read from the device in the memory of the I/O Server. This means that if the
I/O Server receives more than one request for device data in a short time period, instead
of contacting the I/O Device a second time and reading identical data, it can retrieve the
data from the cache.

412
Chapter 16: Tagging Process Variables
You need to assign a variable tag to each I/O Device variable that CitectSCADA uses in
your runtime system. To define your variable tags, you declare them in the variable tag
database. The variable tag becomes a label, used to reference the data value of the I/O
Device register at the specified address. Using labels has several benefits:
l You do not have to remember the address every time you want to use the variable.
You use the tag name, which has to be logical and descriptive, and therefore less con-
fusing.
l The address in the I/O Device is defined only once. If you change the address, you
only need to update the variable tag definition, not every instance in your con-
figuration.
l You can scale the raw data to an appropriate range in the same declaration.
l You can access extended data value, quality and timestamp information.
You need to define your variables as a specific data type. The most common variables
supported by I/O Devices are digital and integer. CitectSCADA also supports real, string,
byte, bcd, long, and longbcd data types.
After you have defined your variable tags, you can use them to:
l Display objects on a graphics page.
l Store data for trending and analysis. (See Trending Data.)
l Monitor Alarms. (See Using Alarms in SCADA.)
l Control equipment and processes. (See Defining Commands and Controls.)
l Store data in memory (See Configuring Local Variables.)
The most common variables supported by I/O Devices are digital and integer variables,
although some I/O Devices support other numeric variables and strings.
See Also
Tag name syntax
Tag Extensions
Tag Data Types
Tag Browsing
Using structured tag names
Configuring Local Variables
Configuring Variable Tags
Formatting numeric variables
Using arrays

413
Chapter 16: Tagging Process Variables

Tag Naming
CitectSCADA puts a couple of restrictions on the names of variable tags:
l Tags are restricted to using a specific syntax. See Tag name syntax.
l Do not give Tags the same name as Cicode functions within the project or within any
included projects. An error will result during compilation if a tag has the same name
as a Cicode function and is placed on a graphic page. See Defining Variable Tag
Names for a list of restrictions on naming.
In addition, using a tag naming convention will make your project easier and faster to
design, configure, commission, and maintain. See Using structured tag names for rec-
ommendations about naming conventions.

Tag name syntax

CitectSCADA tags (variable tags, alarm tags and trend tags) need to have the following
syntax:

[<alpha> | '_'] *[<alpha> | <digit> | '\' | '_']

That is, the tag name needs to begin with either an alpha character (A-Z or a-z) or the
underscore character (_). Any following characters needs to be either alpha characters
(A-Z or a-z), digit characters (0 - 9), backslash characters (\), or underscore characters (_).
The use of any other characters will result in a compiler error.
For example, '_MyTag123' and 'my\New\Tag' are both valid tag names, whereas '\Ne-
wTag\' is invalid.
Tag names that begin with a numeric character, such as '12TagName', are only valid if
the INI parameter [General]TagStartDigit is set to 1 (the default value is zero).

Note: The name of an Alarm Tag needs to follow this syntax but the Alarm Name
does not.

414
Chapter 16: Tagging Process Variables

Using structured tag names

The following naming convention is recommended for a system, to obtain maximum
benefit when using features such as Genies and Super Genies. (If you are already using a
naming system that differs from the following convention, you can still use Genies and
Super Genies supplied with CitectSCADA by modifying the Genies that you want to
use.)
Each tag name can contain up to 79 characters. To establish a convention, you need to
divide the characters in the tag name into sections that describe characteristics of the tag,
for example, the area where the tag is located, the type of variable, and any specific attrib-
utes. Four basic sections are suggested for a CitectSCADA naming convention:

Area_Type_Occurrence_Attribute

Area
The Area section identifies a plant area, number, or name. If you use a prefix that iden-
tifies tags within a particular area, you can easily duplicate CitectSCADA functions
within the area. For example, if you have three boilers with the same controls on each
boiler, you can configure the tags for boiler number one, and copy the tags to boilers two
and three. You then only need to change the area section in the tag names to the area of
the second and third boiler. The remainder of the tags remain unchanged, for example:

Boiler 1 Boiler 2 Boiler 3

B1_TIC_101_PV B2_TIC_101_PV B3_TIC_101_PV

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

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

Variable Tag Meaning

B1_TIC_101_PV Temperature indicating controller

B1_FIC_101_PV Flow Indicating controller

415
Chapter 16: Tagging Process Variables

B1_PUMP_101_PV Pump

B1_VALVE_101_PV Valve

Occurrence
The Occurrence section identifies the loop number.

Variable Tag Meaning

B1_TIC_101_PV Temperature Indicating Controller 101

B1_TIC_102_PV Temperature Indicating Controller 102

B1_PUMP_101_PV Pump 101

B1_PUMP_102_PV Pump 102

Attribute
The Attribute section identifies the attribute or particular parameter that is associated
with the loop.

Variable Tag Meaning

B1_TIC_101_PV Process Variable

B1_TIC_101_SP Setpoint

B1_TIC_101_OP Output

B1_TIC_101_P Gain or proportional band

B1_TIC_101_I Integral

B1_PUMP_101_CMD Command signal to start pump

B1_PUMP_101_M Auto/Manual mode

B1_TIC_101_V Value (running/stopped)

416
Chapter 16: Tagging Process Variables

Recommended Attributes
Genies and Super Genies supplied with CitectSCADA use the following attribute con-
vention. If you follow this convention, you can use the Genies without having to modify
them.

Mnemonic Discrete Control / Monitoring Data Range

Type

_CMD Command Signal to Start Device Digital 0 = Off, 1

= On

_M Control Mode Digital 0=Man,

1=Auto

_V Value Digital 0=Off,

1=On

_FAIL Device Failure Digital 1=OK,

0=Failed

FAULT Device Fault Digital 1=OK,

0=Fault

Mne- Process Alarms Data Range

monic Type

_ALM General Alarm Digital 0=Active, 1=InActive

_HHALM High High Alarm Digital 0=Active, 1=InActive

_HALM High Alarm Digital 0=Active, 1=InActive

_LALM Low Alarm Digital 0=Active, 1=InActive

_LLAM Low Low Alarm Digital 0=Active, 1=InActive

_DALM Deviation Alarm Digital 0=Active, 1=InActive

_DLALM Deviation Low Alarm Digital 0=Active, 1=InActive

_DHALM Deviation High Alarm Digital 0=Active, 1=InActive

_HHTRIP High High Alarm Trip Point Analog

417
Chapter 16: Tagging Process Variables

_HTRIP High Alarm Trip Point Analog

_LTRIP Low Alarm Trip Point Analog

_LLTRIP Low Alarm Trip Point Analog

_DTRIP Deviation trip Point Analog

_LDTRIP Low Deviation Trip Point Analog

_HDTRIP High Deviation Trip Point Analog

_HHhyst High High Alarm Hysteresis Analog

_Hhyst High Alarm Hysteresis Analog

_Lhyst Low Alarm Hysteresis Analog

_LLhyst Low Low Alarm Hysteresis Analog

_LDhyst Low Deviation Alarm Hysteresis Analog

_HDhyst High Deviation Hysteresis Analog

Mnemonic Analog Control / Monitoring Data Range

Type

_PV Process Variable Analog

_SP Setpoint Analog

_RSP Remote Setpoint Analog

_OP Output Analog

_OPM Output Mode Digital 0=Manual,

1=Auto

_SPM Setpoint Mode Digital 0=Local,

1=Remote

_P Gain (Proportional Band) Analog

418
Chapter 16: Tagging Process Variables

_I Integral (Reset) Analog

_D Derivative (Rate/Preact) Analog

_KP Gain Modifier Analog

_KI Integral Modifier Analog

_KD Derivative Modifier Analog

_SPTK Setpoint Track Mode Digital 0=OFF,

1=Track

_OPTK Output Track Mode Digital 0=OFF,

1=Track

_SPB Setpoint Bias Analog

_SPR Setpoint Ratio Analog

_DEV Deviation

_TOT Totalizer Value Analog

_COUNT Counter Value Analog

_CRESET Counter Reset Command Digital 0=Counting,

1=Reset

_CLIMIT Counter Preset Limit Analog

_TIME Timer Value Analog

_TRESET Timer Reset Command Digital 0=Timing,

1=Reset

_EXP Timer Expired Digital

_TLIMIT Timer Limit Analog

_CALC1 Calculation Result 1 Analog

_LINZ1 Linearized Signal 1 Analog

_Q Data Quality Flag Digital 1=OK, 0=BAD

419
Chapter 16: Tagging Process Variables

Note: To keep the tag names shorter you can omit the underscore, but you would sac-
rifice readability; for example: B1TIC101PV instead of B1_TIC_101_PV.

Tag Data Types

Tags in CitectSCADA hold data values that can be defined as one of the following data
types.

Data Type Variable Size Allowed Values

BCD Binary- Coded Decimal 2 bytes 0 to 9,999

BYTE Byte 1 byte 0 to 255

DIGITAL Digital 1 bit or 1 0 or 1

byte

INT Integer 2 bytes -32,768 to

32,767

UINT Unsigned Integer 2 bytes 0 to 65,535

LONG Long Integer 4 bytes -2,147,483,

648 to 2,147,
483,647

ULONG Unsigned Long Integer 4 bytes 0 to 4,294,

(Only for display on a screen.Arit- 967,295
hmetic operations are not sup-
ported. )

LONGBCD Long Binary- Coded Decimal 4 bytes 0 to 99,999,

999

REAL Floating Point 4 bytes -3.4E38 to

3.4E38

STRING String 256 bytes ASCII (null ter-

(maximum) minated)

Tag values can be used with the Cicode Variable data types.
A Cicode variable of INT data type can be used to store Tag data types: BCD, BYTE, DIG-
ITAL, INT, UINT, LONG, ULONG and LONGBCD.

420
Chapter 16: Tagging Process Variables

A Cicode variable of the QUALITY or TIMESTAMP data type can be used to store the
Tag quality and timestamp items.
See Also
Cicode Variable Data Types

Configuring Variable Tags

To configure a variable tag:

1. Start Citect Explorer.

2. Click Variable Tags, or choose Tags | Variable Tags. The Variable Tags form dis-
plays.
3. Enter the properties of the variable tag.
4. Click Add to append a new record, or Replace to modify a record.
At a minimum you need to enter the Variable Tag Name, I/O Device Name, Data
Type, and Address fields.
You can paste any existing variable tag into forms in your project.
To select an existing variable tag:

1. Open the Project Editor.

2. Choose Edit | Paste Tag.
To configure a digital tag:

1. Open the Project Editor.

2. Click Variable Tags, or choose Tags | Variable Tags.
3. Complete the properties in the Variable Tags dialog box that appears, using DIG-
ITAL as the Data Type.
4. Click Add to append a new record, or Replace if you have modified a record.
You need to at least enter the Variable Tag Name, I/O Device Name, Data Type, and
Address fields. Leave the following properties blank:
l Raw Zero Scale, Raw Full Scale
l Eng Zero Scale, Eng Full Scale
l Eng Units, Format
To configure an analog tag:

1. Start the Project Editor.

2. Click Variable Tags or choose Tags | Variable Tags. The Variable Tags form
appears.

421
Chapter 16: Tagging Process Variables

3. Enter the properties, using INT (or Real, BCD, Long, LongBCD) as the Data Type.
4. Click Add to append a new record, or Replace to modify a record.
You need to at least enter the Variable Tag Name, I/O Device Name, Data Type, and
Address fields.
See Also
Variable Tag Properties
Formatting numeric variables

Variable Tag Properties

You can use this dialog for Configuring Variable Tags.

Note: When modifying a variable tag, be aware that if the variable tag was created
using the equipment editor - equipment type workspace, the fields configured will be
grayed out in the variable tag properties form.

Variable tags have the following properties:

Equipment
The name of the equipment associated with the Variable Tag. The name should be 254
characters or less. This property is optional. If you do not specify or select an equipment
name, then no equipment will be associated with the Variable Tag.
Item Name
An Item is an attribute of a physical device that is defined as equipment within your sys-
tem. For example: equipment can have numerous items, with each 'Equipment.Item'
associated to a variable tag.

Equipment Item Equipment.Item Tag Name

Name

Plant.Mixer.Fu- Proc- Plant.Mixer.Fu- Raw_Full-

llMilk.Temperature ess llMilk.Temperature.ProcessVariable MilkTemp_
Var- PV
iable

Set- Plant.Mixer.Fu- Raw_Full-

Point llMilk.Temperature.SetPoint MilkTemp_
SP

Out- Plant.Mixer.FullMilk.Temperature.Output Raw_Full-

put MilkTemp_
OP

Used as part of the equipment hierarchy an item name will help with future migration
of your system and the step towards an object oriented model.

422
Chapter 16: Tagging Process Variables

This field is optional. If not configured, the last 63 characters of the “Variable Tag” field
will be used for the item name. The Variable Tag name allows 79 characters, while item
name has a maximum of 63 characters. This may result in the compiler generating an
alert message if the 'Equipment.Item' name is not unique.
When defining an equipment name and item name the following rules apply:
l There is a limit of 254 characters on the combination of Equipment and Items, includ-
ing the period '.', for example “Equipment.Item” should be 254 characters or less.
l Equipment name needs to exist in the same cluster as the tag.
l Item name needs to follow tag name syntax. E.g. '%', '?', '/', etc. characters are not
allowed as part of the name.
l Equipment and Item path of a tag may not be the same as that of another equipment.
E.g. Equipment1 = part1, Equipment2 = part1.part2, a tag cannot have equipment =
part1 and item = part2 as it will clash with the name of Equipment2.
l Item name may not be the same as tag extension keywords, i.e. Field, Valid, Override,
OverrideMode, ControlMode, Status, V, VT, Q, QT, T.
See also Scenarios of Item Name for additional information regarding this field.
Cluster Name
The name of the cluster to which the tag applies (16 characters). Select a cluster name
from the list of available clusters as defined under Cluster Definitions.
Comment
Any useful comment (254 characters).
Tag Name
You can use any name for a tag (79 characters) provided it follows the Tag name syntax
and isn't the same as the name of a Cicode function within the project or any included
projects (see Defining Variable Tag Names for a list of restrictions on naming). If you
have many tags, use a naming convention (see Using structured tag names). This makes
it easier to find and debug your tags.When the tag name is referenced on a graphics
page, Cicode, etc., it can be used with or without a specific tag element or item.
If you are using distributed servers, the name needs to be unique to the cluster (for exam-
ple, you cannot have the same variable tag name in more than one cluster).

Note:CitectSCADA will automatically resolve tags without a cluster context specified

if every tag name in the project is unique. See Resolving cluster context with unique
tag names.

I/O Device

423
Chapter 16: Tagging Process Variables

The name of the I/O Device where the variable is stored (31 characters). If using I/O
Device redundancy, you need to specify the primary I/O Device name here, not the
standby.

Note: Avoid changing the tag's I/O device name from this FORM as the variable.dbf will not be updated.If you
do change the tag's I/O device name you will need to clear the tag's reference fields.

Address
The register address in the I/O Device where the variable is stored (254 characters). The
format and prefix of an address will depend on the protocol configured for the I/O
Device, which can be determined by checking the Protocol field on the I/O Devices form
in Project Editor.
Data Type
The type of I/O Device variable (16 characters). I/O Devices support several data types
that are used to exchange data with CitectSCADA. Because of the lack of an industry
standard, many I/O Device manufacturers use individual naming conventions for their
I/O Device variables. However, every variable corresponds to one of the Tag data types.

Note: If you do not specify a range for your tag, then an out of range alert message
will be generated if you write a value which is outside the range of the type.

You need to specify the correct data type that corresponds to the data type of the I/O
Device variable you are configuring. Each data type has a unique address format. You
need to use this format when you are specifying the address of the variable (as the
Address property).
You will want to verify that you only use data types that are valid for your I/O Device. If
you do not specify a data type, the variable will be treated as 16-bit integer.
CitectSCADA supports concatenation of I/O Device registers. For example, you can
define a real data type (in CitectSCADA) as two contiguous int data types (in the I/O
Device). CitectSCADA reads across the boundary of the two ints and returns a real.
If you use concatenation of registers, the address of the variables needs to be on odd
boundaries or even boundaries. You cannot mix address boundaries. For example, V1,
V3, V5 are valid addresses.
Be careful when using this feature: the I/O Device needs to maintain the integrity of the
second register. (If the I/O Device writes to the second int, the value of the real could be
corrupted.) The structure of some I/O Devices might not support this feature, and might
therefore behave unpredictably.

424
Chapter 16: Tagging Process Variables

UNINTENDED EQUIPMENT OPERATION

Do not mix the use of odd and even variable addresses as boundaries when you are con-
catenating registers.

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

Eng Zero Scale / Eng Full Scale

The scaled values that CitectSCADA calculates from the raw values (11 characters). The
Raw Zero Scale is scaled to the Eng Zero Scale and the Raw Full Scale is scaled to the
Eng Full Scale. These properties are represented in engineering units and are used as the
upper and lower limits of trends and bar graphs.
Many I/O Devices return an integer to indicate the value of an analog input. To return a
usable value, the I/O Device converts an input signal (usually 4-20 mA) to a raw scale
variable, usually in the range 6400 to 32000.
To present this variable as a meaningful value, you can specify a scaling calculation.
CitectSCADA then scales every value accordingly, as in the following diagram.

The scaled value of the variable (engineering value), not its raw value, is used through-
out the system.
The scaling properties are optional. If you do not specify scaling, Eng Zero Scale defaults
to Raw Zero Scale, and Eng Full Scale defaults to Raw Full Scale; that is, no scaling
occurs.

425
Chapter 16: Tagging Process Variables

A value that is below the specified Raw Zero Scale or above the specified Raw Full Scale
causes an "Out of Range" alert message in your runtime system.
String variables
While numeric variables are more common, some I/O Devices also support ASCII
strings. You can use strings to store text data (for example, from a bar code reader).
All strings needs to be NULL-terminated in the I/O Device. CitectSCADA uses the NULL
character to check for the end of a string, and if no NULL character is present, Citect-
SCADA reads (and displays) any extra characters in memory, after the end of the string.
When you are using a disk I/O Device, you can also specify a string data type for storage
of recipes, or for operator display information.
Not every I/O Device supports strings. However, if your I/O Device does support integer
data types, CitectSCADA can use these integer registers to store ASCII strings in your I/O
Device. CitectSCADA strings can only be stored in contiguous blocks (consecutive reg-
isters), and are stored as an array.

Note: Non printable characters within string tag values will be substituted with
spaces e.g. string [ 0x01, 0x41, 0x10, 0x42 ] will appear as " A B", so cache loading
continues to operate.

To display the data types for an I/O Device, double-click the I/O Devices book from the
Help, select your I/O Device from the list, and then select the Data Types topic.
Linked
The Linked field in the status line of the Variable Tags form reads either Yes or No and
indicates whether or not the variable tag is linked to an external data source. When you
program an I/O Device using software other than CitectSCADA, an external data source
is used to store tag data. Linked variable tags are updated whenever external tag data
changes, meaning you are not required to enter the information again in CitectSCADA.

Extended forms fields

The following fields are implemented with extended forms (press F2). Note that some of
the fields listed below may be displayed in the previous section of the form.
Raw Zero Scale / Raw Full Scale
The unscaled (raw) values (of the variable) that represent the zero point and full scale
point for the data (11 characters). The raw values are the values that CitectSCADA reads
from the I/O Device.
Eng Units

426
Chapter 16: Tagging Process Variables

(8 characters.) The engineering units that the value represents (for example %, deg,
mm/sec, etc.). This property is optional. If you do not specify engineering units, no engi-
neering units are used.
Format
(11 characters). The display format of the value (of the variable) when it is displayed on
a graphics page, written to a file, or passed to a function (that expects a string). This
property is optional. If you do not specify a format, the format defaults to ####.##.
Deadband
(11 characters). A deadband allows the value of a variable tag to fluctuate within a
defined threshold without updates being sent through the system. This may be useful if
a tag produces many small, insignificant value changes. The threshold is represented as
a percentage of the tag's engineering range. The default value is 0 (zero), which captures
every value change.
For example, if a variable tag has an engineering range of zero to 10000, a deadband of 1
would mean a change in value would have to be greater than 100 (or 1 percent of the
range) to be recognized. If the current value was 5600, the tag in the PLC would have to
change to a value greater than 5700 or less than 5500 before an update would be sent
through the system.
The deadband setting for a variable tag will not apply to an associated trend tag. If a
trend tag requires a deadband setting, it should be configured independently in the trend
tag properties.
Historize
This field enables you to automatically historize and publish the specified variable tag
in Schneider Electric's Historian application.
If you set this field to "TRUE", the variable will be included in an automated con-
figuration process within the Historian environment. If you set the field to "FALSE" (or
leave it blank), the variable will not be included.
Custom 1...Custom 8
A user-defined string can be used for storage of static information. Information contained
within custom1..8 can be used for categorization purposes, as such, it does not usually
change during runtime.
See Integration with Historian.

Defining Variable Tag Names

You cannot use certain reserved words when defining your tag name variables. You can-
not use:

427
Chapter 16: Tagging Process Variables

l Reserved words such as:

& * ** -

/ + < <=

>= <> = >

ACTION AND ANY_NUM ARRAY

BOOL CASE CON- CON-

FIGURATION STANT

DATE DATE DINT DO

DUT DWORD ELSE EN

END_ END_CON- END_FOR END_IF

CASE FIGURATION

END_PRO- END_VAR END_WHILE ENO

GRAM

EXIT FALSE FOR FUNCTION

IF INT INT MOD

NOT OF OR PROGRAM

REAL REPEAT STRING STRING

TASK TIME TIME TO

TRUE TRUE UNTIL VAR_

EXTERNAL

VAR_ VAR_IN_OUT VAR_INPUT VAR_OUT-

GLOBAL PUT

WHILE WORD XOR

l Cicode function names. See Functions Reference for an entire list of Cicode functions.
Using reserved words or Cicode function names may cause a syntax error.

428
Chapter 16: Tagging Process Variables

Referencing Variabe Tags in your project

You can reference Variable tag names (as a string) in your project, using any of the fol-
lowing formats:
l Tag Name
l cluster.tagname (used in multi-cluster systems)
l equipment.item
l cluster.equipment.item

Note: If the tag name exceeds the length limit of 254 characters the hardware alarm
"Tag name exceed length limit" will be raised.

See also
Variable Tag Properties
CtAPI Functions

Formatting numeric variables

The value of a numeric variable (number) can be displayed on a graphics page or
written to a file in many different formats (for example, 24, 0024, 24.000, or 24.0%).

Format specifiers
Format specifiers are keyboard characters that you use to define the format for the
numeric variable. The specifiers that you can use are:

Specifier Description Function

# The hash character The number of characters to display

0 Zero Padding

- Minus Justification

. Period Decimal notation

EU Engineering units

S Exponential notation

429
Chapter 16: Tagging Process Variables

Specifying the number of digits

The hash character (#) specifies how many digits CitectSCADA displays. every numeric
variable displays to the right of an animation point, for example:
Format: ####
In this example, CitectSCADA displays at least four digits (or spaces) to the right of the
animation point. If the number contains more than four digits, the first digit is located at
the animation point. The following figure illustrates several numbers in the above for-
mat.

Padding with zeros

When a number contains fewer digits than your format specifies (5 or 75 in the above
example), CitectSCADA only displays the meaningful digits. You can use the padding
character, zero (0), as the second character in the format string, to fill the number with
zeros, for example:
Format:#0##
This format string displays:

430
Chapter 16: Tagging Process Variables

Changing justification
By default, numeric variables are right-justified (within their field). You can change the
default justification by using a minus (-) sign as the second character in the format
string, for example:
Format: #-###
This format string displays:

Specifying decimal notation

To specify decimal notation, use a period (.), for example:
Format: ###.##
In this example, CitectSCADA displays three digits before the decimal point and two dig-
its after. If the variable is 12.3, CitectSCADA displays 12.30.
All numbers are automatically rounded, i.e. 12.306 displays as 12.31.

Specifying engineering units

You can specify engineering units (such as %, deg, rpm, M, mm/sec, etc.) when you
define a variable tag. To include these units in the format of the number, type EU in the
appropriate position.
Format: ####.##EU

Note: If you do not specify an engineering unit for the variable, only the number is
displayed (or logged).

Specifying exponential notation

To specify exponential notation, include the exponential character (s), for example:
Format: #s###

431
Chapter 16: Tagging Process Variables

In this example, CitectSCADA displays the number in exponential notation format, for
example: 1.234e+012.

Combining format specifiers

You can combine format specifiers, for example:
Format: #0-###.##EU
This format string displays six digits before the decimal point and two digits after. The
number is left justified, padded, and displayed with engineering units (if specified).

Using shortform notation

As an alternative to the hash (#) notation, you can use shortform notation. With short-
form notation, you use a number to specify the format of the numeric variable, for exam-
ple:
Format: 3.2
This format string displays three digits before the decimal point and two digits after.
This format string is equivalent to the ###.## format specification. You can also include
engineering units with shortform notation, for example:
Format: 6.0EU
This format string displays six digits before the decimal point and no digits after. The
number is displayed with engineering units (if specified). This format string is equiv-
alent to the ######EU format specification.
You cannot use padding or left justification with shortform notation.

Note: If the value of a numeric variable is extremely large, it is displayed in expo-

nential notation (for example 1.2345E012).If no format is specified for a variable, the
default ####.# (or 4.1) is used.

Variable Tag Name Conveyor_Speed

Address V500[5]

Here, five register addresses are referred to by the variable tag Conveyor_Speed.

Referring to array variables

Each entry of an array is referred to by an index. You can extract individual variables
(from the array) by specifying the tag name and index:

<Tag Name>[Index]

For example, to refer to the third variable of the array in the above example (Conveyor
3), use the following syntax:

Variable Tag Conveyor_Speed[2]

The index of the first entry of an array is always 0 (zero). In this example, Conveyor_
Speed[0] is the first entry of the array (Conveyor 1), and Conveyor_Speed[4] is the last
entry (Conveyor 5).
Note the following when using arrays:

433
Chapter 16: Tagging Process Variables

l Do not define large arrays, because each time an individual array entry is requested,
CitectSCADA reads the entire array from the I/O Device. With large arrays, system
performance could be reduced.
l The size of the array needs to be less than the maximum request length of the pro-
tocol. The I/O Device description help topic (for your I/O Device) displays the max-
imum request length of the protocol.
l declare digital arrays on a 16 bit boundary. CitectSCADA rounds each digital array
down to the nearest 16 bit boundary. Consequently, digitals in the array are changed.
For example, if you declare an array Test to start at bit 35, and CitectSCADA starts
the array at bit 32. The index to the array also starts at bit 32; Test[0] refers to bit 32,
not bit 35.
l Each individual array entry has its own data value for the field, valid and override
elements, but the entries within an array share the override and control mode ele-
ments, quality and timestamps. Reading the quality or timestamp for an indexed
array entry will return the quality or timestamp for the entire array. Writing to the
value for an indexed array entry will change the timestamps and quality for the
entire array. Changing the override mode and the control mode for an array entry
will change it for the entire array.
See Also
Tag Extensions

String arrays
If you are using a CitectSCADA string data type, you need to specify an array of integer
data types. One int register stores two string characters.
To calculate the size of an array (for string data types), use the following formula:

The last element of the array is always used to store the null character '\0'. This char-
acter marks the end of the string.
To store the word "Recipe", you need to specify an array with 4 elements, for example:

Variable Tag Name Recipe_Tag

Address V500[4]

Two characters are stored in each register, i.e:

434
Chapter 16: Tagging Process Variables

You can then refer to the entire string by specifying the tag:

For example:

Variable Tag Recipe_Tag

To store the word "Recipes", you would also specify an array with 4 elements. The char-
acters are stored as follows:

Note: If your I/O Device supports string data types, you need to specify the address
in the format determined by the I/O Device you are using.

Configuring 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 may be of any data type supported by Citect-
SCADA, including two-dimensional arrays of standard CitectSCADA types.
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.
To configure a local variable:

1. In Project Editor, select Tags | Local Variables. The Local Variables dialog displays.
2. In the Name field, enter a name for the local variable. Variable names cannot include
the '-', '/', '%' or <space> characters.
3. In the Data Type field (16 characters), select one of the following supported data
types:

Data Variable Size Allowed Values

Type

BCD Binary- Coded Dec- 2 0 to 9,999

imal bytes

BYTE Byte 1 0 to 255

byte

DIGITAL Digital 1 bit 0 or 1

or 1
byte

INT Integer 2 -32,768 to 32,

bytes 767

UINT Unsigned Integer 2 0 to 65,535

bytes

LONG Long Integer 4 -2,147,483,648

bytes to 2,147,483,647

LONGBCD Long Binary- 4 0 to 99,999

Coded Decimal bytes

REAL Floating Point 8 -1.7e308 to

436
Chapter 16: Tagging Process Variables

bytes 1.7e308

STRING String up to ASCII (null ter-

256 minated)
bytes

Numeric and digital variables have a default value of 0 and string variables default to ""
(empty string). If you do not specify a data type, the local variable will be treated as 16-
bit integer.
4. In the Array Size field (8 characters), enter the size of the array (number of elements)
used to store the local variable. The array will be of the data type specified in the
Data Type field. The array can be one or two-dimensional. Up to 32766 elements can
be used, which, for a two dimensional array, means that the size of the first dimen-
sion multiplied by the size of the second is less than or equal to 32766. When spec-
ifying a multi-dimensional array, separate the dimensions with a comma, for
example "20,30"."
5. In the Zero Scale field (11 characters), enter the value of the local variable that rep-
resents the zero point for the data. The zero scale value is used as the lower limit for
trend and bar graphs, and values below the zero scale value will cause an "Out of
Range" alert message in the runtime system.
6. In the Full Scale field (11 characters), enter the value of the local variable that rep-
resents the full scale point of the data. The full scale value is used as the upper limit
for trend and bar graphs, and values above the full scale value will cause an "Out of
Range" alert message in the runtime system.
7. In the EngUnit field, enter the engineering units that the value represents (for exam-
ple %, deg, mm/sec, etc.). This property is optional. If you do not specify engineering
units, no engineering units are used.
8. In the Format field, Enter the display format of the value (of the variable) when it is
displayed on a graphics page, written to a file, or passed to a function (that expects a
string). This property is optional. If you do not specify a format, the format defaults to
####.#.
9. In the Comment field, enter any useful comment. This property is optional and is not
used at runtime.
10. Click Add.
See Also
Configuring Variable Tags

437
Chapter 16: Tagging Process Variables

Tag Browsing
Tag browsing enables you to browse a list of variable tags owned by a data source at
runtime, in the same way that you can with alarm and trend browsing. Once a tag
browsing page has been created in the Graphics Editor during development it will be
available to the runtime operator. The tag browsing page can present any of the fol-
lowing information to the operator:
l Any configuration field available on the Variable Tag form and including a newly
added Equipment Field.
l Some fields available from the Cicode functions of TagInfo and TagInfoEx.
l Tags which are in Override Mode.
l Tags which are in Control Inhibit Mode.
l The Number of current subscriptions.
Tag browsing enables you to browse to the tag element level only, for example, '.field'.
Refer to the TagBrowseOpen Cicode function for a list of supported fields.
For more details on the above Value, Quality, Timestamp tag elements and sub elements
refer to the Tag Extension topic.
See also
The Browsing Session
Opening a Browsing Session

The Browsing Session

In order to access the tag information at runtime, the client computer initiates a con-
nection to the servers specifying the browsing session parameters such as required fields
and filters. It is possible to open and maintain multiple browsing sessions
simultaneously.
Each server in a session prepares a snapshot of its data and sends records in batches to
the client. As the server records arrive, the client reconciles them against each other in
the event that duplicate or conflicting data arrives from different servers.
The records reconciliation is based on records with the “best device status” which are
selected, and the others are discarded.
“Best device status” is calculated as follows:
l Data Source online state (ONLINE is picked over OFFLINE), then
l Data Source active state (ACTIVE is picked over INACTIVE), then

438
Chapter 16: Tagging Process Variables

l Data Source priority (higher priority is picked over a lower one, with highest being 1
– for primary I/O device)
If records from different I/O servers fully match on “best device status” the browsing rec-
ords are taken on the first-come basis. Be aware that there may be project inconsistencies
(on different machines) which can affect tag browsing functionality. This can occur if a
project is being updated across a number of servers, but only gradually, so there may
exist several versions of the project across the network. Tag Browsing will try to rec-
oncile the conflicting data the best way possible, but in such cases check that the
returned data is correct.
For each server session the client keeps track of how many records are expected, and
what the last record received was. The TagBrowseNext Cicode function will either cause
the client to look at the next cached record which was received earlier and fully rec-
onciled, or request the next batch of records from the I/O servers.
If a a communication disruption occurs during the browsing process, or when the client
explicitly closes the browsing session, the session will be terminated.
See also
Tag Browsing
Opening a Browsing Session

Opening a Browsing Session

Open a browsing session by using the TagBrowseOpen Cicode function, the server then
builds a snapshot (representing the state the data at the time of the TagBrowseOpen call)
of the data requested. A snapshot from a given server contains the same number of rec-
ords as the number of tags available from all I/O devices. Requesting only the
“CLUSTER” field with 10000 tags belonging to three clusters will produce a snapshot
with 10000 records where entries Cluster1, Cluster2, Cluster3 will be repeating a number
of times.
The snapshot will exist on the server until all the records have been fetched by the client,
or the browse session is closed, or an existing connection is lost, or a new connection is
established.
When you use the TagBrowseOpen function you have the option to specify several
parameters which will determine which tags will be displayed. These parameters are
used to select tags to display in the browsing session as described below.
See also
The Browsing Session
Tag Browsing
Browsing Field
Browsing Filter
Browsing Clusters

439
Chapter 16: Tagging Process Variables

Sort Order

Browsing Filter
A browsing filter can be used to specify the records to return during the browsing ses-
sion, using a set of predefined field names, shown below, within a regular expressions
separated by a semicolon. For example, the filter “NAME=Tag_IO_*;TYPE<2” would
result in requesting all tags from all clusters where the tag name matches the pattern
“Tag_IO_*” and tag type is 0 (DIGITAL) or 1 (INTEGER). 1). If you do not specify a filter
string then all tag records will be displayed.
If any of the filter names are invalid, opening a browsing session will not succeed and
will return an invalid handle.
See also
The Browsing Session
Opening a Browsing Session
Browsing Field
Clusters
Sort Order

Browsing Field
Fields are specified using a set of predefined field names, separated by a comma. For
example, “TAG,TYPE,ENG_UNITS”. Each browsing record arriving from the server in
response to the request will be represented as a list of key-value pairs. At least one field
should be specified. If any of the fields are invalid, opening a browsing session does not
succeed.
Only the fields explicitly asked for will be available for the TagBrowseGetField function.
The only exception to this are the fields mentioned within the sort order since record sort-
ing takes place on both the server and the client and sorting cannot be done on a field
which is not available on the client.
See also
The Browsing Session
Opening a Browsing Session
Browsing Filter
Browsing Clusters
Sort Order

440
Chapter 16: Tagging Process Variables

Sort Order
You can optionally include a preferred sort order for the fields returned in the browsing
session, each field being indicating if A – ascending or D – descending). For example
"TYPE:D". By default tag browsing records are sorted by the tag primary key which is
Cluster.TagName. which is implicitly appended to the list of sorting fields, since the
other fields may end up not being unique.
Tag records are sorted on the server, and arrive at the client in the order specified by the
sort order parameter, or the default sorting order.
See also
The Browsing Session
Opening a Browsing Session
Browsing Filter
Browsing Clusters
Browsing Field

Browsing Clusters
An optional parameter can be included using a comma delimited string that specifies
the clusters containing tags to be included in the browse session. An empty string indi-
cates that the all clusters will be browsed.
See also
The Browsing Session
Opening a Browsing Session
Browsing Filter
Browsing Field
Sort Order

Tag Extensions
A variable tag is a representation of data elements. 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 to access
the following information:

Element Description

.field The field element, which represents the latest field data received from
the device (see Reading Tag Values).

.valid The valid element, which represents the last field data which had

441
Chapter 16: Tagging Process Variables

Element Description

‘Good’ quality (see Reading Tag Values).

.override The override element, which represents the overridden tag value (see
Controlling and Overriding Tag Values).

.overridemode The override mode, which is used to set the override behavior of the
tag (see Override Mode).

.controlmode The control mode, which is used to set the control inhibit mode of the
tag (see Control Inhibit Mode).

.status The tag status element, which is used to represent the current status
of the tag (see Tag Status).

The tag and each element have items that can be referenced to access the following infor-
mation:

Item Description

v The value, which will access the data value of the tag or element.

vt The value timestamp, which will access the timestampof when the
value last changed.

q The quality, which will access the quality quality of the value, either
GOOD, UNCERTAIN or BAD. You can access further detail from the qual-
ity using the Cicode Quality functions.

qt The quality timestamp, which will access the timestamp of when the
quality last changed.

The timestamp, which will access the timestamp of when the tag or ele-
t
ment was last updated.

The tag reference syntax is:

[Cluster.]Tag[.Element][.Item][ [n]], where

Cluster The optional cluster name.

Tag The tag name or SuperGenie association.

Element The optional element name. If the element name is not specified, the
requested element will be determined at runtime.

Item The optional item name. If the item name is not specified, the whole ele-
ment is referenced.

n The optional array index if the tag is defined as an array.

The array index is at the end of the reference (MyArray.v[n], MyArray.Field[n], MyAr-
ray.Field.v[n]). There is only a single quality and timestamp for each array, each member
will return the same quality and timestamp.

442
Chapter 16: Tagging Process Variables

Note: Consider the impact on network traffic when configuring tag extensions, as the
distribution of quality and value timestamps increases the amount of data being sent
between servers.

You can access Tag data in the following ways:

1. Reference the tag data by using only the tag name, for example ‘MyTag’ (unqualified
tag reference). This will provide default access to the Field element information, unless
the tag is in one of the override modes.
2. Reference the tag data by using the tag name and the item name, for example
‘MyTag.q (unqualified tag reference). This will provide access to the item information for
the tag, either default from Field or Override element.
3. Reference the tag data by using the tag name and the element name, for example
‘MyTag.Field’ (qualified tag reference). This reference will provide access to the specific
tag element information.
4. Reference the tag data by using the tag name, element name and the item name, for
example ‘MyTag.Field.vt’. This reference will provide access to the specific tag element
item (qualified tag reference).
You can also access alarm data similar to tag data. See Using Alarm Properties as Tags.
Controlling Tag Extension behavior

By default, the tag data referenced without an element will provide access to the data
value when the value is of quality is good and an error (#BAD, #COM, etc) when the
quality is bad. The configuration parameter PageIgnoreValueQuality can be used to
change this behavior, including automatically changing the background color of text and
number graphics objects on a page with changes in quality of the tag.
The Tag Extensions behavior is controlled by several citect.ini file settings which are
described in the Parameter Help file. For each of these settings there is a corresponding
setting in the parameters database (param.dbf). A citect.ini file setting specifies behavior
for a particular machine and a parameter database setting is applied system-wide. The
citect.ini file setting can be entered using the Computer Setup Editor, the parameter data-
base settings are configured in the CitectSCADA Project Editor from the System, Param-
eter menu.

Note: By default, the TagSubscribe Cicode function is set to retrieve "lightweight" tag
values that exclude quality and value timestamps. If you need a subscription to
retrieve timestamp data, you need to set the "bLightweight" argument to 0 (false).

See Also
The Quality Tag Element
Reading and Writing Tags

443
Chapter 16: Tagging Process Variables

Tag Data Types

Controlling and Overriding Tag Values

The Quality Tag Element

The majority of data which is contained within the variable tag is represented as an ele-
ment which includes the items "Value", “ValueTimestamp”, “Quality”, “Qual-
ityTimestamp” and "Timestamp". With the exception of "Quality" these items are
absolutes of a single value. However the 'Quality" item has several layers of information
within it. These layers of information are covered by the following categories:
The primary layer identifies the General Quality Values.

Cicode label
Value Description
name

QUAL_BAD 0x00 Value is not useful for reasons indicated by the Substatus Bit
Field.

QUAL_UNCR 0x01 The Quality of the value is uncertain for reasons indicated by the
Substatus Bit Field.

QUAL_GOOD 0x03 The Quality of the value is Good.

These can be accessed from a text object on a graphics page at runtime or with Cicode
using the QualityGetPart Cicode function and the necessary Part parameter.
Within each of these quality values is a second, substatus layer, and a third extended
substatus layer. These layers of information listed below can also be accessed using the
QualityGetPart Cicode function.
l QUAL_BAD Substatus Values
l QUAL_UNCR Substatus Values
l QUAL_GOOD Substatus values
There is also the additional informational value of "Quality Limit" and "Tag Status"
accessed using the QualityGetPart Cicode function or the appropriate function shown
below.
Quality Limit

Cicode label
Value Description
name

QUAL_LIMITED_ 0x0 The value is free to move up and down.

NOT_LIMITED

QUAL_LIMITED_ 0x1 The value has ‘pegged’ at some lower limit.

LOW

QUAL_LIMITED_ 0x2 The value has ‘pegged’ at some high limit.

444
Chapter 16: Tagging Process Variables

Cicode label
Value Description
name

HIGH

QUAL_LIMITED_ 0x3 The value is a constant and cannot move.

CONSTANT

Quality Tag Status

Cicode label
Value Description
name

QTS_OVERRIDE 0x01 The tag is in Override mode.

QTS_CONTROL_ 0x02 The tag is in Control Inhibit Mode.

INHIBIT

QUAL_BAD Substatus Values

Use the the QualityGetPart Cicode function and the necessary Part parameter to return
the details of a QUAL_ BAD tag. The following table identifies the possible information
that will be returned.

Cicode label
Value Description
name

QUAL_BAD_NON_ 0x00 The value is bad but no specific reason is known.

SPECIFIC

QUAL_BAD_CON- 0x01 There is some server-specific incorrect configuration. For

FIGURATION_ example, the item in question has been deleted from the con-
ERROR figuration.

QUAL_BAD_NOT_ 0x02 The input is necessary to be logically connected to something

CONNECTED but is not. This quality may reflect the fact that no value is avail-
able at this time, for reasons like the value may not have been
provided by the datasource.

QUAL_BAD_ 0x03 An inoperative device has been detected.

DEVICE_FAILURE

QUAL_BAD_SEN- 0x04 An inoperative sensor has been detected (the ‘Limits’ field can
SOR_FAILURE provide additional diagnostic information in some situations).

QUAL_BAD_ 0x05 Communication has been lost, however, the last known value is
LAST_KNOWN_ available. The age of the value may be determined from the
VALUE TIMESTAMP in the OPCITEMSTATE.

QUAL_BAD_ 0x06 Communication has been lost. There is no last known value
COMM_FAILURE available.

QUAL_BAD_OUT_ 0x07 The block is off scan or otherwise locked. This quality is also
OF_SERVICE used when the active state of the item or the group containing
the item is InActive.

445
Chapter 16: Tagging Process Variables

Cicode label
Value Description
name

QUAL_BAD_WAIT- 0x08 After items are added to a group, it may take some time for the
ING_FOR_INI_ server to actually obtain values for these items. In such cases,
DATA the client might perform a read (from cache), or establish a
ConnectionPoint based subscription and/or execute a refresh
on such a subscription before the values are available. This
substatus is only available from OPC DA 3.0 or newer servers.

See Also
QUAL_EXT Substatus Values
QUAL_GOOD Substatus Values
QUAL_UNCR Substatus Values
The Quality Tag Element

QUAL_UNCR Substatus Values

Use the the QualityGetPartCicode function and the necessary Part parameter to return
the details of an UNCERTAIN quality tag. The following table identifies the possible
information that will be returned.

Cicode label
Value Description
name

QUAL_UNCR_ 0x00 The value is uncertain but no specific reason is known.

NON_SPECIFIC

QUAL_UNCR_ 0x01 Whatever was writing this value has stopped doing so. Regard
LAST_USABLE_ the returned value as ‘stale’. This differs from a BAD value with
VALUE Substatus 5 (0x14) (Last Known Value). This status is asso-
ciated specifically with a detectable communication error on a
‘fetched’ value and indicates the failure of some external source
to ‘put’ something into the value within an acceptable period of
time. The age of the value can be determined from the TIMES-
TAMP in OPCITEMSTATE.

QUAL_UNCR_ 0x04 Either the value has ‘pegged’ at one of the sensor limits (in
SENSOR_NOT_ which case, set the limit field to 1 or 2) or the sensor is other-
ACCURATE wise known to be out of calibration via some form of internal diag-
nostics (in which case,set the limit field to 0).

QUAL_UNCR_ 0x05 The returned value is outside the limits defined for this param-
ENG_UNIT_ eter. In this case the Limits field indicates which limit has been
EXCEEDED exceeded but does NOT necessarily imply that the value cannot
move farther out of range.

QUAL_UNCR_ 0x06 The value is derived from multiple sources and has less than the
SUBNORMAL necessary number of Good sources.

QUAL_GOOD Substatus Values

QUAL_BAD Substatus Values
The Quality Tag Element

QUAL_GOOD Substatus Values

Use the the QualityGetPart Cicode function and the necessary Part parameter to return
the details of a GOOD quality tag. The following table identifies the possible information
that will be returned.

Cicode label
Value Description
name

QUAL_GOOD_ 0x00 The value is good. There are no special conditions.

NON_SPECIFIC

QUAL_GOOD_ 0x06 The value has been Overridden. Typically this is means the input
LOCAL_OVER- has been disconnected and a manually entered value has been
RIDE "forced".

See Also
QUAL_EXT Substatus Values
QUAL_BAD Substatus Values
QUAL_UNCR Substatus Values
The Quality Tag Element

QUAL_EXT Substatus Values

Use the the QualityGetPart Cicode function and the necessary Part parameter to return
the details of a BAD or UNCERTAIN quality tag. The following table identifies the pos-
sible information that will be returned.

Cicode label
Value Description
name

QUAL_EXT_ 0x00 There is no specific extended substatus value.

NON_SPECIFIC

QUAL_EXT_ 0x01 The device is a scheduled device that is offline and no cache
SCHEDULED_ value is available.
OFFLINE

QUAL_EXT_ 0x02 The tag configuration is invalid.

INVALID_TAG

QUAL_EXT_ 0x03 The value of the tag is invalid.

INVALID_DATA

447
Chapter 16: Tagging Process Variables

Cicode label
Value Description
name

QUAL_EXT_ 0x04 An internal software error occurred in the device driver.

SOFTWARE_
ERROR

QUAL_EXT_ 0x05 Too many devices are attached.

TOO_MANY_
DEVICES

QUAL_EXT_ 0x06 Communication is not initialised.

COMM_NO_INIT

QUAL_EXT_ 0x07 Bad communication.

COMM_BAD

QUAL_EXT_ 0x08 Tag address is out of range.

TAG_OUT_OF_
RANGE

QUAL_EXT_ 0x09 Tag is not readable.

WRITE_ONLY

QUAL_EXT_ 0x0A Write operation is not authorised.

WRITE_PRO-
TECTED

QUAL_EXT_NO_ 0x0B No cluster is specified within a system or for a given tag.

CLUSTER_SPEC-
IFIED

QUAL_EXT_ 0x0C The requested cluster is not known or no clusters are available.
CLUSTER_NOT_
FOUND

QUAL_EXT_ 0x0D The requested cluster is disabled.

CLUSTER_DIS-
ABLED

QUAL_EXT_SES- 0x0E Cannot connect to the requested session.

SION_NOT_CON-
NECTED

QUAL_EXT_ 0x0F Tag could not be resolved.

TAG_RESOLVE_
TIMEOUT

QUAL_EXT_ 0x10 Tag element value not replicated to every redundant DataSource.
VALUE_NOT_
REPLICATED

QUAL_EXT_ 0x11 Tag element value is “stale.

STALE

QUAL_EXT_ 0x12 Waiting for initial tag value from the DataSource.
WAITING_FOR_
INI_DATA

448
Chapter 16: Tagging Process Variables

Cicode label
Value Description
name

QUAL_EXT_ 0x13 Invalid element used for referencing to a tag.

INVALID_ARGU-
MENT

See Also
QUAL_BAD Substatus Values
QUAL_GOOD Substatus Values
QUAL_UNCR Substatus Values
The Quality Tag Element

Reading and Writing Tags

CitectSCADA represents an I/O Device variable monitored or controlled by the system
as a tag variable. You create a tag variable in the Project Editor specifying the tag var-
iable name, data type, address, deadband and other attributes. After the tag variable has
been created, you can reference it using the tag name. The tag name reference provides
access to the value of the tag variable.
This functionality is available to be read from a tag with a text object on a graphics page
and can be read, and in some cases written to, using Cicode functions or CtAPI func-
tions.
Tag Extensions provide the following additional functionality:
l Access to the tag value quality and timestamp.
l Extended data associated with a variable tag.
l Make this data available to CitectSCADA client components: Control Client, Trend
Server, Alarm Server, Report Server, Cicode and CtAPI.
l Be able to override and prohibit writing to the tag variable value.
l Be able to display and trend the tag values even if their quality is not “Good”.
l Be able to have the real PLC quality and timestamp in CitectSCADA and to make it
available.
l Have Persistence and Replication of the tag data.
Each DataSource owns a local tag data cache. This cache is periodically saved to disk,
thus, maintaining last known value (LKV) for each tag. When a DataSource is restarted
its local tags are initialised to their corresponding LKVs, unless the tags have never been
cached before – in which case they are initialised to the default values.

449
Chapter 16: Tagging Process Variables

Tag data from the DataSource cache is periodically saved to disk. When the time comes
to save the file, a temporary file is used, which after it is written simply gets renamed to
the original file name. This is done to avoid partial master file updates or corruption. If
the DataSource is shutdown abruptly, some tag value changes that are waiting to be per-
sisted to disk may get lost. The Field data are currently saved to disk.
The Tag cache file is saved in an XML format, as shown here, preserving the necessary
information about each tag’s value, quality, and timestamp. On load the original per-
sisted quality is substituted by BadLastKnown quality value. The file is saved in the
CitectSCADA Data directory using the name format of:
<ClusterName>.<IOServerName>.<IODeviceName>.cache
If during the file load the schema validation is unsuccessful, the entire file is considered
invalid and the tags LKVs are lost. If during the file load a particular tag’s value, qual-
ity, or timestamp is invalid, the corresponding invalid entry is simply ignored (and
logged as such). Persistence is configurable within the extended section of the Citect-
SCADA I/O Devices properties dialog.

Minimum Update Rate

The DataSource will send tag update value notifications to subscription clients after a
pre-defined period of time expires. The configuration of the minimum update rate period
is performed via the IODevice configuration dialog. Devices that are configured for
redundant operation needs to have minimum update rate set according to the rules spec-
ified in the table below.

Primary Device Standby Device

Compilation
Minimum Update Rate Minimum Update Rate
Result
Value/Staleness Period Value Value/Staleness Period Value

Blank (Default) Blank (Default) OK

Blank (Default) Value Defined Error

Value Defined Blank (Default) OK

Value Defined Same value as primary OK

Value Defined Value is different than on primary Error

Stale Tag Values

When an I/O Data Consumer does not get a tag element value update from the Data-
Source for a specific period of time, as specified by the Staleness period, the tag element
value is considered to be “stale”. The Extended Quality Substatus QUAL_EXT_STALE
will indicate this condition. Processing of staleness period for tags is performed on the
client side of the connection.

450
Chapter 16: Tagging Process Variables

Configuration can be performed on the server using the IODevice properties dialog, or
on the client using Citect.ini parameters.
Staleness Period

The Staleness Period represents the total number of seconds that will elapse after the last
update before extended quality of the tag element is set to “Stale”. It can be configured
on both the server and client. The server configuration is specified in the table above. For
client configuration details refer to the ClientStalenessPeriod parameter.
Staleness Period Tolerance

Staleness Period Tolerance represents the percentage of the staleness period within a
total of which time a check or stale client tag elements will be performed. The default
value is 10%, which caters for a large number of configuration scenarios. You can reduce
or increase the tolerance as necessary by your particular scenario by configuring this
value in the client machine’s using the ClientStalenessPeriodTolerance parameter. This
parameter is not available for server configuration.
Example:
In order to reduce CPU load on the client machine,the default Staleness Period Tolerance
is 10%. This means that if staleness period is set to 600 seconds, a check for stale client
tag elements will be performed every 60 seconds.

XML DataSource Schema

<?xml version="1.0" encoding="utf-8"?>

<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.schneider-ele-
tric.com/Platform/PSI/DataSource/PersistenceCache/V1/"
xmlns:dsps="http://www.schneider-
electric/Platform/PSI/DataSource/PersistenceCache/V1/"
elementFormDefault="qualified"
targetNamespace="http://www.schneider-elec-
tric.com/Platform/PSI/DataSource/PersistenceCache/V1/">

<xs:simpleType name="DataType">
<xs:restriction base="xs:string">
<xs:enumeration value="Boolean" />
<xs:enumeration value="SByte" />
<xs:enumeration value="Byte" />
<xs:enumeration value="Char" />
<xs:enumeration value="Double" />
<xs:enumeration value="Int16" />
<xs:enumeration value="Int32" />

451
Chapter 16: Tagging Process Variables

<xs:enumeration value="Int64" />

<xs:enumeration value="Single" />
<xs:enumeration value="String" />
<xs:enumeration value="UInt16" />
<xs:enumeration value="UInt32" />
<xs:enumeration value="UInt64" />
<xs:enumeration value="Decimal" />
<xs:enumeration value="DateTime" />
</xs:restriction>
</xs:simpleType>

<xs:simpleType name="ElementName"
<xs:restriction base="xs:string">
<xs:enumeration value="" />
<xs:enumeration value="Field" />
<xs:enumeration value="Valid" />
<xs:enumeration value="Override" />
<xs:enumeration value="OverrideMode" />
<xs:enumeration value="ControlMode" />
<xs:enumeration value="Status" />
</xs:restriction>
</xs:simpleType>

<xs:complexType name="DataSource">
<xs:sequence minOccurs="1" maxOccurs="1">
<xs:element name="properties" type="PropertyCollection">
<xs:unique name="UniquePropertyName">
<xs:selector xpath="dsps:property" />
<xs:field xpath="@name" />
</xs:unique>
</xs:element>
<xs:element name="tags" type="TagCollection">
<xs:unique name="UniqueTagName">
<xs:selector xpath="dsps:tag" />
<xs:field xpath="@name" />
</xs:unique>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="PropertyCollection">
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:element name="property" type="Property" />
</xs:sequence>
</xs:complexType>

<xs:complexType name="TagCollection">
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:element name="tag" type="Tag" />
</xs:sequence>
</xs:complexType>

<xs:complexType name="Property">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="name" type="xs:string" use="necessary" />

452
Chapter 16: Tagging Process Variables

<xs:attribute name="type" type="DataType" use="necessary" />

</xs:extension>
</xs:simpleContent>
</xs:complexType>

<xs:complexType name="TagElement">
<xs:sequence minOccurs="1" maxOccurs="1">
<xs:element name="v" type="Value" />
<xs:element name="q" type="Quality" />
<xs:element name="t" type="xs:dateTime" />
<xs:element name="qt" type="xs:dateTime" />
<xs:element name="vt" type="xs:dateTime" />
</xs:sequence>
<xs:attribute name="name" type="ElementName" use="necessary" />
</xs:complexType>

<xs:complexType name="Value">
<xs:sequence minOccurs="1" maxOccurs="unbounded">
<xs:element name="item" type="xs:string" />
</xs:sequence>
<xs:attribute name="type" type="DataType" use="necessary" />
<xs:attribute name="size" type="xs:positiveInteger" use="necessary" />
</xs:complexType>

<xs:complexType name="Quality">
<xs:sequence minOccurs="1" maxOccurs="1">
<xs:element name="generic" type="xs:integer" />
<xs:element name="specific" type="xs:integer" />
</xs:sequence>
</xs:complexType>

<xs:element name="datasource" type="DataSource" />

</xs:schema>

Reading Tag Values

The data received from the field is represented by the Field and Valid tag elements.
l The Field element represents the latest tag field data received from the device.
l The Valid element represents the last field data which had “Good” quality.

453
Chapter 16: Tagging Process Variables

Note:The Valid tag element initially has bad quality. The quality will only become
good when the first read request is successfully finished for the tag, which will only
occur when the IO device is online and either background polling is enabled, the tag
has been subscribed to, or a TagRead has been initiated.

You can access these elements by using a qualified tag reference (a tag referenced by the
tag name and the element name, for example ‘MyTag.Field’).. The following tables
describe each of these elements.
Field tag element

CitectSCADA
Reference Syntax Description
Data type

TagName.Field INT Implied value of Field element

REAL
STRING

TagName.Field.V INT Value

REAL
STRING

TagName.Field.VT TIMESTAMP Timestamp of when the value

last changed

TagName.Field.Q QUALITY Quality

TagName.Field.QT TIMESTAMP Timestamp of when the quality

last changed

TagName.Field.T TIMESTAMP Timestamp of when the element

was last updated

Valid tag element

CitectSCADA
Reference Syntax Description
Data type

TagName.Valid INT Implied value of Valid element

REAL
STRING

TagName.Valid.V INT Value

REAL
STRING

TagName.Valid.VT TIMESTAMP Timestamp of when the value

last changed

454
Chapter 16: Tagging Process Variables

CitectSCADA
Reference Syntax Description
Data type

TagName.Valid.Q QUALITY Quality

TagName.Valid.QT TIMESTAMP Timestamp of when the quality

last changed

TagName.Valid.T TIMESTAMP Timestamp of when the element

was last updated

If you determine that the tag value is incorrect because of a sensor or communication
becoming inoperative, the tag value may need to be overridden. The Override tag ele-
ment is used to store the overridden tag value. For further information refer to Con-
trolling and Overriding Tag Values.

Writing Tag Values

The tag elements which have read/write access can be modified. However, these ele-
ments can only be updated as a whole; writes to an individual element item is not
allowed.
The following table shows the result of writing to each of the tag elements:

Element Name Write allowed Write Result

Not specified (unqualified Yes Write to the Field element and propagate
tag reference) the value to the I/O Device.

Field Yes Write to the Field element and propagate

the value to the I/O Device.

Valid No Will not succeed

Override Yes Write to the Override element

Override Mode Yes Write to the Override Mode element.

See the appropriate function references
for the available override mode values.
Note: When the tag is in Override mode,
an unqualified tag reference will refer to
the Override element

Control Mode Yes Write to the Control Mode element

The Value item can be one of the fol-
lowing:
0 – Control inhibit mode is Off.
1 – Control inhibit mode is On.
Note: When Control inhibit mode is On,

455
Chapter 16: Tagging Process Variables

Element Name Write allowed Write Result

writing to the Field element is prohibited.

Tag Status No Will not succeed

If you determine that the tag value is incorrect because of a sensor or communication
interuption, the tag value may need to be overridden. The Override element tag element
is used to store the overridden tag value. For further information refer to Controlling and
Overriding Tag Values.

Controlling and Overriding Tag Values

Tag extensions in CitectSCADA allow you to control the ability of a tag to be written to,
or to override a value read from a tag if it is considered to be incorrect due to some loss
of communication with the PLC.
These functions are managed by setting the tag into Control Inhibit Mode or Override
Mode.

Control Inhibit Mode

PERFORMING A CONTROL OPERATION WHICH DOES NOT IN FACT OCCUR.

When the tag is put into the control inhibit mode, writing to the Field element value is pro-
hibited. If the system is configured in such a way that it does not give the operator any indi-
cation that the tag is in the control inhibit mode, the operator may assume that he is
performing a control operation which does not, in fact, occur.

Configure the system in such a way that it provides a visual indication to the operator that a
tag is in the control inhibit mode.

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

To provide a visual indication to the operator that a tag is in the control inhibit mode
the following can be done:
Set any of the following Citect.ini parameters in such a way that control inhibit mode
will be indicated by changing the background color or overlaying the numeric or text
graphics objects and symbol set objects with a dithered pattern:
[Page]ControlInhibitDitheringColor
[Page]ControlInhibitDitheringDensity
[Page]ControlInhibitTextBackgroundColor
and set [Page]IgnoreValueQuality parameter to a value of 0 or 2.

456
Chapter 16: Tagging Process Variables

or
Use the Control Mode element value (0 if the tag is not in the control inhibit mode or 1
otherwise)
or
Use the Field element quality Tag Status ControlInhibit bit (1 if the tag is in the control
inhibit mode or 0 otherwise)
Control Mode

Control inhibit mode allows you to prohibit writing to the Field tag element. Setting a tag
in Control inhibit mode is applied system wide. Writing to the Field element will be pro-
hibited for each of the I/O Data Consumers.
Control inhibit mode is controlled by the “Control Mode” element which is described in
the following table.

CitectSCADAData
Reference Syntax Description
type

TagName.ControlMode INT Value of Control Mode element

TagName.ControlMode.V INT Value

Allowed values are:
0 – Control inhibit mode is Off.
1 – Control inhibit mode is On.
Default value: 0.

TagName.ControlMode.VT TIMESTAMP Timestamp of when the value last changed

TagName.ControlMode.Q QUALITY Quality. The Control Mode quality is QUAL_

GOOD if the tag was put into the Control
inhibit mode on the primary server and it
was propagated to redundant servers.
Otherwise the general quality status will be
QUAL_UNCR and the extended susbstatus
will be QE_NOT_REPLICATED to indicate
that not every redundant server is aware of
the fact that the tag is in Control inhibit
mode.

TagName.ControlMode.QT TIMESTAMP Timestamp of when the quality last

changed

TagName.ControlMode.T TIMESTAMP Time of when the tag was put in or out of

the Control inhibit mode. (equal to 0 at
start up)

457
Chapter 16: Tagging Process Variables

Note: The quality of tags referenced by items, ex. Tag1.v or Tag1.Field.t, is GOOD
and its timestamps are 0 (INVALID TIMESTAMP). Therefore they give no visual
indication of any not good quality, error or change in handling state such as control
inhibit or override mode regardless of the setting used for the [Page] Ignore-
ValueQuality parameter.

Override Mode

PERFORMING A CONTROL OPERATION BASED ON INACCURATE DATA.

When the tag is put into the override mode, the default tag element value will be equal to
the Override element value instead of the Field element value. If the system is configured in
such a way that it does not give the operator any indication that the tag is in override mode,
the operator may assume that he is seeing the Field element value (live data) and con-
sequently may operate the plant inappropriately.

Configure the system in such a way that it provides a visual indication to the operator that a
tag is in override mode.

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

To provide a visual indication to the operator that a tag is in the override mode the fol-
lowing can be done:
Set any of the following citect.ini parameters in such a way that override mode will be
indicated by changing the background color or overlaying the numeric or text graphics
objects and symbol set objects with a dithered pattern:
[Page]OverrideDitheringColor
[Page]OverrideDitheringDensity
[Page]OverrideTextBackgroundColor`
and set [Page]IgnoreValueQuality parameter to a value of 0 or 2.
or
Use the Override Mode element value (0 if the tag is not in the Override Mode or 1,2,3,4
otherwise)
or
Use the default or override element quality Tag Status Override bit (1 if the tag is in the
override mode or 0 otherwise)
Using Override Mode

458
Chapter 16: Tagging Process Variables

If you determine that the tag value is incorrect because of a sensor or communication
interuption, the tag value may need to be overridden. The Override tag element is used
to store the overridden tag value.
You can put the tag into the Override Mode which will cause each unqualified tag ref-
erence (a tag referenced only by the tag name, for example ‘MyTag’).in every I/O Data
Consumer (Control Client, Trend Server, Alarm server, etc) to return the Override ele-
ment.The quality of the tag will indicate that the tag is in override mode.
Tag override is controlled by the Override and Override Mode tag elements. The Over-
ride element contains the override value and the Override Mode tag element is used to
set the specific override mode.
The following tables describe each of these elements:
Override tag element

CitectSCADA
Reference Syntax Description
Data type

TagName.Override INT Implied value of Override element

REAL
STRING

TagName.Override.V INT Value

REAL
STRING

TagName.Override.VT TIMESTAMP Timestamp of when the value last

changed

TagName.Override.Q QUALITY Quality. The Override value has “Good”

quality except when it is out of range

TagName.Override.QT TIMESTAMP Timestamp of when the quality last

changed

TagName.Override.T TIMESTAMP Timestamp of when the element was

last updated

Note: The quality of tags referenced by items, ex. Tag1.v or Tag1.Field.t, is constantly
GOOD and its timestamps are constantly 0 (INVALID TIMESTAMP). Therefore they
give no visual indication of any not good quality, error or change in handling state
such as control inhibit or override mode regardless of the setting used for the [Page]
IgnoreValueQuality parameter.

Override Mode tag element

459
Chapter 16: Tagging Process Variables

CitectSCADA
Reference Syntax Description
Data type

TagName.OverrideMode INT Value of Override Mode element

TagName.OverrideMode.V INT Override Mode Value. See the appropriate

function references for the available over-
ride mode values.

TagName.OverrideMode.VT TIMESTAMP Timestamp of when the value last changed

TagName.OverrideMode.Q QUALITY The Override Mode quality is QUAL_GOOD if

the tag was put into the Override mode on
the primary server and it was propagated
to any redundant servers. Otherwise the
general quality status will be QUAL_UNCR
and the extended substatus will be QE_
NOT_REPLICATED to indicate that some
redundant servers are unaware of the fact
that the tag has been overridden.

TagName.OverrideMode.QT TIMESTAMP Timestamp of when the quality last

changed

TagName.OverrideMode.T TIMESTAMP Time when the tag was put in or out of Over-
ride mode. (equal to 0 at start up)

Override Modes

Override
Mode Description
Value

0 The Override Mode is Off.

1 The tag is in Static Override Mode and the Override value is initially set to the
value of the tag’s Field element.

2 The tag is in Static Override Mode and the Override value is initially set to the
value of the tag’s Valid element.

3 The tag is in Static Override Mode and the Override will remain at the previously
set value of the tag's Override element.

4 The tag is in the Dynamic Override Mode and the Override value will continually
track the value of the tag's Valid element. The ability to write to the value of the
tag’s Override element is disabled in this mode.

460
Chapter 16: Tagging Process Variables

Tag Status
The Tag Status element is used to represent the current status of the tag. The value of
this element is affected only for those tag operations that involve a physical device (for
example, writing to the Field element will affect the status element, but writing to the
Control Mode will not). Tag Status element is reset after I/O Server restart. The element
value contains a set of bit flags.
The following table describes the Tag Status element:

CitectSCADA
Reference Syntax Description
Data type

TagName.Status INT Value of Tag Status element

TagName.Status.V INT Value

A set of bit flags representing
the following data:
- 0x1: Read Pending.
- 0x2: Write Pending.
- 0x4: Write Successful.
- 0x8: Write Unsuccessful.
Default value: 0.

TagName. Status.VT TIMESTAMP Timestamp of when the value

last changed

TagName.Status.Q QUALITY Quality

TagName.Status.QT TIMESTAMP Timestamp of when the quality

last changed

TagName.Status.T TIMESTAMP Timestamp of when the element

was last updated

461
Chapter 16: Tagging Process Variables

462
Chapter 17: Linking, Importing, and Exporting Tags

Because I/O Devices are often programmed independently of CitectSCADA, you can
import, or link to, every the tag in an external data source. This means that you only
have to define tag information once when you program your I/O Devices. You do not
have to re-enter the same information again in CitectSCADA. Because the necessary infor-
mation is already saved in an external data source, you can just import it or link to it.
There are two types of tags in the CitectSCADA variable database - linked tags and non-
linked tags. When performing a tag import from Citect Explorer, only non-linked tags are
updated. Linked tags remain unchanged. When performing a refresh or auto-refresh,
only linked tags are updated. Non-linked tags remain unchanged. When performing a
synchronization (Live Update), every tag for the I/O device are updated and linked.
CitectSCADA also lets you export tags to an external file, specifying the destination and
format of your choice. You might then import this file into a third-party I/O Device pro-
gramming package database, or simply use it as a backup.

Note: The simultaneous update of a tag name and its fields is only supported when
importing via OFS. In every other case, if you attempt to simultaneously update a
tag's name and fields, only the name will be updated. In this case update a tag name
in a separate operation from updating its fields.

See Also
Linking tags
Importing tags
Exporting tags
Unity Support Matrixes

Linking tags
Linking is an I/O Device specific operation. When you add an I/O Device record in Citect-
SCADA (using the Express Communications Wizard), you can choose to link it to an
external data source. The external data source is where the tag data was saved when the
actual I/O Device was programmed. If you link to the external data source, CitectSCADA
automatically creates variable tag records for every tag in the I/O Device.

463
Chapter 17: Linking, Importing, and Exporting Tags

These variable tag records are dynamically linked to the tags in the external data source.
CitectSCADA is updated whenever one of the external tags is changed. For example, you
might program your I/O Devices, configure your project, then add some new tags or edit
existing tags. In this situation, CitectSCADA is automatically updated with your
changes.
This update occurs when you attempt to read the changed tags in CitectSCADA (for
example you compile your project, display the tag using the Variable Tags dialog box,
modify or paste the tag, or perform a manual refresh, etc.). For example, if you change
the address of a tag using a third party I/O Device programming package, the external
data source is changed. Then, when you display the variable tag record or compile your
project in CitectSCADA, the change is copied from the external database to Citect-
SCADA's variable tags database.
You can tell if a tag is linked because the status line at the bottom of the Variable Tags
form will read Linked: Yes. If it is linked and you change a field, your change will not
be overwritten when the link is next refreshed. Generally, however, any field which takes
its value from the external data source is disabled.

Note: Some properties defined for the external tags will not be relevant to Citect-
SCADA. Also, some will not be in a format that CitectSCADA can read. Each I/O
Device has an associated format file in CitectSCADA. It is this file that determines
what information is copied to CitectSCADA's variable tags database and how this
information is to be converted. In most cases, you will not have to edit this file.

Note the following for Citect tags linked to Unity tags:

1. The addition of a new tag on either side, will result in the addition of a new tag on
the other side.
2. The deletion of an existing tag on either side, will result in the deletion of the cor-
responding tag on the other side.
3. The modification of an existing tag on either side, will result in the modification of
the corresponding tag on the other side.
4. The delete operation in either Unity or Citect will take precedence over other oper-
ations (such as modify).
5. If there is some contention between the Unity database and the Citect database for the
same tag, that is modifications are done from both databases at the same time, the
Unity database item will take precedence over the Citect database item.
6. The linked I/O Device live update synchronization will be triggered in the following
cases:
1. Unity configuration update.

464
Chapter 17: Linking, Importing, and Exporting Tags

2. Citect configuration update.

3. Manual refresh.
See Linked Tags for information about levels of support between Unity and Citect-
SCADA.

Breaking the link to the external data source

You can break the link to the external data source from the I/O Devices form or through
the Express Communications Wizard. If you break the link, you can choose to make a
local copy of the tags or you can simply delete them altogether.

Deleting the I/O Device

If you delete an I/O Device record which is marked as linked, you can choose to make a
local copy of the linked tags or you can simply delete them.
To link to tags in an external data source:

1. Start the Project Editor.

2. Choose Communication | I/O Devices.
3. Scroll to the relevant I/O Device and choose Linked | True.
4. Complete the remaining fields as necessary.
To link to tags in an external data source using the Express Communications Wizard:

1. Start the Project Editor and choose Communication | Express Wizard. (Alternatively,
you can open Citect Explorer, and then click Express I/O Device Setup in the Com-
munications folder of the current project.)
2. Complete the wizard screens one by one, selecting the relevant I/O Device, and so on.
When the Link to External Database screen appears, select the Link I/O Device to an
external tag database check box and complete the remaining details.
To manually refresh linked tags:

1. Open Citect Explorer.

2. Choose Tools | Refresh Linked Tags to display the Refresh Linked Tags dialog
box.
See Also
Refresh Linked Tags properties
Importing tags

Refresh Linked Tags properties

Use this dialog to refresh linked tags. The dialog has the following field:

465
Chapter 17: Linking, Importing, and Exporting Tags

Select Linked I/O Devices

Every linked I/O Device in your project (and included projects) are listed here. To refresh
the tags for an I/O Device, click the I/O Device, then click Refresh. This updates your
project with the latest tag values for the selected I/O Device.
If you use CitectSCADA to modify any I/O Device tags, your modifications will not be
overwritten on refresh.

Importing tags
Importing tags from an external data source lets you halve your data entry time. Instead
of entering your tag information once when you program your I/O Device and once
when you configure your project, you can program your I/O Device, then import the tags
straight into CitectSCADA, where they are treated as regular tags. (CitectSCADA auto-
matically creates variable tag records for every tag in the I/O Device.)

Note:CitectSCADA only supports the use of alphanumeric characters, the backslash

and underscore characters (see Tag name syntax). Any other characters will be con-
verted to underscores on import. This may result in Duplicate Tag errors on com-
pilation.

Like linking, the importing of tags is an I/O Device specific operation: you import the
tags for a particular I/O Device. Unlike linking, however, imported tag records are not
linked in any way to the tags in the external data source. Therefore, importing is typ-
ically a one-time operation. To update imported tags, you need to import them again.

Note: Tags will be imported into the project in which the selected I/O Device is
defined. This could be either the project selected in the Explorer, or in one of its
included projects.

For most external data sources, the import process involves two steps. First you export
the data from the I/O Device to a format that CitectSCADA can read, then you import the
database into CitectSCADA. However, tag data saved using Mitsubishi or Unity Fast-
Linx can be read directly by CitectSCADA. This means that no export is necessary.
Some characteristics of the import are defined in the format files in the Config directory
(with the extension .fmt). There is one format file for each database type, and each file
specifies how external data is converted to CitectSCADA variable data. In general,
imported tags are either added to the CitectSCADA variable database if the tag does not
already exist, or updated if the tag exists. However, if a field is listed in the [Edi-
tableFields] section of the format file corresponding to the import database type:

466
Chapter 17: Linking, Importing, and Exporting Tags

l If the tag already exists, the CitectSCADA field for the tag will not be updated with
the external value.
l If the tag does not yet exist, the CitectSCADA field for the tag will be updated with
the external value.
For example, if a tag has 10 fields to be imported and 5 of them are listed in the [Edi-
tableFields] section of the format file, then if the tag already exists in CitectSCADA the
tag will be updated with the external values for the 5 fields that are listed in [Edi-
tableFields]. If the tag does not already exist then the tag will be created with the external
values for every 10 fields.
Fields marked as editable in this way can be changed by CitectSCADA. To prevent inter-
nal changes being lost, changes to these fields in the external database are ignored.

Note: If the external database supports to LiveUpdate and the LiveUpdate Link has
been selected for the I/O Device, existing CitectSCADA tags will be synchronized
with the external database and the tags will be updated for the imported fields
regardless of whether it is marked as an editable field. An I/O Device configured as
Linked or Auto-refreshed Linked will behave as in a normal import and will not
update fields marked as editable.

When you import tags into CitectSCADA, you have two options for dealing with existing
tags:
l Delete tags associated with that I/O Device prior to the import.
l Update existing tags on import. Tags found in CitectSCADA and in the external data
source are updated in CitectSCADA. Tags found in CitectSCADA but not in the exter-
nal data source will remain untouched. New tags are appended.
If you import a data source that is already linked, every tag in the data source are dupli-
cated. That is, you will have two copies of each tag: one local and one linked.
See Imported Tags for information about levels of support between Unity and Citect-
SCADA.
Some properties defined for the external tags will not be relevant to CitectSCADA. Also,
some will not be in a format that CitectSCADA can read. To define what information is
copied to CitectSCADA's variable tags database and how this information is to be con-
verted, you need to edit the I/O Device's format file.
To import variable tags from an external database:

1. Open Citect Explorer.

2. Choose Tools | Import Tags.
3. Complete the Import Variable Tags dialog box as necessary.

467
Chapter 17: Linking, Importing, and Exporting Tags

See Also
Import variable tags properties

Import variable tags properties

Use this dialog for Importing tags from an external data source.

Note: If an I/O Device is linked to an external data source the Database Type, Exter-
nal Database, Connection String, and Tag Prefix fields will be greyed out.

The Import Variable Tags dialog has the following fields:

I/O Device
The I/O Device for which you are importing tags. Use the menu to select an I/O Device
that has been defined using CitectSCADA.

Note: Tags will be imported into the project in which the selected I/O Device is
defined. This could be either the project selected in the Explorer, or in one of its
included projects.

Database type
The format of the data referenced by the external data source.
External database (128 Chars.)
References the source for the external database. Click the Browse button to either navi-
gate to the file or to specify configuration options. The external database can be:
l An explicit path and file (for example, C:\Data\Tags.csv)
l An IP address and node (for example, 127.0.0.1\HMI_Scada)
l A URL (for example http://www.abicom.com.au/main/scada)
l A computer name (for example \\coms\data\scada)
Tag data can be read directly from a Unity SpeedLink or OPC Factory Server data-
sources. Click the browse button to specify configuration options. See OPC Factory Server
Tag Import or Unity Link Tag Import.
Connection string (128 Chars.)
Connection details for the data source. This is similar to an ODBC connection string. For
example:

UserID = XXX; Password = YYY

468
Chapter 17: Linking, Importing, and Exporting Tags

ServerNode=111.2.3.44; Branch=XXX

Only certain drivers require a connection string:

l Mitsubishi FastLinx
l Unity Fastlinx (Static/Dynamic)Unity SpeedLink (Static/Dynamic)
l OPC
Selecting one of these drivers and then browsing for the external database will auto-
matically populate the Connection String field where necessary.
Add prefix to imported tags
Select this box to insert a prefix in front of the names of imported tags in your
Variable.DBF.
Tag prefix
The prefix (8 characters max.) that is inserted in front of the names of imported tags in
the variable tags database.
Delete I/O Device tags prior to import
Select this box to delete every one of the I/O Device's tags (from the variable tags data-
base) before importing.
If you do not select this checkbox, tags found in CitectSCADA and in the external data
source are updated in CitectSCADA. Tags found in CitectSCADA but not in the external
data source remain untouched. New tags are appended.
Purge deleted tags not found in data source
Select this box to delete tags which have been removed from the external database. In
other words, if a tag is still part of the I/O Device in your project, but not in the external
database, it is deleted from your project.

FastLinx for Mitsubishi Tag Import

Use the CitectSCADA FastLinx tag browser to:
l Browse the available Mitsubishi servers on your network.
l Generate the connection strings and server parameters that the Fastlinx database
driver requires in CitectSCADA.
The FastLinx tag browser has the following fields:
Database tree display

469
Chapter 17: Linking, Importing, and Exporting Tags

Shows a hierarchical display of the MxChange servers (both local and networked), their
Fastlinx databases, and associated nodes. To expand or collapse a tree entry, click the
add [+] or minus [-] symbol, respectively, to the left of the entry.
When you open the browser, the information displayed depends on whether or not there
is an existing FastLinx database with the same name as the current CitectSCADA
project:
l If an FastLinx database exists with the same name as the CitectSCADA project and
the database contains a GID node with the same name as the CitectSCADA I/O
Device, the browse dialog highlights the GID node of that name. You can then click
Open to generate connection strings or server parameters.
l If no FastLinx database exists with the same name as the CitectSCADA project, the
Create a new database node is highlighted. Click Open to generate the connection
strings, or click the highlighted node to create a new database.
Server
Displays the server name on which the database, if present, exists. If no database is
found, this box displays defaults to the name of the local PC. (Read-only)
Database
Displays the database name (i.e., name of the current CitectSCADA project). (Read-only)
IO Device
Displays the name of the GID node (i.e., CitectSCADA I/O Device). (Read-only)
PLC Class
Indicates the type of project configured in the MxChange server.
PLC Type
Indicates the PLC type corresponding to the selected PLC class.
Password
Enter the password for the selected database to allow CitectSCADA to access the data-
base for data retrieval. The password needs to be valid for read/write access as assigned
by your database administrator.
See Also
Defining Variable Tag Names for Mitsubishi FastLinx

Defining Variable Tag Names for Mitsubishi FastLinx

Note: The functionality described in this topic relates only to FastLinx for Mitsubishi.

470
Chapter 17: Linking, Importing, and Exporting Tags

You need to have purchased an appropriate CitectSCADA license for this func-
tionality to be supported.

If you are using Mitsubishi FastLinx, you cannot use certain reserved words when defin-
ing your tag name variables. You cannot use:

471
Chapter 17: Linking, Importing, and Exporting Tags

l Reserved words such as:

& * ** -

/ + < <=

>= <> = >

ACTION AND ANY_NUM ARRAY

BOOL CASE CON- CON-

FIGURATION STANT

DATE DATE DINT DO

DUT DWORD ELSE EN

END_ END_CON- END_FOR END_IF

CASE FIGURATION

END_PRO- END_VAR END_WHILE ENO

GRAM

EXIT FALSE FOR FUNCTION

IF INT INT MOD

NOT OF OR PROGRAM

REAL REPEAT STRING STRING

TASK TIME TIME TO

TRUE TRUE UNTIL VAR_

EXTERNAL

VAR_ VAR_IN_OUT VAR_INPUT VAR_OUT-

GLOBAL PUT

WHILE WORD XOR

l Cicode function names. See Functions Reference for a complete list of Cicode func-
tions.
Using reserved words or Cicode function names may cause a syntax error in Mitsubishi
FastLinx when you export tags to the FastLinx tag name database.

472
Chapter 17: Linking, Importing, and Exporting Tags

See Also
FastLinx for Mitsubishi Tag Import

Unity Link Tag Import

The Unity Link Configuration dialog specifies the parameters used to generate alarm
and trend tags. It has the following fields:
I/O Device & Protocol Driver
The name of the destination I/O Device and its corresponding protocol. Unity
SpeedLinkFastLinx will only import tags to an I/O Device using either the MODBUS,
MODNET, MBPLUS, or UNITE.
Unity Database Type
The import/export database driver type selected from the Import Variable Tags dialog.
PLC Family
The family name of the PLC you are importing from. It can be either Premium or Quan-
tum. This option is only valid for the Unity SpeedLinkFastLinx Static protocol.
Unity File
Path of the Unity project file from which you want to import the tags. If the database
type is Unity SpeedLinkFastLinx Dynamic, this is a *.stu file. If the database type is
Unity SpeedLinkFastLinx Static, this is a *.xsy file.
Unity Profile Enable
Enable this if the Unity database is restricted by user profile and a user name and pass-
word combination are needed to gain access. See the Access Security Management sec-
tion of the Unity Pro online help for further information.
Unity Username and Password
The username and password, if it is necessary, for the Unity database from which you
are importing.
DCOM Enable
Enable this if the database host is a DCOM server.
DCOM Server Name
If enabled, the DCOM server that the client uses to hosts the database from which you
are extracting tags.
DCOM Username and Password
If enabled, the username and password for the DCOM server.
Log File Path
The path name for log files generated during the import or export process.
Logging Level
The level of detail necessary in the import or export logs.

473
Chapter 17: Linking, Importing, and Exporting Tags

Log Pool Size

Specifies the maximum number of log files for the given device.
Validate
Click the validate button to check the Unity Link settings are correct. This button enables
the OK button on the page.

Additional Tag Generation Configuration

This dialog specifies the path of the XML template, the parameters specified in the tem-
plate, and displays the template description (extracted from the desc attributes used in
the template).
1. Click Browse to select the XML file to use.
2. Double click on a parameter in the parameters list to change its value.
3. Click OK to save this template into your project. The template will be copied into the
project and, when validated, saved with a taggen_import_ioDeviceName.xml or taggen_
link_ioDeviceName.xml filename.

Note: When you return to this dialog, the pathname will point to the location of
the template in the project, rather than the path of the original template file.

OPC Data Access Server Tag Browser

The OPC Data Access Server Tag Browser dialog generates the strings that the OPC Data
Access Server database driver requires in CitectSCADA.
The OPC Data Access Server Tag Browser dialog has the following fields:
Machine Name
The location of the OPC Server which can be an IP address or the network path server.
Leave blank to select the local machine.
Database tree display
Displays the Servers on the network that are running the OPC Server application, and
the hierarchical database node structure for each.
Select a group of tags to import from an available database. OPC data can be either a
tree (hierarchical) or a flat structure. The CitectSCADA OPC driver supports access to
both types of storage. If the data is in a tree structure, it can be accessed to the first
branch level down from the root node. Deeper levels of branching may be supported in
the future.

474
Chapter 17: Linking, Importing, and Exporting Tags

Note: The authentication values needs to be valid for read/write access, as assigned
by the appropriate database administrator.

OPC Factory Server (OFS) Tag Import

Vijeo Citect can now import tags from the OPC Factory Server. For Database Type,
choose the "Unity SpeedLink via OFS" option and then click the Browse button to specify
the location of the database. In the OPC Data Access Server Parameters dialog that is dis-
played, you can browse the OFS servers installed on the PC and select tags to be
imported into Vijeo Citect.
There are some limitations and things be aware of when importing tags from OFS. See
OFS Tag Import Limitations for more information.

Note: There are two modes that can be used on the OPC Factory Server when import-
ing tags; device mode and OFS simulator mode. If device mode is used, the time
taken to import tags is increased significantly. This is because for each tag requested
by Vijeo Citect the OPC Factory Server needs to verify the item from the device. OFS
simulator mode is highly recommended to avoid these performance issues.

Machine Name
The location of the OPC Factory Server which can be an IP address or a UNC path.
Leave blank to select the local machine.
Select server and branch to Import
Displays the OPC Factory Servers on the network that are running the OPC Factory
Server application, and the hierarchical database node structure for each.
Select a group of tags to import from an available database. OPC data can be either a
tree (hierarchical) or a flat structure. The Vijeo Citect OPC driver supports access to both
types of storage. If the data is in a tree structure, it can be accessed to the first branch
level down from the root node. Deeper levels of branching may be supported in the
future.

Note: The authentication values needs to be valid for read/write access, as assigned
by the appropriate database administrator.

Tag Gen Configuration Enable

Enable this to automatically generate tags from the variable Tags database. Tags are
created using rules specified in the XML template file.

475
Chapter 17: Linking, Importing, and Exporting Tags

Configured template is saved as

Filename of the Tag Gen XML Template file that specifies the rules for generating tags.
Click Configure to select and configure the XML file. See Additional Tag Generation Con-
figuration.
Log File Path
The path name for log files generated during the import or export process.
Log Level
The level of detail necessary in the import or export logs.
Log Pool Size
Specifies the maximum number of log files for the given device.

OPC Factory Server (OFS) Tag Import Limitations

Note:When using a UnityPro project file as a symbol file on Windows 7, it is nec-

essary to execute OFS with the option 'Run As Admin' enabled.

Please be aware of the following limitations when importing tags from an OFS database.
l For each imported tag, the CitectSCADA tag name will be the same as the name of
the tag defined on the OFS except "." characters will be replaced by "_" characters.
l Using OFS tag import to import tags from an OFS database may not succeed on Win-
dows Vista if User Account Control (UAC) is enabled. UAC prevents access to the
external database. If importing via OFS on Windows Vista, either turn off UAC, or
right click on the OFS and Unity Pro Windows shortcuts and select "Run as Admin-
istrator".
l To generate Alarm and Trend tags, a unique identifier can be set in the Custom and
Comment field for Elementary Data Type (EDT) tags. For example, the string "VJA" is
used to identify a tag that the user wants to use to generate a corresponding Digital
Alarm Tag. Only the Comment field can be used for this feature on Derived Data
Types (DDT) and Derived Function Block (DFB) tags.
l OFS built-in tags are not imported. They can be added in CitectSCADA manually.
l The length of the comment field in the CitectSCADA tag form is limited to 48
chaacters.
l CitectSCADA does not support DDT or DFB structure types. The OFS import will enu-
merate each element of this type of tag and import them as elementary tags.
l OFS tag import is only supported when the OFS links to the .STU and .XVM files.

476
Chapter 17: Linking, Importing, and Exporting Tags

l DFB components of type "ANY_ARRAY_xxxx" are not imported when the OFS links
to a *.xvm file. When a data dictionary is used, the data dictionary ignores comment
and custom fields and therefore taggen cannot generate alarm and trend tags. If there
are DFB components of type "ANY_ARRAY_xxxx", the whole DFB is not imported.
l The following table shows data types supported by the tag import and TagGen when
the OFS links to *.stu or *.xvm file.

OFS links to *.xvm

OFS links to *.stu file
file

Tag Gen Tag Gen

Tag Tag
Comment
Import Comment Import
Data Types Custom Field Field
Field
Only

Elementary Data Types

(EDT)

BOOL Yes Yes Yes Yes Yes

EBOOL Yes Yes Yes Yes Yes

BYTE Yes Yes Yes Yes Yes

INT Yes Yes Yes Yes Yes

DINT Yes Yes Yes Yes Yes

WORD Yes Yes Yes Yes Yes

DWORD Yes Yes Yes Yes Yes

UINT Yes Yes Yes Yes Yes

UDINT Yes Yes Yes Yes Yes

REAL Yes Yes Yes Yes Yes

STRING Yes Yes Yes Yes Yes

DATE Yes Yes Yes Yes Yes

DT Yes Yes Yes Yes Yes

TIME Yes Yes Yes Yes Yes

TOD Yes Yes Yes Yes Yes

Derived Data Types

(DDT)

EDT in DDT Yes Yes 2 No Yes Yes 3

477
Chapter 17: Linking, Importing, and Exporting Tags

OFS links to *.xvm

OFS links to *.stu file
file

Tag Gen Tag Gen

Tag Tag
Comment
Import Comment Import
Data Types Custom Field Field
Field
Only

Array in DDT Yes Yes 2 No Yes No

Arrays

Array of EDT 4 Yes Yes No Yes No

Array of DDT 4 No No No Yes Yes 1

Function Block Types

(FBT)

Elementary Function Block Yes Yes 2 No Yes Yes 3

(EFB)

Derived Function Block Yes Yes 2 No Yes Yes 3

(DFB)

Synchronization

Live Update No No No No No

Automatic Refresh of tags No No No No No

1. Only the BOOL type tags in the DDT can be used to generate Alarm and Trend tags
when the OFS links to the *.xvm file.
2. When OFS links to the stu file, the comment string defined in the tag instance will be
taken, the comment string defined in the DDT/DFB definition will be ignored.
3. When OFS links to the xvm file, the comment string defined in the DDT/DFB def-
inition will be taken and the comment defined in the tag instance will be ignored.
4. Array with negative index is not supported.

TagGen XML Template

The TagGen template is an XML file that uses proprietary tags and attributes to specify
the fields of input and output databases, and define filters and transformation rules that
create tags from existing database fields.
The basic structure of the XML file is as follows:

478
Chapter 17: Linking, Importing, and Exporting Tags

<?xml version="1.0"?>
<template>
<param name="parameter">
</param>
<input name="variable" file="variable.dbf">
</input>
<output name="trend" file="trend.dbf" filter="">
</output>
</template>

This outline template specifies no parameters, takes input from the variable.dbf database
and outputs the results to the trend.dbf database. The <template> tag is the root tag of the
template document and need to be present.
Within the <template> tag are three sections:
l <param>

This is an optional section you can use to specify string constants that can be referred to
in other sections of the template. For example:

In this example the variable MyIODevice is given the value DISK_PLC.

The <param> tag has a name attribute. You can use any name provided that it uniquely
identifies the section within the XML file. This section name is used when referring to
variables from other sections of the file. See Referencing variables.
Strings defined here are displayed in the Additional Tag Generation Configuration
dialog when templates are selected. It is possible to define strings that are otherwise not
used in the template to specify version or revision information in order to track template
modifications.
l <input>

The <input> section specifies the name of the database and the fields that are used for
processing into tags. There needs to be only one input section in the XML file. For exam-
ple:

<input name="variable" file="variable.dbf">

<field name="name"></field>
<field name="type"></field>
<field name="unit" load="true">{parameter.IODevice}</field>
<field name="custom"></field>
<array name="taginfo">{ToProperty('{custom}', '=', ';')}</
array>
<string name="alarminfo">{variable.taginfo[VJA]}</string>
<string name="trendinfo">{variable.taginfo[VJT]}</string>

479
Chapter 17: Linking, Importing, and Exporting Tags

</input>

This example identifies four fields from the variable.dbf database: name, type, unit and
custom. These fields are used later in the file. The input section loads only rows where
the unit field matches the value of the IODevice variable in the parameter section. This
helps improve performance by avoiding the processing of irrelevant rows.
An array is created called taginfo that contains key value pairs based on the value of the
custom field. If the custom field value was "VJA=Alarm;VJT=Trend", then an array is
created containing the values taginfo[VJA] = "Alarm" and taginfo[VJT] = "Trend".
Two string variables are created based on the values of the taginfo array.
l <output>

The <output> section defines the output database, the processing to be done on the input
fields and the respective output fields to be generated. There can be many output sec-
tions in the XML file. The output section can specify the same database file as the input
section if necessary. For example:

<output name="digalm" file="digalm.dbf"

filter="'{variable.alarminfo}=VJA' AND
'{variable.type}=DIGITAL'">
<field name="tag">{variable.name}_ALARM</field>
<field name="name">{variable.name}_ALARM</field>
<field name="var_a" key="true">{variable.name}</field>
<field name="taggenlink" load="true">{parameter.IODevice}</
field>
</output>

In this example, fields are written to the digalm.dbf database. Output processing only
occurs for the current row if the input row relates to a digital alarm. That is, if the alarm-
info variable from the input section has the value of "VJA" and the type field from the
input database is "DIGITAL. The tag and name fields are given the value name_ALARM.
Curly braces are usually used for substitutions to replace pre-defined texts with tag prop-
erties. To use curly brace characters as normal characters, use double curly braces which
will be exceptionally converted to singular ones to express curly braces. Round brackets
are not regarded as special characters when used in tags other than <calculator> tag.
Example

<output name="digalm" file="digalm.dbf" filter=" ( '{variable.alarminfo1}=VJA' OR '

{variable.alarminfo2}=VJA' ) AND '{variable.type}=DIGITAL'" desc="Generate digital
alarm tags from input digital variable tags">

<field name="tag">{variable.name}_ALARM</field>

480
Chapter 17: Linking, Importing, and Exporting Tags

<field name="name">{variable.name}_ALARM</field>

<field name="var_a" key="true">{variable.name}</field>

<field name="taggenlink" load="true">{parameter.IODevice}</field>

<field name="comment">{{Testing1}}</field>

</output>

Proprietary tags used in the template are described in XML template tags. See Sample
XML Templates for more comprehensive examples.

Referencing variables
Variables can be used to temporarily store information. Variables can be defined either
globally in the <param> section of the XML file or locally in an <input> or <output> section.

Variables are defined using the <string> tag as shown in XML template tags. For exam-
ple:

To refer to a variable, use the following syntax:

{SectionName.VariableName}

and for this example:

{parameters.MyIODevice}

The SectionName can be omitted if you are referencing a variable defined in the same sec-
tion.
Variables are evaluated sequentially in the XML file. Variables in the <param> section are
assigned first, followed by those in the <input> section, followed by variables in each <out-
put> section in sequence. This means that:

l Variables in the <param> section can be referenced by the <input> section and every
<output>section in the same template.
l Variables in the <input> section can be referenced by every <output> section.

481
Chapter 17: Linking, Importing, and Exporting Tags

l Variables in each <output> section can only be referenced by subsequent <output> sec-
tions.

Referencing arrays
To reference a member of an array by member name use:

{SectionName.ArrayName[MemberName]}

To reference a member of an array by matching a pattern use:

{SectionName.ArrayName(PatternString)}

See Pattern matching for information on pattern matching wildcards.

XML template tags

The proprietary tags used in TagGen XML files are listed below.

This is the root tag in the XML file. Only have one <template> tag in each XML file.
Can contain:
<param>, <input>, <output>

Attributes:
desc
Description of the template section.

<param>

This optional tag defines global parameters for the XML file. Here you can specify string
constants to be used in the rest of the file.
Can contain:
<string>

Attributes:
name
Name of the parameter section.
desc
Description of the parameter section.

<input>

This defines the source database of the XML file, the fields to be imported and any input
filtering that might be necessary. There needs to be only one input section defined.

482
Chapter 17: Linking, Importing, and Exporting Tags

Can contain:
<field>, <string>, <array>, <calculator>

Attributes:
name
Name of the input section.
file
Input database file name.
desc
Description of the input section.

This defines the output database of the XML file, the tags to be generated and any trans-
formations necessary to generate tag data from input variable data. A template needs to
have at least one output section defined.
Can contain:
<field>, <string>, <array>, <calculator>

Attributes:
name
Name of an output section
file
Output database file name
filter
Output section filter, syntax:
filter="variable=FilterString "

<FilterString> is a string expression that can combine wildcards or wildcard

strings with boolean operators (AND, OR and NOT), as well as grouped
boolean terms using parentheses. For example, "L*" will match if string
beginning with the letter "L"; "L* OR H*" will match if string beginning
with "L" or "H". See Pattern matching for a list of wildcard operators.
desc
Description of the output section.

<field>

This tag specifies the database fields that will be processed in <input> and <output> sec-
tions.
When used in the input section it specifies the named fields for each record loaded from
the input database. It is read only.

483
Chapter 17: Linking, Importing, and Exporting Tags

When used in an output section it specifies the named fields to write to for each gen-
erated tag record in the output database.
Attributes:
name
Case insensitive name of a database field.
key
Valid for output sections only, this boolean flag indicates whether this is a key field.
This is useful for special handling in the output section. For example, you can syn-
chronize between a new record set and an old record set by matching the key fields.
load
Valid for both input and output sections, this boolean flag indicates whether this is a
load filter field. Load filter fields are used to filter records when loading data from the
input database and output database.
desc
Description of the field element.

Note: Key and Load string expressions can contain a regular string, a variable ref-
erence, wild card operators, or a mixture of these. See Pattern matching for a list of
wildcard operators.

This tag defines a string constant that can be used in <param>, <input> and <output> sec-
tions.
Attributes:
name
Name of a variable string.
desc
Description of the string element.

Note: For Unity SpeedLink, the string "IODevice", when defined in the <param> sec-
tion, refers to the project's IO Device. Do not assign it another value.

<array>

This tag defines a dynamic array of strings in <input> and <output> sections.
The set of strings depends on the fields of the record being processed and those strings
that are generated by the ToProperty() and Split() commands. See Built-In Functions for
more information.
Attributes:

484
Chapter 17: Linking, Importing, and Exporting Tags

name
Name of a variable string array.
desc
Description of the array element.

This tag defines an expression variable in <input> and <output> sections.

The content of this tag is a mathematical expression used to specify a simple operation
for data transformation.
The operands in the expression can be only numbers or variables with numeric values.
The expression can use parentheses to change the precedence of the evaluation.
For example, the following calculator in an <input> section counts input records by incre-
menting its current value.

<calculator name="c1" initial="0">{c1} + 1</calculator>

Attributes:
name
Name of a calculator.
initial
Initial value of the calculator, zero by default.
desc
Description of the calculator element.

Pattern matching
The following wildcards can be used in strings

Character Description

* Matches any string in the input data stream

? Matches any single character in the data stream

%d Matches any decimal integer (nnn... where n is 0-9) in the data stream

%e Matches any octal number (0onnn... where n is 0-7) in the data stream

%h Matches any hexadecimal number (0xnnn... where n is 0-9, A-F or a-f) in

the data stream

485
Chapter 17: Linking, Importing, and Exporting Tags

%s Matches any string in the data stream (same as *)

{ Begin a token string. The characters between { and } in the Input Pattern
(including regular and special characters) represent a "token string".
The characters in the data stream that match this token string are a
token, and can be referenced by the Output Data String, and written
directly to the output database as a group

} End of a token string

\ Treat the following character as a literal. For example, if a literal `*' char-
acter was expected in the input data stream, you would use \* to denote
this. If a literal backslash \ is expected, use \\.

Built-In Functions
There are three built-in functions that can be used to manipulate strings in the XML tem-
plate. The syntax to call a built-in function as follows:

{<FunctionName>(<arg1>, <arg2>,...)}

The three built-in functions are:

SubString(string, start, count)
This function extracts a substring from the given source string starting at character start
and ending after count characters.
Split(string, delimiter)
This function splits the source string into parts separated by the delimiter and stores
them in a zero based string array. For example:

<array name="tagid">
{split('VJA;VJT', ';')}
</array>

produces tagid[0] = VJA, tagid[1] = VJT.

ToProperty(string, separator, delimiter)
This function splits the source string parts separated by the delimiter, and then further
into key value pairs separated by the separator. For example:

<array name="taginfo">
{ToProperty('VJA=Alarm;VJT=Trend', '=', ';')}
</array>

produces taginfo[VJA] = Alarm, taginfo[VJT] = Trend.

486
Chapter 17: Linking, Importing, and Exporting Tags

Sample XML Templates

A sample template is provided to create analog or digital alarm tags and trend tags. The
template shown below specifies the rules for generating Vijeo Citect Alarm and Trend
tags from a Unity SpeedLink device/database, for the import and/or Synchronization of
Variable Tags.

Note: You will need to modify this template to suit your particular requirements.
Refer to TagGen XML Template for more information.

For each Unity Database variable tag with the text "VJA" in the custom field imported in
to Vijeo Citect of type "DIGITAL", this file will generate a linked Digital Alarm Tag
within Vijeo Citect (digalm.dbf) with the name <variablename>_ALARM.
For each Unity Database variable tag with the text "VJA" in the custom field imported in
to Vijeo Citect not of type "DIGITAL" and not of type "STRING", this file will generate a
linked Analogue Alarm Tag within Vijeo Citect (anaalm.dbf) with the name <var-
iablename>_ALARM.
For each Unity Database variable tag with the text "VJT" in the custom field imported in
to Vijeo Citect, this file will generate a linked Trend Tag within Vijeo Citect (trend.dbf)
with the name <variablename>_TREND. This example file does not enter values for any
of the other Trend tag properties.

<?xml version="1.0"?>
<template desc="Default SpeedLink Unity Pro TagGen template">

<input name="variable" file="variable.dbf" desc="Load variable tags for the spec-

ified I/
O Device">
<field name="name"></field>
<field name="type"></field>
<field name="unit" load="true">{parameter.IODevice}</field>
<field name="custom"></field>

<array name="taginfo">{ToProperty('{custom}', '=', ';')}</array>

<string name="alarminfo">{variable.taginfo[VJA]}</string>
<string name="trendinfo">{variable.taginfo[VJT]}</string>
</input>

<output name="digalm" file="digalm.dbf" filter="'{variable.alarminfo}=VJA' AND

'{variable.type}=DIGITAL'" desc="Generate digital alarm tags from input digital

487
Chapter 17: Linking, Importing, and Exporting Tags

variable
tags">
<field name="tag">{variable.name}_ALARM</field>
<field name="name">{variable.name}_ALARM</field>
<field name="var_a" key="true">{variable.name}</field>
<field name="taggenlink" load="true">{parameter.IODevice}</field>
</output>

<output name="anaalm" file="anaalm.dbf" filter="'{variable.alarminfo}=VJA' AND

'{variable.type}=NOT DIGITAL' AND '{variable.type}=NOT STRING'" desc="Generate
analog
alarms from input analog variable tags">
<field name="tag">{variable.name}_ALARM</field>
<field name="name">{variable.name}_ALARM</field>
<field name="var" key="true">{variable.name}</field>
<field name="taggenlink" load="true">{parameter.IODevice}</field>
</output>

<output name="trend" file="trend.dbf" filter="'{variable.trendinfo}=VJT'"

desc="Generate trend tags from input variable tags">
<field name="name">{variable.name}_TREND</field>
<field name="expr" key="true">{variable.name}</field>
<field name="taggenlink" load="true">{parameter.IODevice}</field>
</output>

</template>

Simple Wildcard Example

The following example shows how an empty string variable called "wildcard" can be
used as a wildcard pattern to load a set of data from a variable database. The string var-
iable is substituted for a "* " wildcard character when the xml file is processed. The
example below loads data where the names of variable tags contain the word "Tank".

<input name="variable" file="variable.dbf">

<string name="wildcard"></string>

<field name="name" load="true">{wildcard}Tank{wildcard}</field>
<field name="unit"></field>
<field name="custom"></field>
</input>

Sample Analog Alarm Example

The following example specifies the rules for generating Vijeo Citect Analog Alarm Tags
and setting the high-high limit attribute, based on the engineering scale of the linked var-
iable Tag.
For each Unity Database variable tag with the text "VJA" in the custom field imported in
to Vijeo Citect not of type "DIGITAL" and not of type "STRING", this file will generate a
linked Analog Alarm Tag within Vijeo Citect (anaalm.dbf) with the name <var-
iablename>_ALARM, with the following properties:

488
Chapter 17: Linking, Importing, and Exporting Tags

l high-high limit based on the variable tag's full and zero engineering scale properties
and a user specified fraction "Divisor".
In this example, only analog alarms for integer variables will have the limit set.

<?xml version="1.0" encoding="utf-8"?>

<input name="variable" file="variable.dbf">

<field name="name"></field>
<field name="type" ></field>
<field name="unit" load="true">{parameter.IODevice}</field>
<field name="eng_zero"></string>
<field name="eng_full"></string>
<field name="custom"></field>

<array name="taginfo">{ToProperty('{custom}', '=', ';')}</array>
<string name="alarminfo">{variable.taginfo[VJA]}</string>
</input>

<output name="anaalm" file="anaalm.dbf" filter="'{variable.alarminfo}=VJA' AND
'{variable.type}=INT'">
<field name="tag">{variable.name}_ALARM</field>
<field name="name">{variable.name}_ALARM</field>
<field name="var" key="true">{variable.name}</field>
<field name="taggenlink" load="true">{parameter.IODevice}</field>
<calculator name="highh" >({variable.eng_full}-{variable.eng_zero})/
{parameter.Divisor} </calculator>
<field name="highhigh">{highh}</field>
</output>

</template>

Exporting tags
The Export feature allows you to export I/O Device data to an external data source, spec-
ifying the destination and format of your choice (for example RSLOGIX driver). This file
might then be imported into a third-party I/O Device programming package database.
Alternatively, you might use it as a backup.

Note: Exporting using the OPC driver is not supported.

489
Chapter 17: Linking, Importing, and Exporting Tags

The file to which you are exporting needs to already exist; otherwise the export will not
work. You can choose to delete its contents before exporting, or you can leave it and
create duplicate tags.

Note: The export tags feature is not yet supported by every database type. If you have
existing links to any external data source, the linked tags will also be exported. As
the structure of each type of external data source differs, some tag data might not be
exported. This is determined by the format file for the I/O Device.

See Exported Tags for information about levels of support between Unity and Citect-
SCADA.

Note: Tag names greater than 32 Chars cannot be exported to Unity.

To export variable tags to an external database:

1. Open Citect Explorer.

2. Choose Tools | Export Tags.
3. Complete the Export Variable Tags dialog box as necessary.
See Also
Export Variable Tags properties
External data source
Format file

Export Variable Tags properties

Use this dialog for Exporting tags to an external database. The Export Variable Tags
dialog has the following fields:
External database
A reference (128 characters max.) to the external data source to which your variable tags
are exported. This can be:
l An explicit path and file (for example, C:\Data\Tags.csv)
l An IP address and node (for example, 127.0.0.1\HMI_Scada)
l A URL (for example, http://www.abicom.com.au/main/scada)
l A computer name (for example, \\coms\data\scada)

Note: This data source needs to exist before the export can be performed.

Database type
The format of the data referenced by the external data source.

490
Chapter 17: Linking, Importing, and Exporting Tags

Connection string
Enter a connection string to provide connection details for the data source. This is sim-
ilar to an ODBC connection string. For example:

UserID = XXX; Password = YYY

Not every data source requires a connection string.

I/O Device
The I/O Device for which you are exporting tags. Use the menu to select an I/O Device
that has been defined using CitectSCADA.
Remove prefix from tags
Select this box to remove a known prefix from the front of the exported tag names.
Tag prefix
The prefix (8 characters max.) to be removed from exported tag names.
Delete existing tags
Select this box to delete any tags in the external database before exporting.

Note: For the Unity driver existing tags are not deleted, even if you select this check
box.

External data source

When setting up an import, export, or link, you need to provide a data source and the
format of the data.
Your data source can be entered as:
l An explicit path and file (for example, C:\Data\Tags.csv)
l An IP address and node (for example, 127.0.0.1\HMI_Scada)
l A URL (for example, http://www.abicom.com.au/main/scada)
l A computer name (for example, \\coms\data\scada)
The database type field specifies the format of the external data source. When Citect-
SCADA attempts to read from this data source, it will use the mechanism specified by
the database type. The supported database types are:
l OPC (OPC1 is not supported)
l CSV (comma-separated values)
l Concept Ver 2.1 ASCII file

491
Chapter 17: Linking, Importing, and Exporting Tags

l Mitsubishi FastLinx (a specialized driver which allows you to connect directly to the
PLC programming software)
To configure the external data source as a file
The example uses a CSV file, in this case an RSLOGIX database driver
In the Import/Export or Links dialog box, enter details as follows:
l External database C:\Data\Tags.csv
l Database type RSLOGIX Driver
l Connection string (leave blank)
To configure the external data source using a specialized driver

Note: This example uses the supplied OPC driver.

In the Import/Export or Links dialog, enter details as follows:

l External database: The name of the OPC server process, for example, Fac-
torySoft.InProc
l Database type: OPC
l Connection string: The parameters are ServerNode or Branch, though both are
optional. Their use depends on the location of the OPC server and the scope of the
necessary data. ServerNode can be an IP address or the network path to the server.
For example:
l ServerNode=127.0.0.1
l ServerNode=\\Server
l ServerNode=www.server.com
For Branch, OPC data can be either a tree (hierarchical) or a flat structure. The
OPC driver supports access to both types of storage. If the data is in a tree struc-
ture, it can be accessed to the first branch level down from the root node, by enter-
ing the name of the branch. For example:
l Branch=device1
Deeper levels of branching might be supported in the future.

Note: This example uses the supplied Mitsubishi Driver

In the Import/Export or Links dialog box, enter details as follows:

l External database: 127.0.0.1\HMI_Scada (you can also use the computer name
instead of the IP address)
l Database type: Mitsubishi FastLinx
l Connection string: UserID=Citect;Password=Citect

492
Chapter 17: Linking, Importing, and Exporting Tags

The Connection String needs to be in the format which the specialized driver (in
this case Mitsubishi FastLinx) expects; otherwise it might be ignored.

Note: Tags in your external data source need to conform to the CitectSCADA
standard. Tag names that are longer than 79 characters are truncated. If this trun-
cation results in duplicate tags, you are informed when you compile your project.
Characters other than (a to z, A to Z, and 0 to 9) and the underscore character "_",
are removed on import/link (and before any truncation).

Format file layout

The format file is divided into sections:
l [General] section
l [Columns] section
l [ImportFilterMap] and [ExportFilterMap] sections
Each section consists of a section header (the section name enclosed in square brackets
(for example "[my_section]")) on a line by itself. This is followed by the body of the sec-
tion, typically single line statements of the form:

"something = something_else -> something_else_again"

494
Chapter 17: Linking, Importing, and Exporting Tags

Any white space (or none at all) is acceptable around the "=" and the "->", but the whole
statement needs to be on one line. Most statements within a format file follow this pat-
tern, but in many cases there might be no "->" (the converter), or there might just be a
converter without anything following it.
The following sections are necessary in every format file:

[General]
[Columns]
[ImportFilterMap]
[ExportFilterMap]

Other sections might be necessary depending on the complexity of the conversion

between CitectSCADA and the external data source. This is determined by the contents
of [ImportFilterMap] and [ExportFilterMap].
Comments can also be added within or between sections. To do this, place a semicolon
";" as the first character on the line. The rest of the line is then considered a comment,
and is ignored by CitectSCADA. For example:

; I am putting the [General] section here

[General]

[General] section
The General section consists of 4 lines:

[General]
Name=name
Description= description
DriverName= driver name
DriverInst="a special string"

The name and the description are not currently used by CitectSCADA. CitectSCADA uses
the driver name to load the correct driver for accessing the external data source. This
driver might be one that is part of the CitectSCADA installation, or it might be a cus-
tomized driver (including a driver that you have written yourself), for accessing a par-
ticular data source (which could be a protocol, type of hardware, server or file type). The
driver needs to be an OLE DB-compliant driver.
The special string allows extra information to be passed to the driver. It is added to the
connection string (in Citect Explorer and the Project Editor). So the connection string can
be used for information that is likely to change often, and this special string can be used
for more persistent information (such as the comma "," delimiter for a .CSV file). The
main use of this string is as a delimiter for an input file. To specify that a comma "," is
used by an input file as the delimiter, the following syntax would be used:

495
Chapter 17: Linking, Importing, and Exporting Tags

DriverInst="delimiter=,"

[Columns] section
The Columns section defines the format of the columns in the external data source. It is
structured as follows:

[Columns]
External column name 1 = column width -> data type
External column name 2 = column width -> data type
..
External column name n = column width -> data type

The only restriction that CitectSCADA places on the data for External Column name n is
that it needs to be unique within the section. For convenience, you can use the names
that the external data source uses (such as "Description", "PLC_id", "Iotype") or you can
just make up names like "Column1", "Column2", etc. The order in which these entries
appear needs to be the same as the order of the fields in the external data source. The
names used for the External Data Source columns in the [ImportFilterMap] and [Export-
FilterMap] sections needs to come from this list.
Column width is the number of characters in the field, and data type is the type of data for
that column. Currently the only acceptable data type is "STRING".

[ImportFilterMap] and [ExportFilterMap] sections

The [ImportFilterMap] and [ExportFilterMap] sections have identical syntax and func-
tionality, except that the [ImportFilterMap] describes how to convert data from the Exter-
nal data source on import, while the [ExportFilterMap] describes the opposite conversion.

These are the most complex sections in the format file. (The rest of the text will just focus
on the [ImportFilterMap], as the [ExportFilterMap] follows basically the same logic.)
The [ImportFilterMap] is structured as follows:

[ImportFilterMap]
Import Rule 1 = External column name l -> Citect Column i
Import Rule 2 = External column name m -> Citect Column j
..
Import Rule nn = External column name n -> Citect Column k

496
Chapter 17: Linking, Importing, and Exporting Tags

The values in Import Rule nn can be any name strings, but they needs to be unique
within the section. Therefore, for convenience, you might want to use names like "Impor-
tRule1", "ImportRule2", "Mapping1", "Filter1" etc., or you might want something that is
descriptive of the conversion involved, such as "Description_to_comment".
The name used for External column name n needs to be identical to a name that appears
in External column name n in the [Columns] section above.
The name used for Citect Column k needs to be the same as one of the columns in the
CitectSCADA internal tags database, such as "Name", "Type", "Addr", "Comment" etc.
Thus the values for the external column and the CitectSCADA column provide infor-
mation on how to transfer data from the external column to the Citect column during
import.
For example:

ImportRule1 = Description -> Comment

This indicates that there is a relationship between the data in the "Description" field in
the external data source and the data that needs to go into the "Comment" field in the
CitectSCADA database.
The name that you use for Import Rule nn might be the same as the name of another
optional section in the format file: here, the extra section provides CitectSCADA with
more information. In the simplest case, if there is no section with that name in the for-
mat file, the rule simply states that the data in External column name n is to be copied
directly into Citect Column k without modification or filtering.
So if the "Description" column in the external database contains "Truck Position 1" and
the above entry appears in the [ImportFilterMap] section, and there is no section called
[ImportRule1], then after the import, the "Comment" column in the CitectSCADA data-
base will contain the string "Truck Position 1".

Concatenation
To concatenate fields from the external database into one field in the CitectSCADA data-
base, add separate entries to the [ImportFilterMap] section. Each section needs to contain
the name of a relevant external column and the name of the destination column in Citect-
SCADA. The entries needs to appear in the order in which the fields are to be con-
catenated.
So, if the external data source has a field called "IOdev" containing the value "M", and
another field called "IOaddr" containing the value "61", and you want to join them
together so that the value "M61" is imported into the CitectSCADA "Addr" field, this is
how it would be done:

497
Chapter 17: Linking, Importing, and Exporting Tags

[ImportFilterMap]
Addr1= IOdev -> Addr
Addr2= IOaddr -> Addr

Here, you need to verify that there are no sections in the format file called [Addr1] or
[Addr2], unless you need some filtering or conversion.
See Also
Field conversion

Field conversion
To modify mapped data or to apply filtering (to reject certain records), create a new sec-
tion using the name of the relevant line from the mapping section. For example, if you
have the following mapping section:

[ImportFilterMap]
Test1_to_type = Test1 -> Type

and you want to convert the data from the Test1 column before importing it, somewhere
in the file you need to have a section called [Test1_to_type]:

Test1_to_type]

followed by the necessary conversion rule.

Note: The name needs to be from the import mapping section, not from the export
mapping section. If you use a name from the export mapping section, the conversion
applies to the export, not the import.

The basic format of this conversion/filtering section is as follows:

[Relevant mapping name]

Filtering Rule 1 = External Pattern 1 -> Citect String 1
..
Filtering Rule m = External Pattern m
..
Filtering Rule n = External Pattern n -> Citect String n

The name used for Filtering Rule n has no intrinsic significance to CitectSCADA (except
that it uses it as a key to locate the entry). The only restriction is that it needs to be
unique within the section, so you can use whatever is convenient.

498
Chapter 17: Linking, Importing, and Exporting Tags

The value in External Pattern n is a combination of characters which CitectSCADA will

look for in the external data source column. This pattern can be any combination of the
following:

Character in Matches what string in external data source

format file

<specific text> <specific text>

* Any string.

? Any single character.

%d Any decimal integer (nnn. . . where n is 0-9).

%e Any octal number (0onnn. . . where n is 0-7).

%h Any hexadecimal number (0xnnn. . . where n is 0-9, A-F or a-f).

%s Any string.

{ Begin a "token string". Any characters enclosed by { } in the Input

Pattern (including regular and special characters) represent a token
string. The characters in the data stream that match a token string
are referenced by the Output Data String and written directly to the
output database as a group.

} End of a token string.

\ Treat the following character as a literal. For example, if a literal *

character was expected in the input data stream, you would use \*
to denote this. If a literal backslash \ is expected, use \\.

Any other characters need to literally match the same character.

If External Pattern n is found in the external column, Citect String n is written to the rel-
evant column in CitectSCADA (as per the mapping).
In addition, two special characters can appear in the output data string:

Character in out- Meaning

put string

$ The pattern $n (where n is any integer) is replaced in the output

data stream by the nth "token"; a token is a matching sequence of
characters enclosed by { } in the input pattern. (An alert message
will result if $ not followed by a token number.)

499
Chapter 17: Linking, Importing, and Exporting Tags

!REJECT! This sequence needs to appear by itself in the output data pattern.
The whole record is rejected. As the record had already been
matched to the input pattern, no further rules are checked.

\ Treat the following character as a literal. This would be used if a lit-

eral $ sign was necessary (use \$) or if another digit immediately
follows. For example, if the string "3August2001" needs to imme-
diately follow the token, use "$1\3August2001".

\ (at end of line) Insert a literal space ` ' character at the end of the output line.
Without this provision, the system could not distinguish between
the end of the input line (which is likely to be followed by char-
acters, such as spaces, that Windows will ignore) and a space
being necessary at the end of the output line.

Other characters are written literally to the output database.

CitectSCADA works through each filtering rule in the section, looking for a match. If a
rule does not match, the next one is tried, then the next, and so on, until a match is
found. If no match is found, the whole record is rejected; none of the data from any field
is copied to CitectSCADA.
For example, to convert the string "FLOAT" in the external data source to "DIGITAL" in
CitectSCADA, you could use the following entry:

[ImportFilterMap]
Test1_to_type = Test1 -> Type
..
[Test1_to_type]
Rule1 = FLOAT -> DIGITAL
..

For a more complex example, let us assume that the external data source has a column
called "Tag" which is equivalent to the "Name" field in CitectSCADA. Let us also assume
that the external database has no direct equivalent of CitectSCADA's "Type" field, yet
CitectSCADA needs this field to be filled in. We need to use the "Tag" field to decide
what goes into the "Type" field of the CitectSCADA database.
If the "Tag" column in the external data source has the value "I:060/07", we have deter-
mined that we write the string "DIGITAL" into CitectSCADA's "Type" field. In fact, if that
field has "I:" followed by any octal value, followed by a slash "/", followed by any octal
value, we want the string "DIGITAL" to appear in our "Type" field. How do we express
this in the format file?
Firstly, there are two sets of relationships to consider, one connecting the "Tag" field in
the external data source to the "Name" field in CitectSCADA, and the other connecting it
to the "Type" field in CitectSCADA. So we need two "mappings" (entries) in the [Import-
FilterMap] section:

500
Chapter 17: Linking, Importing, and Exporting Tags

[ImportFilterMap]
Tag_to_Name = Tag -> Name
Tag_to_Type = Tag -> Type
..

As we want the data in the "Tag" field to be copied directly into the "Name" field, we do
this by not having a [Tag_to_Name] section anywhere in the format file.
But because we are not copying directly from the "Tag" field to the "Type" field, but are
just using the data to decide what goes into the "Type" field, we need a [Tag_to_Type] sec-
tion.
Recall the desired outcome: If the "tag" field has "I:" followed by any octal value, fol-
lowed by a slash "/", followed by any octal value, we want the string "DIGITAL" to
appear in our "Type" field.
We express this in the format file as follows:

[Tag_to_Type]
Rule1 = I:%e/%e -> DIGITAL
..

This will match "I:060/07" or "I:0453/02343445602" (and cause the string "DIGITAL" to be
written to CitectSCADA's Type field), but will not match "I:060/98" or "I:054".
To give a few examples of how the wild-card characters (%s, * and ?) might be used, the
pattern "HE%sLD" or "HE*LD" in the format file would match "HELLO WORLD" or "HE
IS VERY BOLD" in the external data source. The pattern "HE???????LD" would match
"HELLO WORLD" but not "HE IS BALD", as each question mark "?" needs to match
exactly one character.
CitectSCADA will also handle multiple wildcard patterns, such as "%s/%s:%s".
For an example more useful than "Hello World", imagine that we need to copy the data
straight across without modification, but we want to verify that no blank fields are cop-
ied across. The pattern "?%s" or "?*" will match any string that has at least one character,
but will not match a blank.
Sometimes only part of the input stream is necessary in the output, or the input might
need to be split up into different output columns. In these situations "tokens" are useful.
In this example of an export situation, the "Addr" field in the CitectSCADA database
needs to be split among two fields in the external database: the "IOdev" (whose value is
always "D" or "M"); and "IOaddr" (whose value is a decimal integer of no more than 3
digits). Values in the "Addr" field of the CitectSCADA database are strings such as
"D62", "M546", etc.

501
Chapter 17: Linking, Importing, and Exporting Tags

This situation could be solved by concatenation, i.e. using one mapping to write to the
IOdev field, and three other separate mappings to copy each digit separately into the
IOaddr field of the external database. But this would be complex and in some situations
would not work.
It is better to use a token to address the situation:

[ExportFilterMap]
..
Addr2IOdev = Addr -> IOdev
Addr2IOaddr = Addr -> IOaddr
..
[Addr2IOdev]
D = D* -> D
M = M* -> M
AnythingElse = * ->
..
[Addr2IOaddr]
Rule = ?{%d} -> $1

In the [Addr2IOaddr] section, the {%d} is the token string, and as it is the first (and only)
token appearing in the rule, $1 is used to reference it on the output stream side. So if the
"Addr" field of the CitectSCADA database contains "D483", "D" is written to the "IOdev"
field of the external data sink, and "483" (the token) to the "IOaddr" field.
Here is another example illustrating the use of multiple tokens. Suppose we need to: con-
vert period characters (.) to colons (:); remove the first two characters (which are blank);
and remove any unnecessary characters from the data we are expecting; that is, convert
"..BJ6452.78......" to "BJ6542:78". This can be achieved by using the following rule:

Rule = ??{%d}.{%d} -> $1:$2

At this point, we introduce another feature of the format file. If you use the following
rule:

[Relevant mapping name]

Filtering Rule = External pattern

i.e., without "-> Citect String" included, CitectSCADA interprets this as "check that the
string matches the External Pattern, if it does, copy it across unchanged".
If this rule is used:

Filtering Rule = External pattern ->

i.e., without "Citect String", it would mean: "If the string pattern matches then accept the
record but copy a NULL string to the CitectSCADA database."

502
Chapter 17: Linking, Importing, and Exporting Tags

Using the above example again, we can add the restriction that any records with no data
(i.e. a blank or NULL string) in the Tag field of the external data source will not be
imported into CitectSCADA. We would add a [Tag_to_Name] section, and would have
just one rule: that we accept everything except for a blank.

[Tag_to_Name]
RejectBlanks = ?*
..

Recall that CitectSCADA checks the pattern in each filter rule sequentially until a pattern
that matches the string is found in the external data source. With this in mind, a huge
range of conversions and filterings are possible by ordering the rules correctly and, in
some cases, by making use of concatenation.
For instance, if certain string types need to be converted but others need to be copied
unmodified to CitectSCADA, you could have a section with a set of rules at the top, fol-
lowed by a final rule to let everything else through unmodified.

[Tag_to_Name]
Rule n = ...... -> ......
..
LetEverythingElseThru = %s

A single %s or *, without anything else, matches anything and everything, including

blanks.
For an example of how to reject a particular string or pattern, let's suppose we want to
reject any tags starting with "DFILE"(another real-life example). We would simply use
the following:

[Tag_to_Name]
Rule1 = DFILE* -> !REJECT!
..
LetEverythingElseThru = %s

Clearly, it is pointless having the !REJECT! rule not followed by other rules concerning
patterns that you do want to accept, as anything that does not match an input pattern is
rejected. The logic behind the order that the rules appear can become particularly impor-
tant when using a !REJECT! rule. You would typically have any reject rule(s) as the first
rule(s) in the mapping. There would not be any point in putting a !REJECT! rule as the
last rule in the mapping.
!REJECT! rules can also be useful where some text file generated by another system con-
tains some sort of header lines that are not wanted, but the rest of the data is necessary.
See Also
Having CitectSCADA recognize format files

503
Chapter 17: Linking, Importing, and Exporting Tags

Recognizing format files

Your format file needs to be saved to the config folder of the CitectSCADA User and
Data folder selected during installation.
For CitectSCADA to import, export, or link, it needs to know the name of the format file
and the name of the driver that will access the external data source. It also needs the text
of the string that will appear in the Database type field of the Import or Export dialog
box. This information is stored in another file, called tagdriv.ini, in the same directory.
The format of tagdriv.ini is simple and based on the odbc.ini format. When it is
installed it already has the necessary information for the format files and drivers that
come shipped with CitectSCADA. You just need to copy the same layout for your new
format file, and the driver that you are using.
The tagdriv.ini file has several sections. The first section is the [External data sources]
section, with the following general layout:

[External data sources]

Section name 1 = the name you want to appear in the import/export/ link menu for
entry 1
Section name 2 = the name you want to appear in the import/export/ link menu for
entry 2
..
Section name nn = the name you want to appear in the import/export menu for entry nn

Each entry in this section refers to a combination of format file and driver necessary for
a particular import, export, or link operation.
The text on the left of the "=" sign needs to refer to the name of another section which
needs to appear in tagdriv.ini.
The text on the right of the "=" sign is exactly what will appear in the menu under "Data-
base type" for importing, exporting or refreshing variable tags.
The other sections each refer to a type of import or export described in the [External data
sources] section, and give details about the format file and driver pair. The general lay-
out of these sections is as follows:

[Section name matching an entry in [External data sources] ]

driverid = Driver ID
datastring = The name of the format file
Currently the Driver ID is always CiTrans.

So if we assume that the version of CitectSCADA you are installing contains 45 format
files, there would be 45 sections in tagdriv.ini, as shown in the following example:

504
Chapter 17: Linking, Importing, and Exporting Tags

; This file contains the driver name, driver prog id, and format file mappings
; The format file needs to reside in the BIN directory

[External data sources]

CSV = CSV Driver
RSLOGIX = RSLOGIX Driver
Concept ver 2.1 Ascii = Concept Ver 2.1 ASCII file
MxChange = Mitsubishi FastLinx

[CSV]
driverid = CiTrans
datastring = csv.fmt

[RSLOGIX]
driverid = CiTrans
datastring = rslogic.fmt

[Concept ver 2.1 Ascii]

driverid = CiTrans
datastring = concept ver 2_1.fmt

[MxChange]
driverid = CiTrans
datastring = MxChange.fmt

; This file contains the driver name, driver prog id, and format file mappings
; The format file needs to reside in the BIN directory

[External data sources]

CSV = CSV Driver
Concept ver 2.1 Ascii = Concept Ver 2.1 ASCII file
OPC = OPC
UnityProDynamic = Unity SpeedLink Dynamic
UnityProStatic = Unity SpeedLink Static

[CSV]
driverid = CiTrans
datastring = csv.fmt

[Concept ver 2.1 Ascii]

driverid = CiTrans
datastring = concept ver 2_1.fmt

[OPC]
driverid = CiTrans
datastring = OPC.fmt

[UnityProDynamic]
driverid = CiTrans
datastring = UnityProDynamic.fmt
LiveUpdate = TRUE

[UnityProStatic]
driverid = CiTrans

505
Chapter 17: Linking, Importing, and Exporting Tags

datastring = UnityProStatic.fmt
LiveUpdate = FALSE

This adds 45 entries to the database type drop down menu: CSV, RSLOGIX, ASCII and
Mitsubishi FastLinxCSV, ASCII, OPC, Unity Pro Dynamic and Unity Pro Static.
The 45 entries in the menu match the strings on the right of the "=" sign in the [External
data sources] section.

If you add another format file, you will also need to add a matching entry to tagdriv.ini.
For example, if you add a new format file for a Simatic data source, you need to add a
line similar to this to the [External data sources] section:

SIMATIC = Siemens SIMATIC Driver

You need to also add the following section to the bottom of the file:

[SIMATIC]
driverid = CiTrans
datastring = SIMATIC.fmt

Save the file, restart Citect Explorer, and "Siemens SIMATIC Driver " appears in the
menu.
Selecting this entry causes the format file in the datastring entry under the [SIMATIC] sec-
tion to be used for the import, export, or link; that is, simatic.fmt.

Unity Support Matrixes

The following sections show the levels of support between Unity and CitectSCADA:
l Imported Tags
l Exported Tags
l Linked Tags

Imported Tags
For Unity Fastlinx Dynamic and Static:

Unity Unity Data Citect Protocols Support Status

PLCs Types

506
Chapter 17: Linking, Importing, and Exporting Tags

QUANTUM BOOL Unite Not Supported

EBOOL
BYTE
WORD Modnet Supported (Except
DWORD BYTE type)
INT
DINT
Modbus Supported (Except
UINT
BYTE type)
UDINT
REAL
TIME * MBPlus Supported (Except
DATE * BYTE type)
TOD *
DT *
OPC Not Supported
STRING

PREMIUM BOOL Unite Supported

M340 BOOL Unite Not Supported

EBOOL
BYTE
WORD Modnet Supported (Except
DWORD BYTE type)
INT
DINT
UINT Modbus Supported (Except
UDINT BYTE type)
REAL
TIME * MBPlus Not Supported
DATE *
TOD *
DT *
OPC Not Supported
STRING

Note: Citect recommends that you use the Unity Fastlinx Dynamic driver when
importing tags from Unity Pro into a Citect project.

507
Chapter 17: Linking, Importing, and Exporting Tags

Note: Arrays are supported for every data type except DATE, TOD, DT and STRING
data types. For Unity data types marked with *, Citect does not have data types that
directly match the Unity types. Instead use supported data types and Cicode to con-
vert and simulate those data types.

In addition, the following Unity data types are not supported:

l Structured data types.
l Arrays which are not zero-based.
l Multi-dimensional arrays.
l Arrays of Unity BOOL data type are not supported for all protocols and will be
excluded from the import.

Exported Tags
For Fastlinx Static:

Unity Unity Data Citect Protocols Support Status

PLCs Types

QUANTUM BOOL Unite Not Supported

508
Chapter 17: Linking, Importing, and Exporting Tags

PREMIUM BOOL Unite Supported

M340 BOOL Unite Not Supported

EBOOL
BYTE
WORD Modnet Supported (Except
DWORD BYTE type)
INT
DINT
UINT Modbus Supported (Except
UDINT BYTE type)
REAL
TIME * MBPlus Not Supported
DATE *
TOD *
DT *
OPC Not Supported
STRING

Note: Arrays are supported for data types except DATE, TOD, DT and STRING data
types. For Unity data types marked with *, Citect does not have data types that
directly match the Unity types. Instead use Technical supported data types and
Cicode to convert and simulate those data types.

In addition, the following Unity data types are not supported:

l Structured data types.
l Arrays which are not zero-based.
l Multi-dimensional arrays.
l Arrays of Unity BOOL data type are not supported for all protocols.

Linked Tags
Linked I/O Device Live Update
For Unity Fastlinx Dynamic:

509
Chapter 17: Linking, Importing, and Exporting Tags

Unity Unity Data Citect Protocols Support Status

PLCs Types

QUANTUM BOOL Unite Not Supported

PREMIUM BOOL Unite Supported

M340 BOOL Unite Not Supported

EBOOL
BYTE
WORD Modnet Supported (Except
DWORD BYTE type)
INT
DINT
UINT Modbus Supported (Except
UDINT BYTE type)
REAL
TIME * MBPlus Not Supported
DATE *
TOD *
DT *
OPC Not Supported
STRING

Note: Arrays are supported for data types except DATE, TOD, DT and STRING data

510
Chapter 17: Linking, Importing, and Exporting Tags

types. For Unity data types marked with *, Citect does not have data types that
directly match the Unity types. Instead use supported data types and Cicode to con-
vert and simulate those data types.

In addition, the following Unity data types are not supported:

l Structured data types.
l Arrays which are not zero-based.
l Multi-dimensional arrays.
l Arrays of Unity BOOL data type are not supported for all protocols.

511
Chapter 17: Linking, Importing, and Exporting Tags

512
Chapter 18: Defining and Drawing Graphics Pages
A runtime system usually comprises a series of graphics pages that display on your com-
puter screen(s) and provide a "window into the process." You can design your pages to
provide your operators with control of an area (or all) of your plant. Your graphics pages
can also display the status of your plant by using various graphical items known as
objects.
See Also
Creating a New Graphics Page
Using Page Templates
Using a Browse Sequence
Specifying a Startup Page
Sizing the Page
Defining Page Properties
Setting Default Page Settings
Understanding the Drawing Environment
Using Find and Replace in a project

Creating a New Graphics Page

You can display your graphics pages on a monitor individually, or display several
pages at a time. You can display them in any order, controlled by operator commands or
controlled automatically.
To create a new page:

1. From the Graphics Builder, click New, or choose File | New.

2. Click Page.
3. Choose a Template upon which to base the page.
4. Choose a Style for the page.
5. Check or clear the Linked and Title bar as necessary.
6. Choose the Resolution for the page.
7. Click OK.

Note: If you create a new page using the Graphics Builder, you need to edit the page
record (with the Project Editor) to define a browse sequence.

513
Chapter 18: Defining and Drawing Graphics Pages

New Dialog Box

This dialog box is used to create a page, template, symbol, Genie, or Super Genie by
selecting a button.

Working with pages

To open an existing page:

1. Click Open, or choose File | Open.

2. Choose Type: Page.

514
Chapter 18: Defining and Drawing Graphics Pages

3. Select the Project where the page is stored.

4. Select the Page.
5. Click OK.

Note: To delete a page from the project, select the page name and click Delete.

To save the current page:

1. Click Save, or choose File | Save.

2. Select the Project in which to store the page. (The first eight characters of the name
needs to be unique to this page.)
3. Click OK.
To save the current page with a new name:

1. Choose File | Save As.

2. Select the project in which the page is stored.
3. Enter a name for the page in Page (64 characters maximum). The first eight char-
acters of the name needs to be unique to this page.
4. Click OK.
To save current pages that are open

l Choose File | Save All. (The first eight characters of each page name needs to be dif-
ferent.)
See Also
Use Template (new page/template) dialog box
Open/Save As dialog box
To locate a graphics page:

1. Choose File | Find.

2. Select a project from the Project Name list.
3. Browse through the pages in the Pages list.
4. Click OK to view the page.
See Also
Using Find and Replace in a project
To print a graphics page on your printer:

l Choose File | Print. (This prints without a confirmation dialog.)

To close an existing page:

l Choose File | Close.

515
Chapter 18: Defining and Drawing Graphics Pages

Use Template (new page/template) dialog box

This dialog box lets you create a new page or template based on an existing template.
Template
A table of templates on which you can base the new page or template. Use the scroll bar
to locate the thumbnail image of the template, then choose the template and click OK (or
double-click the thumbnail image).

Note: To edit the template, select it and click Edit

Style
The style of the page. CitectSCADA templates are grouped into several styles and are
available in various page resolutions. When you create a new project, you can choose
the style that most suits your taste and application. For details of each style, refer to the
"Presenting CitectSCADA " booklet, supplied with your CitectSCADA system.
Linked
To maintain the link with the original template, select this check box. A page or template
that is linked with its original template is automatically updated if the template is
changed.

Note: You can cut the link to the template at any time with the Cut Link command
from the Edit menu, but you cannot re-link a page or template with its original tem-
plate after the link has been cut.

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 dis-
play, the title bar still displays, even if fullscreen mode is enabled. Standard templates
styles are available for both page sizes.
Resolution
The screen resolution of the page or template:

516
Chapter 18: Defining and Drawing Graphics Pages

Screen
Width (pixels) Height (pixels)
Type

Defaul- Width of the screen on the computer Height of the screen on the com-
t currently in use puter currently in use

VGA 640 480

SVGA 800 600

XGA 1024 768

SXGA 1280 1024

User User-defined size User-defined size

Open/Save As dialog box

This dialog box lets you open or save a page, template, symbol, Genie, or Super Genie.
(To select the type of entity, click the appropriate tab.)
Page/Symbol/Template/Genie
The name of the graphics page, template, symbol, Genie, or Super Genie.
If you are opening a page, template, symbol, Genie, or Super Genie, select its name from
the large window.
If you are saving a page, template, symbol, Genie, or Super Genie, type a name into the
smaller input box (or select a name from the large window if you want to overwrite an
existing page, template, symbol, Genie, or Super Genie).

Note: If you are using distributed servers, the name needs to be unique to the cluster
(for example you cannot have the same page name in more than one cluster).

Project
The project in which to save the graphics page, template, symbol, Genie, or Super Genie.
Library
(For symbols, Genies, and Super Genies only.) The library in which to save the symbol,
Genie, or Super Genie. To create a new library, click New.
Style
(For templates only.) The style of the template. To create a new style, click New.
Preview Enable

517
Chapter 18: Defining and Drawing Graphics Pages

Displays a thumbnail image of the page, template, symbol, Genie, or Super Genie.
Title bar
(For templates only.) Specifies whether to include a space for the title bar. If you use a
title bar, you will have slightly less display space on screen.
Resolution
(For templates only.) The screen resolution of the template:

Screen Type Width (pixels) Height (pixels)

Default Width of the screen on the Height of the screen on the

computer currently in use computer currently in use

VGA 640 480

SVGA 800 600

XGA 1024 768

SXGA 1280 1024

User User-defined size User-defined size

To delete a page, template, symbol, Genie, or Super Genie, select it and click Delete.

Using Page Templates

You can use many different page types in your runtime system.
l Mimic pages display the status of the plant, with buttons and other controls to give
your operators control of processes within the plant.
l Alarm pages display alarm information.
l Trend pages display a visual representation of past and current activity in the plant.

Note: You need to create default pages for your alarms (including alarm summary
and hardware alarms pages).

To enable you to create your graphics pages quickly, there are templates for common
page types. Templates help you create project pages that have a consistent 'look-and-
feel'. (Consistency in your project reduces the time your operators need to learn how to
use your runtime system.)

518
Chapter 18: Defining and Drawing Graphics Pages

See Also
Choosing a page style
Linking templates
Creating your own templates

Choosing a page style

Templates are grouped into several styles and are available in various page resolutions.
When you create a new project, you can choose the style that most suits your taste and
application.
See Also
Linking templates

Linking templates
When using a template to create a new page, a link can be kept to the template. A page
(or template) that is linked with its original template is automatically updated if the tem-
plate is changed.
When a page is linked to a template, the objects that form the template cannot be
accessed from the page by the usual double-click. To display the properties of these
objects, hold the Control (CTRL) key down and double-click the object you want to view
properties for. Alternatively, choose Tools | Goto Object, select the group, and click OK.
However, most of these properties are read-only.

Note: You can cut the link to the template at any time using Edit | Cut Link, but you
cannot re-link a page or template with its original template after the link has been
cut.

Creating your own templates

If your project contains several pages that are similar (for example, menu pages, com-
mon processes, or common equipment), you can create your own template (containing
common objects) to use as a base for the pages. You can then create the pages based on
the template, and add individual objects to each page.
If you want to delete or change the location of a common object, or to add a new com-
mon object, you do not have to change each page; instead, you can change the template.
Pages based on that template are automatically updated.

519
Chapter 18: Defining and Drawing Graphics Pages

Note: When you create a template, save it in the project directory. It is then backed
up when you back up the project. Don't modify the supplied standard templates.
When you edit a template, you need to use the Update Pages command (from the
Tools menu) to update each page based on the template. The properties of the tem-
plate are not updated automatically.

To create a new template:

1. Click New, or choose File | New.

2. Click Template.
3. Choose a Template upon which to base the template.
4. Choose a Style for the template.
5. Check or clear the Linked and Title bar as necessary.
6. Choose the Resolution for the template.
7. Click OK.
To open an existing template:

1. Click Open, or choose File | Open.

2. Select Type: Template.
3. Select the Project where the template is stored.
4. Select the Template.
5. Click OK.

Note: To delete a template from the project, select the template name and click
Delete.

To save the current template:

1. Click Save, or choose File | Save.

2. Select the Project in which to store the template.
3. Click OK.

Note: To create a new style for the template, click New. You create a new template

520
Chapter 18: Defining and Drawing Graphics Pages

style using the New Style dialog box.

New Style dialog box

This dialog box lets you create a new style of templates. Enter a name for your new style
in the Name text box.
See Also
Creating your own templates

Using a Browse Sequence

You can link related pages together with a browse sequence. A browse sequence creates
a linear navigation sequence for the pages in your system.
When you define a graphics page, you can specify where in the browse sequence the
page displays. Within a browse sequence, an operator can display a preceding or fol-
lowing page by choosing Page Previous and Page Next commands (or a similar set of
buttons defined on each page).
When you save a page for the first time it is automatically added to the browse
sequence.
You can also use multiple browse sequences by defining a Page GoTo command that dis-
plays a page in another (secondary) sequence. The Page Next and Page Previous com-
mands then display the next and previous pages in the secondary sequence, as in the
following diagram:

521
Chapter 18: Defining and Drawing Graphics Pages

You do not have to use a display sequence. You can define several Page GoTo com-
mands that display specific pages in an hierarchical structure.
See Also
Specifying a Startup Page

Specifying a Startup or Splash Page

Every system needs to have a startup page and may have a splash screen.
A splash screen is the very first window that is displayed when CitectSCADA starts. The
splash window has a thin windows border, is non-movable and is often set to "always
on top". Usually, the splash window displays brief project information, such as com-
pany logo, software version, project version, while the system is initializing. By default,
it is only displayed for a brief period of time and then automatically dismissed.
The startup page is displayed before or after the splash window is dismissed. The tim-
ing is controlled by a set of parameters:
l [Page] SplashTimeout# - how long the splash window will be displayed
l [Page] StartupDelay# - how long the Startup page will wait before it is displayed.
If the StartupDelay is set to less than the SplashTimeout, the Startup page will be dis-
played while the splash screen is still shown. On the other hand, setting the Star-
tupDelay to be greater than the SplashTimeout will display the Startup page after the
splash screen is dismissed.

522
Chapter 18: Defining and Drawing Graphics Pages

The example project makes use of the new splash screen parameters to specify a page to
be displayed as splash screen, and the new Cicode functions to display product and
project information on the splash screen.
The following parameters are used to set up the splash screen in the example project:
[Page]
Splash = !Splash
SplashWinName = Splash
SplashTimeout = 5000
Startup = Menu
StartupWinName = Main
StartupDelay = 5100
HomePage = Menu
See Also
Sizing the Page

Sizing the Page

By default, new pages in the Graphics Builder take up your entire display area. You can
resize them if you want. You can:
l Specify the size of a page when you create it.
l Change the size of a page at any time after it is created.
l Specify that new pages default to a different size.
See Also
Page (screen) resolution
Page size at runtime

Page (screen) resolution

When you draw a graphics page, determine the resolution of the computer you are using
to draw the page, and the resolution of the screen that will display the page in your run-
time system.
If a page displays on a screen with a resolution which is greater than the page's res-
olution, the page will be smaller than the display area. For example, if you draw a page
on a VGA screen (640 x 480) and then display it on a XGA screen (1024 x 768), the
image displays in the top left corner of the screen, and occupies a little more than half of
the screen.

523
Chapter 18: Defining and Drawing Graphics Pages

Conversely, if a page displays on a screen with a resolution which is lower than the
page's resolution, the page will be larger than the display area. For example, if you draw
a page on a XGA screen and then display it on a VGA screen, it occupies more than the
entire screen; use the scroll bars to scroll to the area of the page that is not displayed.

See Screen examples for some examples of parameter settings and how the screen is dis-
played on screen.
See Also
Page size at runtime

Screen examples
When you draw a graphics page, determine the resolution of the computer you are using
to draw the page, and the resolution of the screen that will display the page in your run-
time system.

524
Chapter 18: Defining and Drawing Graphics Pages

Example Description Notes

[Animator]Full-
Screen = 0
[Animator]Max-
imizedWindow =
0
[Page]Dynam-
icSizing = 1
[Page]Main-
tainAspectRatio
=0

[Animator]Full-
Screen = 0
[Animator]Max-
imizedWindow =
0
[Page]Dynam-
icSizing = 1
[Page]Main-
tainAspectRatio
=1

[Animator]Full- Page content is not

Screen = 0 scaled. Scrollbars are
[Animator]Max- enabled if the window
imizedWindow = is resized and no
0 longer large enough
[Page]Dynam- to show the entire
icSizing = 0 page.

525
Chapter 18: Defining and Drawing Graphics Pages

Example Description Notes

[Animator]Full-
Screen = 0
[Animator]Max-
imizedWindow =
0
[Page]Star-
tupMode = 4

[Animator]Full-
Screen = 0
[Animator]Max-
imizedWindow =
0
[Page]Star-
tupMode = 16

[Animator]Full- "Page size = monitor -

Screen = 0 titlebar - taskbar"
[Animator]Max- means the aspect
imizedWindow = ratio of the page is the
1 same as that of the
[Page]Dynam- screen area of a mon-
icSizing = 1 itor after taking out
[Page]Main- the total area of the
tainAspectRatio titlebar and the task-
=0 bar.

Aspect ratio =
monitor - titlebar
- taskbar
[Animator]Full-
Screen = 0
[Animator]Max-
imizedWindow =
1
[Page]Dynam-
icSizing = 1

526
Chapter 18: Defining and Drawing Graphics Pages

Example Description Notes

[Page]Main-
tainAspectRatio
=1

Page size = mon-

itor - titlebar -
taskbar
[Animator]Full-
Screen = 0
[Page]Dynam-
icSizing = 0

[Animator]Full-
Screen = 0
[Animator]Max-
imizedWindow =
1
[Page]Dynam-
icSizing = 1
[Page]Main-
tainAspectRatio
=0
[Page]Star-
tupMode = 16

Aspect ratio =
monitor - taskbar
[Animator]Full-
Screen = 0
[Animator]Max-
imizedWindow =
1
[Page]Dynam-
icSizing = 1
[Page]Main-
tainAspectRatio
=1
[Page]Star-
tupMode = 16

Page size = mon-

itor - taskbar
[Animator]Full-
Screen = 0
[Page]Dynam-
icSizing = 0

527
Chapter 18: Defining and Drawing Graphics Pages

Example Description Notes

[Page]Star-
tupMode = 16

Aspect ratio <>

monitor - titlebar
- taskbar
[Animator]Full-
Screen = 0
[Animator]Max-
imizedWindow =
1
[Page]Dynam-
icSizing = 1
[Page]Main-
tainAspectRatio
=1

Aspect ratio <>

monitor - taskbar
[Animator]Full-
Screen = 0
[Animator]Max-
imizedWindow =
1
[Page]Dynam-
icSizing = 1
[Page]Main-
tainAspectRatio
=1
[Page]Star-
tupMode = 16

Aspect ratio <>

monitor - titlebar
- taskbar
[Animator]Full-
Screen = 0
[Animator]Max-
imizedWindow =
1
[Page]Dynam-
icSizing = 1
[Page]Main-
tainAspectRatio
=1

528
Chapter 18: Defining and Drawing Graphics Pages

Example Description Notes

Aspect ratio <>

monitor - taskbar
[Animator]Full-
Screen = 0
[Animator]Max-
imizedWindow =
1
[Page]Dynam-
icSizing = 1
[Page]Main-
tainAspectRatio
=1
[Page]Star-
tupMode = 16

[Animator]Full-
Screen = 1
[Page]Dynam-
icSizing=1
[Page]Main-
tainAspectRatio
=0

Aspect ratio =
monitor
[Animator]Full-
Screen = 1
[Page]Dynam-
icSizing = 1
[Page]Main-
tainAspectRatio
=1

Page size = mon-

itor
[Animator]Full-
Screen = 1
[Page]Dynam-
icSizing = 0

529
Chapter 18: Defining and Drawing Graphics Pages

Example Description Notes

[Animator]Full- The window cannot

Screen = 2 be moved.
[Page]Dynam-
icSizing=1
[Page]Main-
tainAspectRatio
=0

Aspect ratio =
monitor - titlebar
[Animator]Full-
Screen = 2
[Page]Dynam-
icSizing = 1
[Page]Main-
tainAspectRatio
=1

Page size = mon-

itor - titlebar
[Animator]Full-
Screen = 2
[Page]Dynam-
icSizing = 0

Aspect ratio <>

monitor
[Animator]Full-
Screen = 1
[Page]Dynam-
icSizing=1
[Page]Main-
tainAspectRatio
=1

Page size <>

monitor
[Animator]Full-
Screen = 1
[Page]Dynam-
icSizing=0

530
Chapter 18: Defining and Drawing Graphics Pages

Example Description Notes

Aspect ratio <> The window cannot

monitor - titlebar be moved.
[Animator]Full-
Screen = 1
[Page]Dynam-
icSizing=1
[Page]Main-
tainAspectRatio
=1

Page size <>

monitor - titlebar
[Animator]Full-
Screen = 1
[Page]Dynam-
icSizing=0

Aspect ratio <>

monitor
[Animator]Full-
Screen = 1
[Page]Dynam-
icSizing=1
[Page]Main-
tainAspectRatio
=1

Page size <>

monitor
[Animator]Full-
Screen = 1
[Page]Dynam-
icSizing=0

Aspect ratio <>

monitor - titlebar
[Animator]Full-
Screen = 1
[Page]Dynam-
icSizing=1
The window cannot
[Page]Main-
be moved.
tainAspectRatio
=1

Page size <>

531
Chapter 18: Defining and Drawing Graphics Pages

Example Description Notes

monitor - titlebar
[Animator]Full-
Screen = 1
[Page]Dynam-
icSizing=0

Page size at runtime

By default, a page that is displayed at runtime:
l Appears the same size as when it was saved, unless its parent (the page it was
called from) was resized.
l Displays in restored state (you can click Maximize, unless viewed in fullscreen mode
where maximize is disabled).
You can resize the page by dragging the window frame. Some options for resizing pages
may be disabled under certain screen parameter settings. See Screen examples for infor-
mation.
See Also
Sizing the Page

Securing the window title bar

You can now specify confirmation actions for standard title bar buttons (minimize, max-
imize, restore, and close) to override the standard behavior for graphic page windows by
writing a Cicode function that defines the alternative action, and specifying that Cicode
function using the appropriate OnEvent()function event code. The Cicode function needs
to return a value.
If your Cicode function returns a zero value, then the Windows message will be passed
on to the default message handler so that the window will continue to execute the
default behavior.
If your Cicode function returns non-zero, then the Windows message will not be passed
on to the default message handler.
In addition, when you call Cicode function Shutdown(), you can decide whether to
bypass the confirmation function or not.

532
Chapter 18: Defining and Drawing Graphics Pages

Defining Page Properties

You can define properties for your graphics pages.
To set up a page:

1. Open the page in the Graphics Builder.

2. Choose File | Properties.
3. Use the Page Properties dialog to define the properties for your graphics pages.
See Also
Page Properties - General
Page Properties - Appearance
Page properties - Keyboard Commands
Page Properties - Events
Page Properties - Environment
Page Properties - Associations
Setting Default Page Settings

Page Properties - General

Graphics pages have the following general properties:
Window title
The title to be displayed on the page at runtime. A window title can have a maximum
size of 64 characters.
The title can be plain text, Super Genie syntax or both e.g. "Pump ?AREA? status".
Description
Enter a description of the page, and its various functions and so on up to a maximum of
250 characters. The description is designed for comments only and does not affect how
your system performs, nor does the description appear during runtime.
Previous page
The page that will precede the current page in the runtime browse sequence (maximum
64 characters). Choose an existing page from the menu or type in a page name.
This property is optional. If you do not specify a Previous page, the Page Previous com-
mand is inoperative while this page is displayed.
Next page
The page that will follow the current page in the runtime browse sequence (maximum
64 characters). Choose an existing page from the menu or type in a page name.

533
Chapter 18: Defining and Drawing Graphics Pages

This property is optional. If you do not specify a Next page, the Page Next command is
inoperative while this page is displayed.
[Security] All areas
Select the check box if you want the page to belong to every area (the page can be seen
by any operator with view access to at least one area; see Adding user records).
[Security] Area
Enter the area to which this page belongs. Only users with access to this area can view
this page. Click the menu to select an area, or type in an area number directly. If you do
not specify an area, the page is accessible to every user.
[Page scan time] Default
The Page scan time defines how often this graphics page is updated at runtime. The
Page scan time also determines the rate of execution of the While page shown events (i.e.
the command(s) which are executed while the page is displayed at runtime).
Select this check box to use the default page scan time (as set using the [Page]ScanTime
parameter); otherwise, leave it blank, and enter (or select) another value in the field
below. For example, if you enter a page scan time of 200 milliseconds, there will be an
attempt to update the page every 200 milliseconds, and any While page shown events
are executed every 200 milliseconds.

Note: You can set the default page scan time using the Computer Setup Wizard.

[Logging] Log device

This is the device to which messages are logged for the page's keyboard commands.
Click the menu to the right of the field to select a device, or type a device name.

Note: You need to include the MsgLog field in the format of the log device for the
message to be sent.

[Cluster context] Inherit from caller

Select this check box to make the current page inherit the default cluster context from the
page or Cicode task that opened this page (for example using the PageDisplay or Win-
NewAt Cicode functions). If this is checked you cannot select a specific default cluster.
See About cluster context for more information.
[Cluster context] Cluster
Specifies a default cluster context for this page.
Click Apply, and then click OK. To define further properties for the page, select the rel-
evant tabs.

534
Chapter 18: Defining and Drawing Graphics Pages

Page Properties - Appearance

You define the appearance of your graphics pages by using the controls on the Appear-
ance tab.
Graphics pages have the following appearance properties:
[Template] Style
The style (appearance) of the graphics page in the runtime system. You can set a default
style (to be applied to new pages) using the page defaults of existing pages and tem-
plates using the Page Properties.
Most users prefer the Standard style. You can view the pre-defined styles by looking in
the Include project under Graphics, Templates.
[Template] Resolution
The default screen resolution of the pages:

Screen Type Width (pixels) Height (pixels)

VGA 640 480

SVGA 800 600

XGA 1024 768

SXGA 1280 1024

User

[Template] Name
The name of the template on which the page is based. Choose a template name from the
menu.

Note: If you are looking for a template that you created yourself, check that you
entered the correct Style and Resolution above.

[Template] Show title bar

535
Chapter 18: Defining and Drawing Graphics Pages

Determines whether the Windows title bar displays (at the top of the 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.
[View area] Width
The width (in pixels) of the area that the operator can view at runtime. Click the up and
down arrows to increase and decrease the width, or type in another value directly.
[View area] Height
The height (in pixels) of the area that the operator can view at runtime. Click the up and
down arrows to increase and decrease the height, or type in another value directly.
Page color
The color that will display in the background of the graphics page.
The preview field to the right of this dialog displays a picture of the selected template.
Click Apply, then click OK. To define further properties for the page, click the relevant
tabs.
Ignore Quality
This field allows you to override the global [Page]IgnoreValueQuality parameter setting
in the Citect.ini file for a particular page.
The options are:
l Default Indication - use the current setting for the [Page]IgnorevalueQuality param-
eter setting in the Citect.ini file.
l #COM Indication - change the setting to the equivalent of 0 for the [Page]Ignore-
valueQuality parameter setting in the Citect.ini file.
l No Indication - change the setting to the equivalent of 1 for the [Page]Ignore-
valueQuality parameter setting in the Citect.ini file.
l Background Indication - change the setting to the equivalent of 2 for the [Page]Ignore-
valueQuality parameter setting in the Citect.ini file.
See Also
Defining Page Properties

536
Chapter 18: Defining and Drawing Graphics Pages

Page properties - Keyboard Commands

The Keyboard Commands property lets you define keyboard commands for the page. A
keyboard command is a particular key sequence which executes a command when it is
typed in by the operator at runtime.
You can also define a message which will log every time the key sequence is entered.
Operators who do not satisfy the Access requirements specified under Security below
cannot enter keyboard commands for this page at runtime.
Keyboard commands have the following properties:
Key sequence (32 Chars.)
Enter the key sequences that the operator can enter to execute a command.
You can enter as many key sequences as you like. To add a key sequence, click Add, and
type in the sequence or select one from the menu. To edit an existing sequence, click the
relevant line, and click Edit. You can also remove key sequences by clicking Delete.
Key sequence command
The commands (set of instructions) to be executed immediately when the selected key
sequence is entered. The key sequence command can have a maximum length of 254
characters.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag, and Insert Function.
[Security] Same area as page
Select this check box to assign the keyboard command to the same area as the page (see
Page Properties - General). Only users with access to this area (and any necessary priv-
ileges) can issue this command or log the message. If you want to assign this keyboard
command to another area, do not select this box: enter another area below.
[Security] Command area
Enter the area to which this keyboard command belongs up to a maximum of 16 char-
acters. Only users with access to this area (and any necessary privileges) can issue this
command or log the message. For example, if you enter Area 1 here, operators need to
have access to Area 1 to issue this command.
Click an area from the menu or type in an area number.
[Security] No privilege restrictions
Tick this box to disable privilege restrictions; otherwise, leave it blank, and enter another
privilege below.

537
Chapter 18: Defining and Drawing Graphics Pages

The result of not assigning a privilege restriction differ according to whether you have
used areas in your security setup:
l No Areas: Every operator has full control of the page.
l Areas: An operator will only need view access to the area assigned to this page to
have full control over the page (see Adding user records).
[Security] Privilege level
Enter the privilege level that a user needs to possess to issue this command or log the
message. For example, if you enter Privilege Level 1 here, operators need to possess Priv-
ilege Level 1 to issue this command. You can also combine this restriction with area
restrictions (see above). For example, if you assign the keyboard command to Area 5,
with Privilege Level 2, the user needs to be set up with Privilege 2 for Area 5 (see Add-
ing user records).
Choose a privilege from the menu or type in an area number.
[Logging] Log Message
A text message sent to the MsgLog field of the Log Device when the selected action is per-
formed by the operator at runtime (32 characters maximum). The message can be plain
text, Super Genie syntax, or a combination of the two.
If you want to include field data as part of a logged message, you need to insert the field
name as part of the device format when you configure the device. For instance, in the
Format field of the Devices form, you could enter {MsgLog,20} {FullName,15}. This
would accommodate the logging of messages such as P2 started by John Smith.
The log device to which the message is sent is specified through the General page prop-
erties.
Click Apply, and then click OK. Click Clear Property to clear property details, and dis-
able the property. To define further properties for the page, click the relevant tabs.
See Also
Defining Page Properties

Page Properties - Events

You use the Events tab to assign commands to your graphics pages. These commands
can be executed when the page is opened, closed, or whenever the page is open. You can
also define different messages to log at the same time.
Page events have the following properties:
Event

538
Chapter 18: Defining and Drawing Graphics Pages

There are three events to which commands can be attached. You can select more than
one type of event. Unique commands can be attached to each (i.e., you can perform one
task when the page is opened, and another when it is closed).
[Event] On page entry
Select this option if you want a command to be executed when the page is initializing.
For example, you could execute a command to extract recipe data from a database into a
Cicode variable, to be displayed on the page.

Note: Use the "On Page Shown" event if your command uses ActiveX controls. The
"On page entry" event may not properly initialize ActiveX controls. The resulting
value from a tag write that is perfomed using the "On page entry" event may not be
displayed and accessed correctly if the tag is used directly within the page. The "On
page shown" event can be used for initializing tags that are to be accessed on the
page.

[Event] On page exit

Select this option if you want a command to be executed when the operator exits the
page. For example, this command could be used to close a database that was opened at
page entry.
Do not call the following functions: PageGoto(), PageNext(), PagePrev(), PageDisplay(), or
PageLast().

Note: If you shut down the system, "On page exit" functions for the currently open
pages do not execute. If a particular page exit code needs to run, call the code before
calling the Shutdown() function.

[Event] While page is shown

Select this option if you want a command to execute continually for the entire time that
the page is open. For example, the While page is shown command could be used to per-
form background calculations for this page.
[Event] On page shown
Select this option if you want a command to execute when a page is first displayed and
objects on it (including ActiveX controls) have been initialized. If you want to reference
ActiveX controls in your command then use this event instead of "On page entry".

539
Chapter 18: Defining and Drawing Graphics Pages

Notes:
1. Use the "On Page Shown" event if your command uses ActiveX controls. The "On
page entry" event may occur before the ActiveX controls have been initialized.
2. Use the "On Page Shown" event if your command requires access to the latest var-
iable tag value. The "On page entry" event may occur before the tag has been
resolved.

Page Properties - Environment

You use the Environment tab to define environment information for your graphics
pages. You can add, remove, or edit page environment variables for a graphics page,
template, or Super Genie.
For example, you can design your loop pages to expand when clicked (a Tune >> but-
ton) to show tuning parameters. You can use the environment variable to define the size
of the expanded window. The DspGetEnv() function would be used as part of the Cicode
for the button that expands the window. This means that the Cicode used to expand the
window can be generic: you can use the same Cicode each time.
From CitectSCADA 7.20, environment variables are propagated from Super Genie tem-
plates to Super Genie pages automatically. Refer to Environment variables in 7.20 for
more information.
Variables
The environment variables to be added to the page. When the page is opened during run-
time, these variables are created. Their values can then be read using the DspGetEnv()
function. When the page is closed, the environment variable memory is freed (dis-
carded). For the example above, you would add one variable to define the width of the
page, and another to define the height.

540
Chapter 18: Defining and Drawing Graphics Pages

To add an environment variable, click Add. To edit an existing environment variable,

select it, and click Edit. (If you click Add or Edit, a small dialog appears, containing two
fields, one for the property and one for its value.) To remove an environment variable,
select it, and click Remove.
See Also
Defining Page Properties

Page Properties - Associations

An association is the name or number you use when defining a Super Genie sub-
stitution, the value or values of which are dynamically generated at runtime.
Use this tab to reference or edit existing associations. In using this tab you can add those
associations that are currently in use in a Super Genie substitution and define the appro-
priate default value and value on error fields. You can also add a description.
Double-click in the row to make it editable, or Click Add.
Name:

Note: On upgrading from an earlier version of CitectSCADA existing numbered sub-

stitutions are taken from defined Super Genie pages and automatically listed in the
drop down box.

For new associations enter the name or number of the association directly in the field
provided, or select the name or number of the association from the drop-down box. Only
those associations that are ‘in-use’ as part of a Super Genie substitution are listed.For
example, if the substitution in the expression field of a button was‘?Speed?’ then the
association name is Speed.
Name Associations:
l To start with an alphanumeric or “_” character
l To contain only those characters that are allowed in variable tag names (excluding
the period character ‘.’), and not contain any white space.
l Be no more than 253 characters in length
Default (optional)
Enter the default value to be used if the page association has not been performed using
one of the Ass() Cicode functions at runtime. The default value needs to be either a literal
string constant enclosed in single quotes (e.g. <'a literal value'> or <'1.23'>) or a valid tag
name.
Value on Error (optional):

541
Chapter 18: Defining and Drawing Graphics Pages

Enter the text to be used if no default value is defined and the association is not per-
formed, or if the defined association did not resolve to a valid tag name. Since the value
on error cannot be a variable tag, it is not necessary to enclose the text in quotation
marks.
If the substitution on the page is specified in a typed format, the value will be converted
to the specified type. If the value cannot be converted a hardware alarm will be raised.
For example, if the substitution is specified as ?INT AlmDesc? and the value on error is
set to <LowLevel>, the animation will display zero (0) and a hardware alarm will be
raised. Typeless substitutions such as ?AlmDesc? will display the value on error as spec-
ified.
Description (optional):
Enter a description of the page association. The description is useful when maintaining
associations.
In Use:
This column can not be edited and simply indicates if the association is in use on the
current page in a Super Genie substitution.
When finished click Add, the association is then added to the table.
To edit an association select an item and click Edit or double-click on the row to make it
editable. You can not edit the name of an existing association that is in use. However
you can select a new name in an existing row, and when this name is <ENTERED>, a
new row of information will be displayed and the existing row of data will disappear.
To delete an association select the row in the table and click Delete. You can delete asso-
ciations in use or not in use. If you delete the object from the page, the status of the asso-
ciation used in the Super Genie substitution will be updated to not in-use.
Click Ok or Apply to save the association table or click Cancel to discard any changes
you may have made.
See Also
Defining Page Properties
Passing Metadata as Super Genie Assoications
Defining Associations for Super Genies
Defining Substitutions for Super Genies
Constants

Setting Default Page Settings

You can define settings that new graphics pages will use.
To set the properties to be used for new graphics pages:

542
Chapter 18: Defining and Drawing Graphics Pages

1. Choose File | Defaults.

2. Complete the Page Defaults dialog box, then click OK.
See Also
Page defaults

Page defaults
You use the Page Defaults dialog box to define the screen resolution and style that graph-
ics pages will use.
You can override these defaults for your pages when you create them or edit them.
[Template] Resolution
Default screen resolution of the standard graphics pages (for example, alarms pages and
standard trend pages):

Screen Type Width (pixels) Height (pixels)

VGA 640 480

SVGA 800 600

XGA 1024 768

SXGA 1280 1024

User

[Template] Style
The style (appearance) of the graphics pages in the runtime system. The style you select
is the default style for new pages you add to the project. You can change the style of
existing pages and templates using the Page Properties.
Most users prefer the Standard style. You can view the pre-defined styles by looking in
the Include project under Graphics, Templates.
[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).

543
Chapter 18: Defining and Drawing Graphics Pages

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
You can override this default for your own pages at the time you create them, or later.
Background color
The color that will display in the background of new graphics pages.
Preview
This dialog also displays a preview of your page with the defaults applied.

Understanding the Drawing Environment

The Citect Graphics Builder is a feature-rich drawing environment that lets you develop
a highly functional interface for your projects.
See Also
Grids
Guidelines
Options
Colors
Zooming

Grids
You can use a grid to align and place objects with precision. When the grid is active,
any objects or groups of objects that you create, move, or re-size snap to the nearest grid
intersection.
To display the grid:

1. Choose View | Grid Setup.

2. Click the Display Grid check box.
To snap to the grid:

l Choose View | Snap to Grid.

By default, the grid is set to 8 x 8 pixels, with the origin located at the top-left corner of
your page.
To change the default grid size and location:

l Choose View | Grid Setup. The Grid Setup dialog box appears.

544
Chapter 18: Defining and Drawing Graphics Pages

Grid Setup dialog box

This dialog box lets you define the origin and pitch (spacing) for Grids. The grid allows
you to align and place objects precisely.
Pitch
The horizontal and vertical spacing of the grid points (in pixels). The smallest grid size
you can specify is 3 x 3 pixels.
Origin
Specifies the grid origin (base point).
Display Grid
Displays the grid on screen.
Snap to Grid (F8)
Activates the grid. When the grid is active, any object or group of objects that you create,
move, or re-size snaps to the nearest grid intersection.

Guidelines
You can use horizontal and vertical guides as a straight-edge, to align and place objects
precisely. When an edge or the center of an object gets close to a guide, that edge or
center automatically snaps to the guide.
To set up guidelines:

1. Choose View | Guidelines Setup.

2. To run the guideline horizontally across your page, click Horizontal.
3. Enter a position (distance from the top of your page) for the guideline, and click Set.
4. To run the guideline vertically down your page, click Vertical.
5. Enter a position (distance from the left edge of your page) for the guideline, and click
Set.
6. Click the Display Guidelines check box.
7. Click the Snap to Guidelines check box.
8. Click OK.
To turn off guidelines:

l Choose View | Snap to Guidelines.

545
Chapter 18: Defining and Drawing Graphics Pages

To move a guideline:

1. Move the cursor over the guideline.

2. Click and hold the left mouse button.
3. Move the guideline to a new location.
4. Release the mouse button.
To create a new guideline with the mouse:

1. Move the cursor over the guideline.

2. Press and hold the Ctrl key.
3. Click and hold the left mouse button.
4. Move the guideline to a new position.
5. Release the mouse button and Ctrl key.
To delete a guideline with the mouse:

l Drag the guideline to the edge of the page.

Guidelines Setup dialog box

This dialog box lets you define 32 horizontal and 32 vertical Guidelines. Guidelines act
as a straight-edge, allowing you to align and place objects precisely. When an edge or
center of an object gets close to a guide, that edge or center automatically snaps to the
guide.
Direction
The direction of the guideline (horizontal or vertical).
Display Guidelines
Displays the guidelines on screen.
Snap to Guidelines (F7)
Activates the guidelines. When the guidelines are active, any object or group of objects
that you create, move, or re-size snaps to the nearest guideline.

Options
You can define general options for your drawing environment.
To define general options for the drawing environment:

546
Chapter 18: Defining and Drawing Graphics Pages

1. Choose Tools | Options. The Options dialog box appears.

2. Enter the relevant details.

Option Description

Display Enables the automatic display of the relevant properties dialog when you
Prop- add an object to the page.
erties on
New

Display Enables the automatic display of the relevant properties dialog when you
Prop- copy an existing object on the page.
erties on
Copy

Save Tem- Enables the display of an alert message when you modify and then save an
plate existing template. When you modify an existing template, any graphics
Warning pages that are associated with the template are not updated until you per-
form an Update Pages to update each page based on the template.

Modify Allows you to modify the number of the animation point (AN) of any object.
AN Field You cannot change an AN to the same number as an existing AN on the
graphics page.

Disable Disables the display of Genie forms when a new Genie is added to the page
Genie or an existing Genie is edited. With Genie forms disabled, a form for each
Forms native object in the Genie displays.

Display Enables the display of a group button on a Genie dialog. The group button
Group displays a form for each native object in the Genie.
Button

Compile Enables the "Do you want to compile?" message window when the project
Enquiry has been modified and Run is selected. Normally the project is compiled
Message automatically (if the project has been modified) when Run is selected.

Fast Run- Enables the fast display of graphics pages in the runtime system.
time Dis-
play

List Sys- Specifies that system pages will be included in:

tem
Pages l The list of pages in the Graphics Builder Open and Save dialog boxes.
l The Page Properties Previous and Next menus, used for defining a
browse sequence for your pages.
l The list of files in the Contents area of Citect Explorer.
System pages are prefixed with an exclamation mark (!).

Show ver- Enables the old (version 3 and version 4) toolbox. This toolbox contains old
sion tools (such as Slider and Bar Graph), which are no longer necessary, as

547
Chapter 18: Defining and Drawing Graphics Pages

Option Description

3.xx/4.xx they can be configured using the Object properties.

tools

Fast Affects the operation of Graphic Builder's "Update Pages" tool. If Fast
Update Update Pages is checked, Graphics Builder only updates modified pages. If
Pages not checked, every project page is updated.

Trans- Allows you to specify a color that becomes transparent when a bitmap is
parent pasted on a graphics page. This applies to bitmaps that are pasted from the
Paste clipboard, or imported from another application.

Note: Transparent data bits are not natively supported by other appli-
cations. If pasting a bitmap into an external application, transparent bits
will appear as the transparent paste color.

ActiveX Lets you save graphics pages before inserting an ActiveX control. This
Auto- guards against the loss of data if you insert custom-built ActiveX controls
matic which cause the Graphics Builder to stop operating normally. With Auto-
Page Sav- matic Page Saving enabled, if inserting an unstable ActiveX control causes
ing such an event, you minimize the likelihood of losing work. When you reopen
the Graphics Builder, you can normally recover the saved page.

The options are:

l Save page before inserting ActiveX controls: The graphics page

is automatically saved with the current page name.
l Prompt before saving: A query will display, asking if you want to
save the page before inserting an ActiveX control.
l Do not save automatically: The graphics page is not saved auto-
matically, and the query is not displayed.

3. Click OK.
See Also
Options

Colors
True Color (16.7 million colors) is supported for static and animated objects, including
page backgrounds, imported images, symbols, metafiles and bitmaps.
Wherever a particular page or object property has a color value, a current color button
will appear.
To choose a different color to the one currently displayed on the button, click on the
small black arrow to the right. This launches the Color Picker.

548
Chapter 18: Defining and Drawing Graphics Pages

Color Picker
The first 11 rows of the Color Picker show a set of standard colors, including transparent
(marked with a black cross). The remaining rows display any user defined colors,
referred to as Color Favorites. This includes flashing colors, represented by a two color
block, divided diagonally.
To select one of the colors displayed on the color picker, click on it.
If the necessary color does not appear, you have the option to create a custom color, or
match an existing color from one of your graphics pages.
To match an existing color on a graphics page:

1. Verify that the color you would like to match is present on the page currently dis-
played in Graphics Builder.
2. From the Color Picker, choose the Color Selector tool (looks like an eyedropper).
3. Use the Color Selector to click on the color you would like to match.
4. The color you have chosen will now appear in the Color Value Display button.
To create a customized color:

1. From the Color Picker, click on the Edit button. This will make the Edit Favorite Color
dialog appear.
2. Use the Edit Favorite Color dialog to create the color you would like to use (See Edit
Favorite Colors dialog box for details).
3. Name the color if necessary.
4. Use the Add button to include the color with the Color Favorites displayed on the
Color Picker.
5. Click OK. The color you have just created will now be selected.
See Also
Edit Favorite Colors dialog box
Swap Color dialog box
Adjust colors dialog box

Edit Favorite Colors dialog box

With the Edit Favorite Colors dialog box, you can:
l Make a visual selection of a color you would like to use by clicking on the color
wheel.
l Decide the brightness level for a color by clicking on the brightness bar.
l Create a color by entering hue, saturation and luminance values.

549
Chapter 18: Defining and Drawing Graphics Pages

l Create a color by entering red, green and blue color values.

l Modify the colors available on the Color Picker by adding, replacing and removing
colors on the color grid.
l Name a color, allowing it to be identified on the color grid via a tool tip.

The Edit Favorite Colors dialog contains the following elements:

Colors Grid
Displays a selection of predefined colors. The first 11 rows show a set of standard colors,
including transparent (marked with a black cross). The remaining rows display the user-
defined colors currently added as favorites. This includes flashing colors, represented by
a two color block, divided diagonally.
The colors that appear in this grid represent those that are available from the Color
Picker.
Add
Adds the color currently displayed in the Color panel to the user-defined favorites in the
color grid. If there are no places available on the grid, you will have to use the Replace
or Clear button instead.
Replace
This button allows to you alter a color on the color grid. Select the color you would like
to change, adjust its color value, and then hit the Replace button. The selected color will
be updated to reflect the changes that were made.

550
Chapter 18: Defining and Drawing Graphics Pages

Clear
Removes the selected color, leaving an "unused" position on the color grid.
Name
Allows you to associate a name with a predefined color. The name can be viewed as a
tool tip in the Color Picker, making it easy to distinguish a specific color among similar
shades.
You can associate a name with a newly created color by typing in a name before clicking
the Add button. You can also apply a name to an existing color by selecting the color,
keying in a name and clicking the Replace button.

Note: The pre-defined color labels are already defined as color names.

Color
The Color panel displays the color created by the current settings applied to the Edit
Favorite Color dialog.
The values displayed on the Edit Favorite Color dialog automatically adjust to correctly
represent the color currently displayed in this panel. The values in each field are not
independent.
Color wheel
The color wheel allows you to visually select a color. It represents the full spectrum of
colors in a cyclic layout, with color saturation increasing towards the outside edge.
Simply click on the wheel to select a color.
Brightness bar
Allows you to visually select the brightness you would like applied to a color. Click on
the bar in the appropriate location to apply a brightness level. The bar represents lumi-
nance, as the colors move away from pure black as they progress up the bar to pure
white.
Hue
Specifies the hue value for the color currently displayed in the Color panel. Hue pri-
marily distinguishes one color from another. The value can be between 0 (zero) and 359,
representing degrees around the color wheel. For example, zero is a pure red to the right,
180 is pure cyan on the left.
Sat
Specifies the saturation level for the color currently displayed in the Color panel. Sat-
uration level increases the further the selected color moves away from gray scale to a
pure primary color. The value can be between 0 (zero) and 255.
Lum

551
Chapter 18: Defining and Drawing Graphics Pages

Specifies the luminance of the color currently displayed in the Color panel. Luminance
represents the brightness of a color, the value increasing the further the color moves
away from black towards pure white. The value can be between 0 (zero) and 255.

Note: When you create a color by using HLS values, you may find that the HLS
values you specified for a color have changed when you reopen the dialog box. This
happens because RGB values are less precise than HLS values, sometimes resulting
in several HLS values being assigned the same RGB value. As a result, when the
HLS values are generated from the RGB values, some values may change.

Red
Indicates the amount of red used to create the color currently displayed in the Color
panel. The value can be between 0 (zero) and 255. Adjust this setting if you want to
create a color using RGB values.
Green
Indicates the amount of green used to create the color currently displayed in the Color
panel. The value can be between 0 (zero) and 255. Adjust this setting if you want to
create a color using RGB values.
Blue
Indicates the amount of blue used to create the color currently displayed in the Color
panel. The value can be between 0 (zero) and 255. Adjust this setting if you want to
create a color using RGB values.
Transparent
Click this button to select transparent. Wherever transparent is used as a color, the back-
ground color, or color behind the transparent object, will be displayed.
Flashing
Check this box if you want to create a flashing color. A flashing color appears as a dia-
gonally divided panel in the color grid. To create a flashing color, you will have to select
an On State and Off State color.

Swap Color dialog box

You use the Swap Color dialog box to swap the colors of an object (or group of objects, or
a bitmap) to new colors.

Note: You may find that you get unexpected results when swapping colors in your
bitmaps if they contain areas that have either very high or very low luminance

552
Chapter 18: Defining and Drawing Graphics Pages

values (that is, white or black areas). This is due to the fact that these areas contain
almost no color, only luminance. For example, areas that represent specular high-
lights (the shine on a brightly illuminated steel conveyor belt, for example) will
remain colorless no matter how the color for the rest of the bitmap is adjusted. Con-
sequently, before working with the Swap Color dialog box and other color tools,
familiarize yourself with the concepts of hue, luminance, and saturation in order to
avoid unexpected results with the images on your graphics pages.

From
The current color of the object. If you click the Swap range check box, it presents a range
of colors in varying degrees of brightness ranging from white to black. Any colors in this
range that exist in the object are replaced by the corresponding colors from the To range
as follows:

To
The color the original object color will be changed to. If you click the Swaprange check
box, it presents a range of colors in varying degrees of brightness from white to black.
This allows you to swap a whole range of colors at once.
From any color
Specifies to change every color in the object to the new color.
Swap range
Specifies to swap a range of colors. The From and To boxes indicate the starting colors
in the ranges.

Note: You cannot invert colors with Swap Range selected. This means, for example,
that you could not swap dark red for light green and light red for dark green in one
go.

553
Chapter 18: Defining and Drawing Graphics Pages

Adjust colors dialog box

The Adjust Colors dialog allows refined color re-mapping with Graphics Builder objects.
Hue (degrees)
The Hue area allows the user to set the color hue range to map to and from. The bars dis-
played span values of 0 (zero) to 359 degrees, representing the cyclic nature of hue color
values. A numeric value for each slider can be keyed in to the field to the right.
l The slider above the From Hue Range bar selects the start of the color range that will
be mapped.
l The slider below the From Hue Range bar selects the end of the color range to be
mapped.
l The slider above the To Hue Range bar selects the start point for the color range
you'll be mapping to. Because the value range is cyclic, the selected area can wrap
around to the left side of the bar.
The range of colors that is excluded by your selection is grayed out, allowing for a visual
assessment of the selected range.
Lightness (%)
The lightness slider allows you to boost the lightness of colors across a range of (neg-
ative) - 100% to 100%. If the slider is increased above zero, colors will tend towards
white. If the slider is set below zero, colors will move towards black. A numeric value
for the slider can be entered into the field to the right.
The Selected Hues Only check box applies the lightness setting to only those colors that
will be remapped. Leaving the box unchecked allows the lightness to be adjusted for
every color.
Saturation (%)
The saturation slider allows you to boost the saturation of color across a range of (neg-
ative) -100% to 100%. If the slider is increased above 0, colors will tend towards primary
colors. If the slider is set below zero, colors will move towards grayscale. A numeric
value for the slider can be entered into the field to the right.
The Selected Hues Only check box applies the saturation setting to only those colors
that will be remapped. Leaving the box unchecked allows saturation to be adjusted for
every color.

554
Chapter 18: Defining and Drawing Graphics Pages

Zooming
Use the Zoom command to view an enlarged view of your drawing. The Zoom com-
mand displays a zoom box on screen that magnifies the area around your cursor, ena-
bling you to position or draw objects precisely.

Procedure Description

To display the Choose View | Show Zoom.

Zoom box

To hide the Zoom Double-click the control menu box (on the Zoom box) or choose
box View | Show Zoom.

You can change the cursor into crosshairs that extend the full width and length of the
drawing area. When you move away from the drawing area, the normal pointer reap-
pears, allowing you to select commands and tools.

Procedure Description

To toggle the cursor between a crosshair Choose View | Cross Hair Cursor.
cursor and a pointer

To hide the status bar Choose View | Show Status Bar.

Choose the command again to redisplay
the status bar.

To hide the Toolbox Double-click the control menu box (on the
Toolbox) or choose View | Show Tools.
Choose the command again to redisplay
the Toolbox.

To hide the toolbar Choose View | Show Tool Bar. Choose

the command again to redisplay the tool
bar.

To change the speed of the cursor when Choose View | Mouse Slow Speed.
using the mouse

To change the speed of the cursor when Choose View | Cursor Keys Slow
using the cursor keys Speed.

Hint: Move the cursor on screen by using

the left, right, up, and down cursor keys.

555
Chapter 18: Defining and Drawing Graphics Pages

Using libraries
You can store frequently used objects or groups of objects (including bitmap objects) in a
library as symbols. You can then paste these symbols onto your page.
After you paste a symbol from the library onto a graphics page, it can be moved, re-
sized, re-shaped, brought to the front, and its properties can be edited, just like any other
type of object.
You can define Metadata for a pasted symbol and on the separate animation points that
make up that symbol. Each of these animation points will have different ANs. Access to
this metadata is obtained through its corresponding AN.
You can paste a symbol from the library to the page:
l As an unlinked symbol; the pasted symbol is not updated with changes to the sym-
bol in the library.
l As a linked symbol; the symbol on the page is updated when the symbol in the
library is changed (to alter the properties of a symbol in the library, open the library
and edit it in the library). If you edit the symbol from the page and then change the
source symbol in the library, the pasted symbol changes. For example, if you double
the size of a pasted symbol, then double the size of the symbol in the library, the
pasted symbol doubles again. You can cut the link to the library by using the Edit |
Cut Link command.
When you save an object in a library, the current properties of that object are saved with
it. When you paste it as a symbol to a graphics page, they are used as defaults for the
symbol. Pasted symbols have different Appearance properties to those of normal objects:
you can only specify a visibility property.
When a symbol is pasted onto a page, the objects that form the symbol cannot be
accessed from the page by double-clicking the symbol. To display the properties of these
objects, hold the Control (CTRL) key down and double-click the specific object. Alter-
natively, you can select Goto Object from the Tools | the group, and click OK. However,
if the link to the library is retained, most of these properties are read-only.
A symbol would be useful, for example, if you have defined a command button with a
particular security classification, and you need to use it on quite a few graphics pages.
You could save it as a symbol, and each time you want to use the button, paste it from
the library. Each time it is pasted, it will have the same properties.

Note: There is a comprehensive range of symbols that you can use in your project(s).
These symbols are stored in several libraries in the "Include" project. When a library
is saved, the first eight characters of the library name needs to be unique to that

556
Chapter 18: Defining and Drawing Graphics Pages

library.

Copying an object to the library

You can copy an object to the library so that you can use it later on other graphics pages.

To copy an object to the library (i.e. make it a symbol):

1. Click Select.
2. Select the object (or group of objects).
3. Choose Edit | Copy to Library. The Copy To dialog box appears.
Copy To dialog box
This dialog box lets you copy an object (or group of objects) to the library as a symbol.

Feature Description

Symbol A name for the symbol.

Library The project library where the symbol is stored.

Project The project where the library is stored.

Preview Enable Displays a thumbnail image of the symbol.

Note: To edit the symbol, select it and click Edit. To create a new symbol, click New.

New Library dialog box

This dialog box lets you create a new library for the symbol, Genie, or Super Genie (32
characters maximum). Enter a new Name for your new library. (The first eight char-
acters of the library name needs to be unique to this library.)

Using symbols
You can create symbols to use on your graphics pages.
To create a new symbol:

1. Click New, or choose File | New.

2. Select Type: Symbol

557
Chapter 18: Defining and Drawing Graphics Pages

Note: You can also create an object (or group of objects on the page) and then choose
Edit | Copy to Library.

To open an existing symbol:

1. Click Open, or choose File | Open.

2. Select Type: Symbol.
3. Select the Project where the library is stored.
4. Select the Library where the symbol is stored.
5. Select the symbol you want.
6. Click OK.

Note: To delete a symbol from the library, select the symbol name and click Delete.

To save the current symbol:

1. Click Save, or choose File | Save.

2. Select the Project in which the library is stored.
3. Select the Library in which the symbol is to be stored.
4. Enter a name for the symbol.
5. Click OK.
For details on using symbols on graphics page, see Pasted Symbol Objects.

Bitmaps
A bitmap image is a drawing object represented as an array of pixels (or dots), rather
than as individual entities. A bitmap is treated as a single object that you can move,
copy, and reshape. Because you can edit individual pixels in a bitmap, you can use bit-
maps for vignettes and image blending.
You can create bitmaps with the Bitmap Editor, or import bitmaps from any other Win-
dows-based bitmap editor.
In a runtime system, bitmaps are displayed differently to other objects. Bitmaps are
mapped directly to the screen (that is, each pixel in the image corresponds to a pixel on
the screen). Objects are stored as a series of instructions, and are drawn on the screen in
the same order as they were drawn on the graphics page.

558
Chapter 18: Defining and Drawing Graphics Pages

The Bitmap Editor

You use the Bitmap Editor to create and edit bitmap images. You can use bitmap images
on your graphics pages, and as animated symbols.
The background color in the Bitmap Editor is always transparent, indicated as a white
pixel with a black dot at the center. To draw with the background (transparent) color,
click (and hold) the right mouse button.
Flashing colors are represented by a diagonally split pixel, indicating the on-state and
off-state colors used.
The tool bar of the Bitmap Editor has the following buttons:

Exits the Bitmap Editor and saves editing changes.

Exits the Bitmap Editor and discards changes.

Zooms in on the image.

Zooms out on the image.

Selects a color from the image to set as the current color (keyboard shortcut is
Shift+P). You can also select the current color from the color swatch.

Displays the Bitmap Size dialog box where you can view the image's current
dimensions and edit the image's edge.

To resize a bitmap:

1. In Graphics Builder, click the bitmap.

2. Choose Tools | Bitmap Editor, or press F9.
3. Click Resize. The Bitmap Size dialog box appears.
4. Select a mode. Click Grow to enlarge the image, or Shrink to reduce it.
5. For each side of the bitmap, specify how many pixels you want to add or remove,
then click OK.
To set a color from a bitmap as the current color:

1. In Graphics Builder, click a bitmap.

2. Choose Tools | Bitmap Editor, or press F9.
3. Click Eye Dropper, and then click a color in the image. The selected color becomes
the current color, and is used when you click elsewhere on the image.
To convert an object (or objects) to a bitmap:

559
Chapter 18: Defining and Drawing Graphics Pages

1. Select the object(s).

2. Choose Tools | Convert to Bitmap.

Note: The Convert to Bitmap operation is only supported in 8-bit (256) color mode.

To invoke the Bitmap editor:

l Choose Tools | Bitmap Editor.

To paste a bitmap (from another application):

1. Create the image in an external application.

2. Use the external application's copy command to copy the image to your computer's
clipboard.
3. Switch to the graphics builder.
4. Choose Edit | Paste.
You can edit pasted bitmaps by selecting the object and then choosing Edit | Properties.
To import a graphic:

1. Choose File | Import. The Import dialog box appears.

2. Select the file you want to import by using the Import dialog box.
3. Click OK (or click the file that you want to import and drag it onto a page in Graph-
ics Builder.
You can edit imported bitmaps by selecting the object and then choosing Edit | Prop-
erties.
To import a flashing graphic:

1. Choose File | Import as Flashing. The Primary Import dialog box appears.
2. Select the first file you want to use for your flashing image.
3. Click OK. The Flashing Import dialog box appears.
4. Select the second file you want to use for your flashing image.

Import dialog box

You use the Import dialog box to import a graphic produced with a different application.
If you have selected Import as Flashing, two Import dialog boxes appear in sequence,
allowing you to choose two images that you want to implement as a flashing symbol.
The Import Primary dialog allows you to select the initial image used; the Import Flash-
ing dialog allows you to choose the second images used.
Look in

560
Chapter 18: Defining and Drawing Graphics Pages

The drive and directory where the graphic is stored.

File Name
The name of the graphics file.
Files of Type
The type of graphics file. The following file formats are supported:
l Windows 3.0 bitmaps (*.BMP, *.DIB, *.RLE)
l PCX format bitmaps (*.PCX)
l Text files (*.TXT)
l AutoCAD DXF Files (*.DXF), 2D only. The binary format is also supported.
l Windows metafiles (*.WMF)
l Encapsulated Postscript (*.EPS)
l Fax Image (*.FAX)
l Ventura Image (*.IMG)
l JPEG (*.JPG, *.JIF, *.JFF, *.JGE)
l Photo CD (*.PCD)
l Portable Network Graphic (*.PNG). (PNG files with alpha channels are not sup-
ported.)
l Targa (*.TGA)
l Tagged Image Format (*.TIF)
l WordPerfect (*.WPG)

561
Chapter 18: Defining and Drawing Graphics Pages

562
Chapter 19: Using Objects
Objects are basic drawing entities that you add to your graphics pages. Objects are
drawn using the tools in the drawing toolbox, and can be moved, reshaped, or copied
after they are drawn. Objects are defined by a set of properties, which are assigned when
the object is drawn, or afterwards, by double-clicking (these properties will override any
conflicting Cicode Display functions).
Most objects can be assigned keyboard commands and access rights, and can be con-
figured in such a way that they change dynamically at runtime when an expression
returns a certain value, or a variable tag changes state. They can even be used as sliders
to change the state of a variable.

Note: If an object is part of a group, part of a pasted Genie or symbol, or part of the
page's template, you can still access its properties. Simply hold down the Control
(CTRL) key and double-click the object. Alternatively, choose Tools | Goto Object,
click the object, and then click OK. However, if there is still a link to the original
Genie/symbol/page template, the object properties are mostly read-only.

Each type of object has its own tool:

Free Hand Line Objects Straight Line Objects

Rectangle Objects Ellipse Objects

Polygon Objects Pipe Objects

Text Objects Number Objects

Button Objects Symbol Set Objects

Trend Objects Cicode Objects

Pasted Symbol Objects Pasted Genie Objects

ActiveX Objects "Process Analyst Objects" in the Process

Analyst User Guide

563
Chapter 19: Using Objects

Database Exchange Con- Pelcro Camera Support

trol Objects

See Also
Using groups
Reshaping objects
Using bitmaps
Importing graphics

Using groups
You can group multiple objects. A group has a unique set of properties (much the same
set as an object) which determine the runtime behavior of the group as a whole. (The
properties of the individual objects in the group remain unchanged.) By defining group
properties, you can specify that the entire group changes dynamically under specific run-
time conditions (for example, when an expression returns a certain value, or a variable
tag changes state).
To edit or view the properties of a group, double-click it. If there are several groups on
your page, choose Tools | Goto Object. This allows you to see which groups and objects
are on your page, making it easier for you to select the object you want to edit. It also
allows you to display the properties of the objects (or groups) that make up the group.
(You can also edit the properties of an object in the group by holding down the Control
(CTRL) key and double-clicking the object. Alternatively, select Goto Object from the
Tools menu, select the object, then click OK.) This is useful if your page has groups
within groups.
A group can be a mix of objects and other groups.

Note: With the release of CitectSCADA 7.30 objects in hidden groups are no longer
visible. For further details, refer to Object Properties - Access (Disable).

Reshaping a line object

Line objects also have nodes, but behave in a more restricted manner than Pipe, Poly-
line, or Polygon objects.
A straight line can only consist of two nodes, (a start node point and an end node point).
These can be individually selected to move the line to a different position, or at least
change its direction. The Line object does not support node adding. To achieve the same
result as adding a node to a Line object, create a Polyline object instead. Deleting either
of the (only two) nodes of a Line object will delete the whole Line object completely.
See Also
Using bitmaps

Using bitmaps
A bitmap image is a special object, represented as an array of pixels or dots, rather than
as individual entities. Bitmaps are treated as single objects that you can move, copy, and
reshape. You can create and edit bitmaps with the Citect Bitmap Editor. Because you can
edit the individual pixels in a bitmap, you can use bitmaps for more 'artistic' images,
such as vignettes and image blending.
See Also
Importing graphics

565
Chapter 19: Using Objects

Importing graphics
The Graphics Builder has several file format filters to allow you to import graphics from
other applications, such as drafting programs, illustration programs, presentation pack-
ages, scanners, etc. After a graphic is imported, you can use the graphics builder to edit
the image.
Graphics files can be dragged from a third-party application (such as Windows
Explorer), and dropped onto a page in the Graphics Builder.

Object Properties
The properties of an object are defined in the Properties dialog box. When you draw an
object, the properties dialog appear, allowing you to define the attributes.
You can also double-click the object (or choose Edit | Properties) to display the prop-
erties dialog.
If an object is part of a group, part of a pasted Genie or symbol, or part of the page's tem-
plate, you can access the object's properties by pressing CTRL and double-clicking the
object. Alternatively, choose Tools | Goto Object, click the object, and then click OK.
See Also
Appearance
Movement
Scaling
Fill
Input
Slider
Access
Metadata

Appearance
Click the Appearance tab to define the appearance of the object, such as line style, and
shadowing. You can also specify when the object will be hidden from the operator (for
example when DIGITAL_TAG is OFF).
The check mark to the left of the Appearance tab tells you when an appearance property
has been configured. The check marks in the tabs down the right of the dialog indicate
which property is configured.

566
Chapter 19: Using Objects

Click the other tabs to define more properties for the object. Most properties work
together; for example, an object could possess color fill, movement, and scaling prop-
erties simultaneously.
See Also
Object Properties
Movement

Movement
Click the Movement tab to move the object vertically or horizontally, or to rotate it,
depending on the return of an expression, or the state of a tag.
The check mark to the left of the Movement tab tells you when a Movement property
has been configured. The check marks in the tabs down the right of the dialog tell you
which property is configured.
Click the other tabs to define more properties for the object. Most properties work
together; for example, an object could possess color fill, movement, and scaling prop-
erties simultaneously.
See Also
Object Properties
Scaling

Scaling
Click the Scaling tab to scale the object both vertically or horizontally, depending on the
return of an expression, or the state of a tag.
The check mark to the left of the Scaling tab tells you when a Scaling property has been
configured. The check marks in the tabs down the right of the dialog indicate which
property is configured.
Click the other tabs to define more properties for the object. Most properties work
together, for example, an object could possess color fill, movement, and scaling prop-
erties simultaneously.
See Also
Object Properties
Fill

567
Chapter 19: Using Objects

Fill
Click the Fill tab to specify the color which is to fill the object, and the level to which the
object will be filled. The fill properties can change dynamically, depending on the return
of an expression, or the state of a tag etc. (for instance, you could use this tab to visually
reflect tank levels).
The check mark to the left of the Fill tab tells you when a Fill property has been con-
figured. The check marks in the tabs down the right of the dialog indicate which prop-
erty is configured.
Click the other tabs to define more properties for the object. Most properties work
together, for example, an object could possess color fill, movement, and scaling prop-
erties simultaneously.
See Also
Object Properties
Input

Input
Click the Input tab to specify the command to be executed, and the message to be logged
when an operator clicks on the object. You can also define keyboard commands for the
object, and limit their scope with area and privilege security.
The check mark to the left of the Input tab tells you when an Input property has been
configured. The check marks in the tabs down the right of the dialog indicate which
property is configured.
Click the other tabs to define other object properties. Most properties work together; for
example, an object could possess color fill, movement, and scaling properties simul-
taneously.
See Also
Object Properties
Slider

Slider
Click the Slider tab to use the object as a slider. A variable can be associated with the
object, and when the operator moves the object, the value of the variable will change.
Objects can be set up to slide vertically and/or horizontally, or they can be rotated.

568
Chapter 19: Using Objects

The check mark to the left of the Slider tab tells you when an Slider property has been
configured. The check marks in the tabs down the right of the dialog indicate which
property is configured.
Click the other tabs to define other object properties. Most properties work together; for
example, an object could possess color fill, movement, and scaling properties simul-
taneously.
See Also
Object Properties
Access

Access
Click the Access tab to assign an area or privilege to the object. Operators without appro-
priate access rights will not be able to use sliders, object specific keyboard commands
etc. It also allows you to disable the object under certain runtime circumstances. This
means that the object can be embossed, grayed, or even hidden.
The check mark to the left of the Access tab tells you when an Access property has been
configured. The check marks in the tabs down the right of the dialog indicate which
property is configured.
Click the other tabs to define more properties for the object. Most properties work
together; for example, an object could possess color fill, movement, and scaling prop-
erties simultaneously.
Clear Property
Click Clear Property to remove the configuration details for this property.
Apply
Click Apply to bring your changes into effect. Apply allows you to view your changes
without closing the Properties dialog.
See Also
Object Properties

Metadata
Metadata is a list of names with corresponding values. The Metadata is attached to an
objects animation point. When using any of the DspAnGetMetadata Cicode functions
this Metadata is processed, with the field values retrieved, and set at runtime. At run-
time Metadata cannot be added or removed.

569
Chapter 19: Using Objects

Metadata can be implemented when configuring the following animation objects-Free

Hand Line,Straight Line, Rectangle, Ellipse, Polygon, Pipe, Text, Number, Button, Symbol
Set,Trend, Paste Symbol, Active X, Process Analyst (Database Exchange Control, Pelco
Camera View Controller, CitectSCADA Web Gate Control)

Note: Metadata can also be assigned to super genie associations. See Passing
animation point metadata as Super Genie associations for more information.

To add a Metadata entry:

Click Add or double click on the row to make it editable.
Insert the Name of the metadata.
l To start with an alphanumeric or “_” character
l To contain only those characters that are allowed as part of the tag name syntax
(excluding the period character ‘.’ and reserved keywords), and not contain any white
space.
l Be no more than 253 characters in length
l To be unique across a specific animation point.
l The name cannot be changed at Runtime.
l The name can contain Genie substitutions
Insert the corresponding Value of the specific metadata entry.
l The Value can contain Genie substitutions. E.g. %Level%
l To contain only those characters that are allowed in variable tag names or equip-
ment.item tag references, and not contain any white space.
l To be no more than 255 characters in length.
l Literal strings are supported and be specified within single quotes e.g.'Literal'.

Note: At runtime Values can be changed, however when the graphics page is closed
the Values will revert to the original configuration.

Click Add to save the row. The next row is highlighted and is now editable. Click on the
ESC key to cancel this row or continue to enter name | value pairs until finished.
To edit a Metadata entry:
Double-click the cell you want to edit, or select a row and click the edit button.
Modify the Name or Value . Click Apply to bring your changes into effect and then OK
to close the graphic object properties dialog.
Refer to Using Metadata for examples on how you can implement metadata in your
project.

570
Chapter 19: Using Objects

2. Repeat to create the remaining pumps M_ PUMP, Y_ PUMP, B_ PUMP

Note:Add these pumps to the example project as Local Variable tags

3. Create a button object. This button when selected at runtime will set the CMYK
values for a specific color e.g Pine Green

571
Chapter 19: Using Objects

Note: For Display functions DspAnGetMetadataAt, DspAnSetMetadata, DspAn-

GetMetadata, and DspAnSetMetadataAt -2 is the default value used to retrieve the
unique animation number for the button object.When you need to know the AN that
triggered the input/command, the KeyGetCursor() function may be used as it returns
the AN where the cursor is currently positioned.

4. At runtime when the ‘Pine green’ button is selected the values of the metadata
defined for Cyan, Magenta, Yellow and Black are retrieved and the relevant pumps
set.

Example 2: Using Genie Substitutions in Metadata

Instead of creating a new button for every color as you did in the previous example, you
can create a genie and save it in the genie library. You can use the genie every time you
need to create a new color button.Only needing to configure the name of the button and
the CMYK values that belong to it.
1. From File New-> Genie
2. Add a button object onto the page
3. Configure the button – the title of the button and the Value of the Metadata have
been defined using genie substitutions e.g %Color% and %Cyan%.

572
Chapter 19: Using Objects

4. Save the genie in the appropriate genie library

5. At design time paste the genie onto the graphics page. A dialog will open prompting
you for the name of the button, and the numeric values for Cyan, Magenta, Yellow
and Black. In this example the name of the color is “Purple Heart”

6. At runtime when the ‘Purple Heart’ color button is selected the values of the meta-
data (that were entered in the genie prompt) are retrieved and the relevant pumps set.
Example 3: Defining a subset of Animation points using Metadata

573
Chapter 19: Using Objects

A graphics page could have over four hundred Animation points. Each Animation point
belongs to an object, which raises the question how can you define a subset of these
objects and perform an operation only on that subset. In this example, metadata is used
to define a subset of animation points, and then Cicode is used to operate on this subset
collectively using values stored in an outside source.

Note:For the following example it is assumed you are already using an ODBC data
source.

This example:
l Defines a subset
l Two Cicode functions (created for this example only) – LoadColors(), and Load-
ColorsForButton()
l Cicode to loop through a database table and match, and retrieve values belonging to
the subset defined as “ColorName”.
1. Create four new buttons for the colors – Charcoal, Lime, Olive and Puce.

2. In the graphics editor create a new button. This button will be used to call the values
from the data source using the function LoadColors()
3. At runtime when the LoadColors() button is selected Cicode is triggered that will
search for metadata entries named “ColorName” on the current page. In this example

574
Chapter 19: Using Objects

the “ColorName” is Olive. From the data source it then loads relevant the CMYK
values.

4. When the Olive color button is then selected the values are displayed and the pumps
set.
Cicode used in this example:

// This function finds animation objects on the current page with

// a metadata entry named "sColorName". This demonstrates how metadata
// values can be used to dynamically identify objects.
FUNCTION LoadColors()
INT nAn;
STRING sColorName;

// Disable hardware errors for this Cicode task. If you don't do

// this then DspAnGetMetadata will generate a hardware error for
// any object that does not have a metadata entry "sColorName".
ErrSet(1);

nAn = DspGetAnFirst();
WHILE nAn <> -1 DO
// Determine whether the current animation object has a
// metadata entry named "ColorName". If DspAnGetMetadata
// cannot find the named entry, it returns an empty string.
sColorName = DspAnGetMetadata(nAn, "ColorName");
IF sColorName <> "" THEN
LoadColorsForButton(nAn, sColorName);
END
nAn = DspGetAnNext(nAn);
END
END
// This function loads the CMYK metadata values for the specified
// button (nAn) from a database. This demonstrates how metadata values
// can be modified at runtime.
FUNCTION LoadColorsForButton(INT nAn, STRING sColorName)
INT hSQL;
INT nStatus;
STRING sCyan;
STRING sMagenta;
STRING sYellow;
STRING sBlack;

// Load the CMYK values from the database.

hSql = SQLConnect("DSN=Colors");
IF hSQL <> -1 THEN
nStatus = SQLExec(hSQL, "SELECT * FROM Colors WHERE ColorName = '" + sColorName +
"';");
IF nStatus = 0 THEN
IF SQLNext(hSQL) = 0 THEN
sCyan = SQLGetField(hSQL, "Cyan");
sMagenta = SQLGetField(hSQL, "Magenta");
sYellow = SQLGetField(hSQL, "Yellow");
sBlack = SQLGetField(hSQL, "Black");

575
Chapter 19: Using Objects

END
SQLEnd(hSQL);
ELSE
Message("Exec Error", SQLErrMsg(), 48);
RETURN;
END
SQLDisconnect(hSQL);
ELSE
Message("Connect Error", SQLErrMsg(), 48);
RETURN;
END

// Update the metadata values of the specified object.

DspAnSetMetadata(nAn, "Cyan", sCyan);
DspAnSetMetadata(nAn, "Magenta", sMagenta);
DspAnSetMetadata(nAn, "Yellow", sYellow);
DspAnSetMetadata(nAn, "Black", sBlack);
END

Passing Animation Point Metadata as Super Genie Associations

The metadata you define can be assigned to Super Genie associations. The name of the
metadata and the name of the association in the Super Genie need to be the same. If the
name matches, the value defined for that name | value pair is then inserted into the rel-
evant ‘association’ field in the Super Genie. At runtime the value is dynamically gen-
erated and then displayed on the Super Genie page.
When configuring the object that will call the Super Genie, you can use a Cicode func-
tion that will perform the associations individually (DspAnGetMetadataAt()) or at once
(AssMetadata()).
The table below outlines the possible display results when passing animation point
metadata as Super Genie associations:
where - Y = Defined, N= Not Defined, * =N/A, and
VoE - used when Tag value is not resolved.
Default Value is used when the Metadata Value is not defined
Empty String is treated as "Not defined"

Animation Point
Associations Display Results at runtime
Metadata Pairs

Name Value Nam- Default Value on Tag Res- Unre- Literal

e Value Error olution solved
Tag

576
Chapter 19: Using Objects

Animation Point
Associations Display Results at runtime
Metadata Pairs

Y Y Y Y Y Tag Value VoE Literal

Y Y Y Y N Tag Value #ASS Literal

Y Y Y N Y Tag Value VoE Literal

Y Y Y N N Tag Value #ASS Literal

Y Y N * * Tag Value #ASS Literal

Y N Y Y Y Default VoE Default

Value Value (lit-
eral)

Y N Y Y N Default #ASS N/A

Value

Y N Y N Y #ASS * *

Y N Y N N #ASS * *

N N N * * #ASS * *

N * Y Y Y Default VoE Default

Value Value (lit-
eral)

N * Y Y N Default #ASS N/A

Value

N * Y N Y #ASS * *

N * Y N N #ASS * *

N * N * * #ASS * *

See Also
Page Properties - Associations
Super Genies

Manipulating Objects
Objects can be manipulated in various ways, such as moving, resizing, and grouping.
See Also
Selecting objects
Moving objects
Resizing objects
Deleting objects
Locking/unlocking objects
Grouping objects
Copying and pasting objects

577
Chapter 19: Using Objects

Changing the Overlap of Objects

Aligning objects
Rotating objects
Mirroring objects
Locate an object

Selecting objects
To select a single object:

1. In Graphics Builder, click Select.

2. Click the object. The object's sizing handles appear, and the cursor changes from an
arrow to a hand while on the object.

Note: To add other objects to the selection, hold the Ctrl key and click each object in
turn. To deselect an object from a group selection, while still holding the Ctrl key,
click the object again. To select every object in the drawing, use Select All from the
Edit menu. To deselect every object, click anywhere other than on an object.

To select a group of objects using a marquee box:

1. In Graphics Builder, click Select.

2. Click and hold the left mouse button and drag the cursor across the page. This
creates a temporary bounding box. Any objects within the box will be selected when
you release the mouse button.
3. Release the mouse button.

Note: To add other objects to the selection, or remove objects from the selection, hold
the Ctrl key and click each object in turn. To quickly select every object in the draw-
ing, you can use Select All from the Edit menu. To deselect every object, click any-
where other than on an object.

See Also
Manipulating Objects
Moving objects

Moving objects
You can move an object if you want by clicking the object and dragging it to the new
location.

578
Chapter 19: Using Objects

If you move an object as soon as you select it, an outline of the object boundary displays
as you move it on your page. If you hold the mouse stationary for 1 sec or more before
you move the object, the object itself displays as you move it, enabling you to better see
the result for a more accurate placement.
See Also
Manipulating Objects
Resizing objects

Resizing objects
You can resize objects simply.
To re-size an object:

1. Select the object, and then move the cursor over a sizing handle. The cursor changes
to a two-sided arrow showing the directions that you can drag the handle to resize
the object.
2. Click and drag the handle to a new location. The object's bounding box appears as
you drag.
3. Release the mouse button.
Select a sizing handle at a corner of the object to change the height and width at the
same time. If you hold the CTRL key while you move a corner sizing handle, the object
maintains its aspect ratio (that is, a square remains a square).
To select an object's node:

1. Select the object. Node selection is only applicable to a Line, Pipe, Polyline, or Poly-
gon object.
2. Position and hold the mouse pointer over the node. The mouse pointer will change to
a small cross shape.
3. Click the left mouse button. The color of the selected node will change to the inverse
of the background (light on a dark background, dark on a light background).
If you have a node selected and then click another node within the same object, the first
node will deselect. To select multiple nodes, hold down the Ctrl key and click each node
you want to select. (With the Ctrl key held down, you can click a previously selected
node to deselect it.) Clicking the same node again toggles the selection of the node alter-
nately on and off. To deselect every node, click anywhere other than on a node.
To move a node of an object:

1. Select the node(s).

2. Position and hold the mouse pointer over the node. The mouse pointer will change to
a small cross shape.

579
Chapter 19: Using Objects

3. Click and hold the left mouse button. The cursor changes to a positioning symbol.
4. Drag the selected node(s) to the desired position.
5. Release the mouse button.
Selecting and moving multiple nodes maintains the aspect ratio of the graphic object
between the selected nodes.
To add a node to an object:

1. Select the object.

2. Position and hold the mouse pointer directly over the graphic object at the exact
point where the new node will be added. The mouse pointer will change to a point-
ing hand shape.
3. Press Insert, or either of the available plus (+) keys.
Depending upon the keyboard you're using, the plus key could be either on the number
pad section, or accessed on the main keyboard via the Shift key.
To delete a node from an object

1. Select the node(s).

2. Press Delete or a minus (-) key.
If no nodes are selected, pressing the Delete or minus keys deletes the object.
See Also
Manipulating Objects
Deleting objects

Deleting objects
You can delete unwanted objects.
To delete an object (or a group of objects):

1. Select the object (or group of objects)

2. Choose Edit|Delete or press the Delete key (or a minus (-) key).
See Also
Manipulating Objects
Locking/unlocking objects

580
Chapter 19: Using Objects

Locking/unlocking objects
On complex drawings (with many objects), selecting a discrete group of objects without
including every object (in the selected area) can be difficult (for example when an object
is hidden by another object). To avoid unintentionally selecting an object, you can `lock'
it in position. When an object is `locked', it cannot be selected, deleted, moved, or edited.
Objects are locked only when the Edit menu Break Lock Mode option is not selected.
To lock an object:

1. Select the object.

2. Choose Edit | Lock Object.
To unlock an object:

1. Choose Edit | Break Lock Mode.

2. Select the object.
3. Choose Edit | Unlock Object.
See Also
Manipulating Objects
Grouping objects

Grouping objects
You can group objects to make them easier to manipulate.
To group objects:

1. Click Select.
2. Select the objects to group, and then click Group (or choose Arrange | Group
Objects).
To ungroup objects:

1. Click Select.
2. Select the objects to group, and then click Ungroup (or choose Arrange | Ungroup
Objects).
To change the properties of a group:

1. Click Select.
2. Double-click the group. The Properties dialog box appears.
3. Change the properties as necessary.
4. Alternatively, choose Tools | Goto Object, select the group, and then click OK.

581
Chapter 19: Using Objects

See Also
Manipulating Objects
Copying and pasting objects

Copying and pasting objects

You can copy and paste objects onto other graphics pages.
To copy an object to the clipboard:

1. Click Select.
2. Select the object (or group of objects).
3. Click Copy or choose Edit | Copy.
To paste an object (or group of objects) from the clipboard:

l Click Paste or choose Edit | Paste.

To cut (remove) an object:

1. Click Select.
2. Select the object (or group of objects).
3. Click Cut or choose Edit | Cut.
To paste an object (or group of objects) from the clipboard:

l Click Paste, or choose Edit | Paste.

You can use the clipboard to transfer objects between different graphics pages and from
other graphics applications.
To cancel your last drawing operation(s):

l Click Undo, or choose Edit | Undo.

You can undo operations performed during the current drawing session apart from edits
to bitmaps.
To cancel the Undo (or Redo) the last drawing operation(s):

l Choose Edit | Redo.

See Also
Manipulating Objects
Changing the Overlap of Objects

582
Chapter 19: Using Objects

Changing the Overlap of Objects

In the Graphics Builder, objects can overlap. Where there is an overlap, new objects are
always placed on top of existing objects. You can move objects backwards and forwards
through this display sequence to change the way they overlap.
To position an object (or group of objects) behind other objects so that objects overlap it:

1. Click Select.
2. Select the object (or group of objects).
3. Click Send to Back or choose Arrange | Send to Back.

An object can be moved backwards and forwards one step at a time (rather than com-
pletely to the back, or completely to the front).
To send an object (or group of objects) one step backwards:

1. Click Select.
2. Select the object (or group of objects).
3. Click Send Backwards or choose Arrange | Send Backwards.

To bring an object to the front:

1. Click Select tool.

2. Select the object (or group of objects).
3. Click Bring to Front or choose Arrange | Bring to Front.

583
Chapter 19: Using Objects

An object can be moved backwards and forwards one step at a time (rather than com-
pletely to the back, or completely to the front).
To bring an object (or group of objects) one step forwards:

1. Click Select.
2. Select the object (or group of objects)
3. Click Bring Forwards or choose Arrange | Bring Forwards.

See Also
Manipulating Objects
Aligning objects

Aligning objects
You can precisely align a group of objects vertically, horizontally, or both.
To align objects:

1. Click Select.
2. Select the objects.
3. Choose Arrange | Align. The Align dialog box appears.

Option Description

584
Chapter 19: Using Objects

Ver- Top Aligns the top edges of the selected objects

tical
Vertically aligns the midpoints of the selected objects
Cen-
ter

Bot- Aligns the bottom edges of the selected objects

tom

Vertically aligns the midpoints of the selected objects with even spac-
Eve- ing
n

Doesn't change the vertical alignment of the selected objects

Non-
e

Hor- Left Aligns the left edges of the selected objects

izontal
Horizontally aligns the midpoints of the selected objects
Cen-
ter

Aligns the right edges of the selected objects

Rig-
ht

Horizontally aligns the midpoints of the selected objects with even

Eve- spacing
n

Doesn't change the horizontal alignment of the selected objects

Non-
e

See Also
Manipulating Objects
Rotating objects

Rotating objects
You can rotate an object 90° right (clockwise) or 90° left (counter-clockwise).
To rotate an object (or group of objects):

1. Click Select.
2. Select the object(s).
3. Choose Arrange | Rotate.

585
Chapter 19: Using Objects

To rotate a text object:

1. Click Select.
2. Select the object(s).
3. Choose Tools | Convert to Bitmap.
4. Choose Arrange | Rotate.
5. Select the direction to rotate the object (or group of objects).
The object(s) are rotated 90 degrees in the direction you select. To rotate the object(s) 180
degrees, click the direction button twice.
See Also
Mirroring objects
Manipulating Objects

Mirroring objects
You can mirror an object relative to its horizontal or vertical axis.
To mirror an object (or group of objects) relative to its horizontal or vertical axis:

1. Click Select.
2. Select the object(s)
3. Choose Arrange | Mirror.
4. Choose the axis about which to mirror the object (or group of objects).
See Also
Locate an object
Manipulating Objects

Locate an object
You use the Goto Object dialog box to find, select and access the properties of objects on
your current page or on page templates used by the current page. You can select objects,
Genies, symbols, and groups on the page (or template) as well as the graphical elements
that make up those Genies, symbols, and groups.
To locate an object (or a group, Genie, symbol, or page template) on the current page and display
its properties:

1. Choose Tools | Goto Object.

2. Locate the object (or group, Genie, symbol, or page template) in the tree structure or
type the relevant AN in the Object AN box.
Objects that are made up of several objects (or other graphical elements) have a

586
Chapter 19: Using Objects

plus sign (+) next to them. Click the + sign to see these component objects.
3. Double click the object in the tree structure, or click OK to display its properties.

587
Chapter 19: Using Objects

588
Chapter 20: Understanding Object Types
There are many different object types, each with their own unique set of properties. For
details of properties common to every object type, see Defining Common Object Prop-
erties.
See Also
Free Hand Line Objects
Straight Line Objects
Rectangle Objects
Ellipse Objects
Polygon Objects
Pipe Objects
Text Objects
Number Objects
Button Objects
Symbol Set Objects
Trend Objects
Cicode Objects
Pasted Symbol Objects
Pasted Genie Objects
ActiveX Objects
"Using the Process Analyst" in the Process Analyst User Guide
Database Exchange Control Objects

Free Hand Line Objects

The Free Hand Line tool allows you to draw lines. Lines can be moved, resized,
reshaped, brought to the front and so on, and their properties edited just like other types
of object.
To draw a freehand line:

1. Click the Freehand tool.

2. Move the cursor to where you want the line to start.

3. Click and drag the cursor to draw the line.
When you release the mouse button, the object properties dialog for the line is dis-
played.

589
Chapter 20: Understanding Object Types

See Also
Freehand Line Properties - Appearance (General)
Understanding Object Types

Freehand Line Properties - Appearance (General)

Free Hand Line drawings have the following general appearance properties.
[Line] Width
The width of the line (in pixels). You can change the width by clicking the up and down
arrows to the right of the field, or by entering another value in this field.
If you make the line more than 1 pixel wide, it needs to be solid.
[Line] Style
The style of the line. You can choose one of the following line styles:

To change the style, choose a style from the menu to the right of this field.
[Line] Color
The color of the line.
[Fill] Filled
The Filled check box determines whether the object will be filled with a color. If you
check this box, an invisible line is drawn from one end of your line to the other. Every-
thing between the invisible line and your line will be filled.

[Fill] Color
The color with which the object will be filled. The color that you select as your fill color
here is static.
To specify a fill color that changes with runtime conditions, click the Fill tab.

590
Chapter 20: Understanding Object Types

If you have enabled the Fill (Color) properties, be aware that the color you select here
will override the OFF color for Fill Color (On/Off), the ABC color for Fill Color (Multi-
state), Array Color 0 for Fill Color (Array), and the At minimum color for Fill Color (Gra-
dient).
For help on the remaining properties tabs, see Defining Common Object Properties.

Straight Line Objects

The Straight Line tool allows you to draw straight lines. Straight lines can be moved,
resized, reshaped, brought to the front and so on, and their properties edited just like any
other type of object.
To draw a straight line:

1. Click the Straight Line tool.

2. Move the cursor to where you want to start the line.

3. Click and drag to draw the line. (If you hold the Ctrl key while drawing the line it is
constrained to the vertical or horizontal.
When you release the mouse button, the object properties dialog for the line is dis-
played.
See Also
Straight Line Properties - Appearance (General)
Understanding Object Types

Straight Line Properties - Appearance (General)

Straight Lines have the following general appearance properties.
[Line] Width
The width of the line (in pixels). You can change the width by clicking the up and down
arrows to the right of the field, or by entering another value in this field.
If you make the line more than 1 pixel wide, it needs to be solid.
[Line] Style
The style of the line. You can choose from the following line styles:

591
Chapter 20: Understanding Object Types

To change the style, choose a style from the menu to the right of this field.
[Line] Color
The color of the line.
For help on the remaining properties tabs, see Defining Common Object Properties.

Rectangle Objects
Use the Rectangle tool to draw rectangles and squares. Rectangles and squares can be
moved, resized, reshaped, brought to the front and so on, and their properties edited just
like other types of object.
To draw a rectangle:

1. Click the Rectangle tool.

2. Move the cursor to where you want the rectangle to start.

3. Click and drag the mouse to the opposite corner of the rectangle and release the
mouse button. If you hold the Shift key before you start drawing the rectangle, it is
drawn from its center outwards.
When you release the mouse button, the object properties dialog for the rectangle is
displayed.
To draw a square:

1. Click the Rectangle tool.

2. Click (and hold) the Ctrl key.
3. Move the cursor to where you want the square to start and click (and hold) the
mouse button.
4. Drag the cursor to the opposite corner of the square and release the mouse button. If
you hold the Shift key (and the Ctrl key) before you start drawing the square, it is
drawn from its center outwards.

592
Chapter 20: Understanding Object Types

When you release the mouse button, the object properties dialog for the square is
displayed.
See Also
Rectangle Properties - Appearance (General)
Understanding Object Types

Rectangle Properties - Appearance (General)

Rectangles have the following general appearance properties.
[Line] Width
The width of the outline for the rectangle (in pixels). You can change the width by click-
ing the up and down arrows to the right of the field, or by entering another value in this
field.
If you make the line more than 1 pixel wide, it needs to be solid.
[Line] Style
The outline style of the rectangle. You can choose from the following line styles:

To change the style, choose a style from the menu to the right of this field.
[Line] Color
The outline color of the rectangle.
[Fill] Filled
The Filled check box determines whether the rectangle will be filled with a color.
[Fill] Color
The color with which the rectangle will be filled. The color that you select as your fill
color here is static.

593
Chapter 20: Understanding Object Types

To specify a fill color that changes with runtime conditions, click the Fill tab. If you have
enabled the Fill (Color) properties, be aware that the color you select here overrides the
OFF color for Fill Color (On/Off), the ABC color for Fill Color (Multi-state), Array Color 0
for Fill Color (Array), and the At minimum color for Fill Color (Gradient).
[Object type] Extra line
Adds an extra line (1 pixel width) of lowlight color to the rectangle, if the rectangle is
defined as Raised or Lowered (click the 3D Effects tab).
[Gradient] Color
Controls the color of the gradient fill between the fill color and the gradient color. This
option is available only when the Filled and Gradient Fill check boxes are selected. The
gradient is updated at runtime to reflect the gradient between the two colors selected.
Gradient fills support flashing colors.
Gradients do not rotate with an object; for example, if an object contains a left-to-right
gradient fill and is rotated 90 degrees (either at runtime or in Graphics Builder), the gra-
dient is still left to right.
[Gradient] Direction
The direction to be used for the gradient color. Use the table below as a guide to choose
the gradient color direction you want.

Example Gradient Color Direction

Left to Right

Right to Left

594
Chapter 20: Understanding Object Types

Top to Bottom

Bottom to Top

Horizontal Gradient to Middle

Horizontal Gradient from Middle

Vertical Gradient to Middle

595
Chapter 20: Understanding Object Types

Vertical Gradient from Middle

[Object type] Border

Adds an extra line (1 pixel width) of black to the perimeter of the rectangle.
[Object type] Corner Radius
Controls the radius of the corners of the rectangle. Enter a value between 0 and 32. The
higher the value, the more rounded the corners of the rectangle.
When the radius is greater than 0, the Extra line and Border options are not available.
For help on the remaining properties tabs, see Defining Common Object Properties.

Ellipse Objects
You use the Ellipse tool to draw ellipses, circles, arcs, and pie-slices. Ellipse objects can
be moved, resized, reshaped, brought to the front and so on, and their properties edited
just like other types of object.
To draw an ellipse:

1. Click the Ellipse tool.

2. Move the cursor to a corner of the bounding rectangle (marquee) and click (and hold)
the mouse button.
3. Drag the cursor to the opposite corner of the bounding rectangle and release the
mouse button. If you hold the Shift key before you start drawing the ellipse, it is
drawn from its center outwards.
When you release the mouse button, the object properties dialog for the ellipse is
displayed.
To draw a circle:

1. Click the Ellipse tool.

2. Click (and hold) the Ctrl key.

596
Chapter 20: Understanding Object Types

3. Move the cursor to a corner of the bounding rectangle (marquee) and click (and hold)
the mouse button.
4. Drag the cursor to the opposite corner of the bounding rectangle and release the
mouse button. If you hold the Shift key and the Ctrl key before you start drawing the
circle, it is drawn from its center outwards.
When you release the mouse button, the object properties dialog for the circle is dis-
played.
See Also
Ellipse Properties - Appearance (General)
Understanding Object Types

Ellipse Properties - Appearance (General)

Ellipses have the following general appearance properties:
[Line] Width
The width of the outline of the ellipse (in pixels). You can change the width by clicking
the up and down arrows to the right of the field, or by entering another value in this
field. If you make the line more than 1 pixel wide, the line style will be solid.
[Line] Style
The outline style of the ellipse. You can choose one of the following line styles:

To change the style, choose a style from the menu to the right of this box.
[Line] Color
The outline color of the ellipse.
[Fill] Filled
The Filled check box determines whether the ellipse will be filled with a color.
[Fill] Color

597
Chapter 20: Understanding Object Types

The color with which the ellipse will be filled. The color that you select as your fill color
here is static.
To specify a fill color that changes with runtime conditions, click the Fill tab. If you have
enabled the Fill (Color) properties, be aware that the color you select here will override
the OFF color for Fill Color (On/Off), the ABC color for Fill Color (Multi-state), Array
Color 0 for Fill Color (Array), and the At minimum color for Fill Color (Gradient).
[Gradient] Color
Controls the color of the gradient fill between the fill color and the gradient color. This
option is available only when the Filled and Gradient Fill check boxes are selected. The
gradient is updated at runtime to reflect the gradient between the two colors selected.
Gradient fills support flashing colors.
Gradients do not rotate with an object; for example, if an object contains a left-to-right
gradient fill and is rotated 90 degrees (either at runtime or in Graphics Builder), the gra-
dient is still left to right.
[Gradient] Direction
The direction to be used for the gradient color. Use the table below as a guide to choose
the gradient color direction you want.

Example Gradient Color Direction

Left to Right

Right to Left

598
Chapter 20: Understanding Object Types

Top to Bottom

Bottom to Top

Horizontal Gradient to Middle

Horizontal Gradient from Middle

Vertical Gradient to Middle

599
Chapter 20: Understanding Object Types

Vertical Gradient from Middle

[Object type] Ellipse

Select this radio button if you want to the object to be a full ellipse.

For a full ellipse, you are not required to specify Start and End angles.
[Object type] Pie-slice
Select this radio button if you want to remove a section from your ellipse (i.e., you want
it to resemble a pie-slice).
If you select this option, you can specify a Start angle, and an End angle:
Start angle
The angle (measured clockwise from 0 degrees) of the section to be removed from the
ellipse. For example, if you enter a start angle of 50 degrees, your pie-slice would look
something like this:

End angle
The angle (measuring clockwise from 0 degrees) of the section of the ellipse which is to
remain. For example, if you enter an end angle of 150 degrees, your pie-slice would look
something like this:

Start and End angles can be combined for various effects. For example, a Start angle of
270 degrees, and an End angle of 150 degrees would produce the following pie-slice:

[Object type] Arc

Select this radio button if you want to draw an arc.

600
Chapter 20: Understanding Object Types

If you select this option, you can specify a Start angle, and an End angle:
Start angle
The angle (measured clockwise from 0 degrees) defining the segment to be removed from
the ellipse, leaving an arc. For example, if you enter a start angle of 50 degrees, your arc
would look something like this:

End angle
The angle (measuring clockwise from 0 degrees) defining the segment of the ellipse
which is to remain. For example, if you enter an end angle of 150 degrees, your pie-slice
would look something like this:

Start and End angles can be combined for various effects. For example, a Start angle of
270 degrees, and an End angle of 150 degrees would produce the following arc:

For help with the other properties, see Defining Common Object Properties.

Polygon Objects
Use the Polygon tool to draw polygons and polylines. Polygons can be moved, resized,
reshaped, brought to the front and so on, and their properties edited just like other types
of object.
To draw a polygon:

1. Click the Polygon tool.

2. Move the cursor to where you want the polygon to start and click and hold the
mouse button.
3. At the end of the first line segment, release the mouse button.
4. Move the cursor to each point on the polygon in turn, and click the mouse button
(clicking and dragging is not necessary after the first segment).

601
Chapter 20: Understanding Object Types

To draw horizontally or vertically only, hold the Ctrl key down when you are
drawing the polygon.
5. To complete the polygon, double-click the mouse button.
When you complete the polygon, the object properties dialog is displayed.
To draw a polyline:

1. Click the Polygon tool.

2. Move the cursor to where you want the polyline to start and click and hold the
mouse button.
3. At the end of the first line segment, release the mouse button.
4. Move the cursor to each point on the polyline in turn and click the mouse button
(clicking and dragging is not necessary after the first segment).
To draw horizontally or vertically only, hold the Ctrl key down when you are
drawing the polyline.
5. To complete the polyline, double-click the mouse button.
When you release the mouse button, the object properties dialog for the circle is dis-
played.
Initially, the object will actually be a polygon. To change it to a polyline, in the
object's properties dialog define it as [Object type] Open.
See Also
Polygon Properties - Appearance (General)
Understanding Object Types

Polygon Properties - Appearance (General)

Polygons have the following general appearance properties.
[Line] Width
The width of the outline of the polygon (in pixels). You can change the width by clicking
the up and down arrows to the right of the field, or by entering another value in this
field.
If you make the line more than 1 pixel wide, it needs to be solid.
[Line] Style
The outline style of the polygon. You can choose any one of the following line styles:

602
Chapter 20: Understanding Object Types

To change the style, choose the style you want from the menu to the right of this field.
[Line] Color
The outline color of the polygon.
[Fill] Filled
The Filled check box, determines whether the polygon will be filled with a color.
[Fill] Color
The color with which the polygon will be filled. The color that you select as your fill
color here is static.
To specify a fill color that changes with runtime conditions, click the Fill tab. If you have
enabled the Fill (Color) properties, be aware that the color you select here will override
the OFF color for Fill Color (On/Off), the ABC color for Fill Color (Multi-state), Array
Color 0 for Fill Color (Array), and the At minimum color for Fill Color (Gradient).
[Gradient] Color
Controls the color of the gradient fill between the fill color and the gradient color. This
option is available only when the Filled and Gradient Fill check boxes are selected. The
gradient is updated at runtime to reflect the gradient between the two colors selected.
Gradient fills support flashing colors.
Gradients do not rotate with an object; for example, if an object contains a left-to-right
gradient fill and is rotated 90 degrees (either at runtime or in Graphics Builder), the gra-
dient is still left to right.
[Gradient] Direction
The direction to be used for the gradient color. Use the table below as a guide to choose
the gradient color direction you want.

Example Gradient Color Direction

603
Chapter 20: Understanding Object Types

Left to Right

Right to Left

Top to Bottom

Bottom to Top

Horizontal Gradient to Middle

604
Chapter 20: Understanding Object Types

Horizontal Gradient from Middle

Vertical Gradient to Middle

Vertical Gradient from Middle

[Object type] Open

Defines the object as a polyline (the first point and the last point are not joined).
[Object type] Closed
Defines the object as a polygon (the first point and the last point are joined).
For help on the remaining properties tabs, see Defining Common Object Properties.

Pipe Objects
Use the Pipe tool to draw pipes with automatic three-dimensional shading. Pipes can be
moved, resized, reshaped, brought to the front and so on, and their properties edited just
like other types of object.
To draw a pipe:

1. Click the Pipe tool.

605
Chapter 20: Understanding Object Types

2. Move the cursor to where you want the pipe to start, and click and hold the mouse
button.
3. At the end of the first line segment, release the mouse button.
4. Move the cursor to each point on the path in turn and click the mouse button (click-
ing and dragging is not necessary after the first segment).
5. To complete the pipe, double-click the mouse button.
When you complete the pipe, the object properties dialog is displayed.

Hint: To draw horizontally or vertically only, hold the Ctrl key down when drawing
the pipe.

Drawing Complex Pipe Arrangements

Use the Pipe tool to draw complex pipe arrangements (including 'T' pieces and junc-
tions). The illustration below shows some pipes, and the sequence of mouse clicks
needed to draw each of them:

Hint: Use the grid to assist in accurate positioning for each click.

See Also
Pipe Properties - Appearance (General)
Understanding Object Types

Pipe Properties - Appearance (General)

Pipes have the following general appearance properties.
[Line] Width

606
Chapter 20: Understanding Object Types

The width of the pipe (in pixels). You can change the width by clicking the up and
down arrows to the right of the field, or by entering another value in this field. Every
pipe needs to be at least 1 pixel wide.
[Line] Highlight Color
The color of the pipe where it is "in the light"; that is, the brightest color on the pipe.
[Line] Lowlight Color
The color of the pipe where it is "in shadow"; that is, the dullest color on the pipe.
For help on the remaining properties tabs, see Defining Common Object Properties.

Text Objects
Use the Text tool to type text on the page. Text can be moved, resized, reshaped, brought
to the front and so on, and their properties edited just like other types of object.
To add text:

1. Click the Text tool.

2. Type your text on the keyboard. (Press Enter to start a new line.)
3. Move the cursor to where you want to position the text and click the left mouse but-
ton.
When you click the mouse button to place the text, the object properties dialog is
displayed.
See Also
Text Properties - Appearance (General)
Understanding Object Types

Text Properties - Appearance (General)

Text has the following general appearance properties
Font
The font used to display the text. Use the scroll bar to the right to view available fonts, or
type the font name, or part of it, directly into this field.
Style
Select whether you would like the text to be Regular, Bold, Bold Italic, or Italic.
Size

607
Chapter 20: Understanding Object Types

Define the size of the text (point size). Available sizes might vary according to the
selected printer and the selected font.
[Alignment] Left
Select this radio button to align the text to the left of the text box.
[Alignment] Right
Select this radio button to align the text to the right of the text box.
[Alignment] Center
Select this radio button to align the text in the center of the text box.
[Effect] Strikeout
Select this box to make the text will appear with a line through it.
[Effect] Underline
Select this box to underline the text.
Text
This field contains the text that will display on the page. You can enter any keyboard
character(s). You can edit the text here, or directly from the graphics page. It is useful to
edit text at this field, as you can apply text changes at the same time as you apply other
font and color changes.
This text changes automatically depending on the Display Value properties that you
define.
Foreground
The color of the text.

Note: There are several radio buttons in Display Value (On/Off, Multi-state and so
on). When selected, these radio buttons change the appearance of the right hand side
of the dialog.

See Also
Text Properties - Appearance (Display Value)

Text Properties - Appearance (Display Value)

Text has the following display value appearance properties. Selecting one of the fol-
lowing five options changes the appearance of the right hand side of the dialog.
[Type] On / Off

608
Chapter 20: Understanding Object Types

Changes the text which displays when a particular condition is met, and another when
it is not. For example, you could display an alarm message when a particular variable
tag is in alarm, and a normal message when it is not.
See Text Properties - Appearance Display Value (On/Off).
[Type] Multi-state
This option is useful when you have several possible conditions, occurring together in
different combinations, at different times. Select this option to display different text for
each combination.
For example, three digital variable tags (A,B, and C) can each be ON or OFF at any time.
You can display a different message for each ON/OFF combination. In other words, you
could display a different message for each of the following ON/OFF combinations ABC,
ABC, ABC, ABC, ABC, ABC, ABC, ABC.
Text Properties - Appearance Display Value (Multi-state).
[Type] Array
Allows you to enter an expression which returns an integer. For each integer (from 0-
255), you can display different text. For example, you could display a different message
for each state of an analog tag.
See Text Properties - Appearance Display Value (Array).
[Type] Numeric
Displays the value of a tag or expression in numeric format (you can specify the format).

See Text Properties - Appearance Display Value (Numeric).

[Type] String
Displays the value of an expression as a string.
See Text Properties - Appearance Display Value (String).

Text Properties - Appearance Display Value (On/Off)

Text has the following On/Off Display Value properties:
ON text when
The text entered in the ON text field (below) appears when the condition entered here is
true. The text can be a maximum of 128 characters long.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options; Insert Tag, and Insert Function.
OFF text

609
Chapter 20: Understanding Object Types

The text that will display whenever the condition entered above is false. You can use
any keyboard character(s) to a maximum length of 256 characters.
For example, you could display the message Conveyor 110 Normal when CV110_
ERROR.On is false (i.e., there is no alarm at conveyor 110).
ON text
The text that will display whenever the condition entered above is true. You can enter
any keyboard character(s) to a maximum length of 256 characters.
For example, you could display the message Conveyor 110 Alarm when CV110_
ERROR.On is true (i.e. there is no alarm at conveyor 110).
Click Clear Property to clear property details and disable the property.
See Also
Text Properties - Appearance (Display Value)
Text Properties - Appearance Display Value (Multi-state)
Text Properties - Appearance Display Value (Array)
Text Properties - Appearance Display Value (Numeric)
Text Properties - Appearance Display Value (String)

Text Properties - Appearance Display Value (Multi-state)

Text has the following multi-state display value properties:
Conditions
The conditions you enter here will occur together in different ways, at different times.
You can use each different combination to determine the text that will display.
The default number of conditions is 3, but you can add more (to a maximum of 5 con-
ditions, providing 32 combinations), using the Add button. You can also delete con-
ditions using the Delete button, but you need to always enter a condition in this field.
To enter a condition, click the relevant line (A, B, C, etc.), and click Edit. To insert a tag
or function, click the Wizard button. This button displays two options: Insert Tag and
Insert Function.

State text
The text that is to display for each combination of the above conditions. You can enter
any keyboard character(s).

610
Chapter 20: Understanding Object Types

For example:
To display different messages about the status of a valve, you could fill out the Con-
ditions and State text fields as follows:

Conditions State text

A Open Feedback ABC Valve Inoperable

B Close Feedback ABC Valve Inoperable

C Open Output ABC Valve Closed

ABC Valve Inoperable

ABC Valve Open

ABC Valve Inoperable

In this example, Open_Feedback and Close_Feedback are variable tags representing

digital inputs on the valve; Open_Output is a variable tag representing an output on the
valve. So, ABC means Open_Feedback is on, and Close_Feedback and Open_Output
are both off. For this combination, the text "Valve Inoperable" will display, because the
valve is open when it is meant to be closed. The same type of logic applies to the rest of
the states.
Click Clear Property to clear property details and disable the property.
See Also
Text Properties - Appearance (Display Value)
Text Properties - Appearance Display Value (On/Off)
Text Properties - Appearance Display Value (Array)
Text Properties - Appearance Display Value (Numeric)
Text Properties - Appearance Display Value (String)

Text Properties - Appearance Display Value (Array)

Text has the following Array Display Value properties:
Array expression
Enter the expression which is to return one or more integers. For each returned integer, a
different piece of text is displayed.
If the return value is:

611
Chapter 20: Understanding Object Types

l Less than 0 (zero), it will be set to 0 (zero), and a runtime hardware alarm will be trig-
gered.
l Greater than 255, it will be set to 255, and a runtime hardware alarm will be trig-
gered.
l A real (non-integer) number, it will be rounded off to the nearest integer.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

Array text
The text that is to display for each integer returned by the Array expression entered
above. You can enter any keyboard character(s).
For example, to display different messages about the status of a motor, you could fill out
the Array expression and Array text fields as follows:

Array expression Array text

MOTOR_STATUS 0 Running

1 Starting

2 Stopping

3 Stopped - Normal

4 Stopped - Error

5 Isolated

In this example, MOTOR_STATUS is an analog variable tag representing the status of a

motor. When the motor changes state, an integer is returned (0 = Running, 1 = Starting
etc.) and the appropriate text displays.
Click Clear Property to clear property details and disable the property.
See Also
Text Properties - Appearance (Display Value)
Text Properties - Appearance Display Value (On/Off)
Text Properties - Appearance Display Value (Multi-state)
Text Properties - Appearance Display Value (Numeric)

612
Chapter 20: Understanding Object Types

Text Properties - Appearance Display Value (String)

Text Properties - Appearance Display Value (Numeric)

Text has the following Numeric Display Value properties.
Numeric expression
The value of the expression entered here will be displayed on the graphics page. It will
be formatted according to the format selected below.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert tag and Insert Function.

Format
The value returned for the expression entered above will be displayed according to the
format you enter here. For example, the analog variable tag MOTOR_STATUS returns
integers 0-5. If you enter this tag as the Numeric expression above, and enter #.## as your
format, the display will alternate between 0.00, 1.00, 2.00, 3.00, 4.00, and 5.00. You can
select a format from the drop-down list, or type in your own. If the numeric expression is
a single variable, its format is overwritten by the format you enter here.
Click Clear Property to clear property details and disable the property.
See Also
Text Properties - Appearance (Display Value)
Text Properties - Appearance Display Value (On/Off)
Text Properties - Appearance Display Value (Multi-state)
Text Properties - Appearance Display Value (Array)
Text Properties - Appearance Display Value (String)

Text Properties - Appearance Display Value (String)

Text has the following String Display Value properties.
String expression
The value of the expression entered here will be displayed as a string on the graphics
page.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert tag and Insert Function.

613
Chapter 20: Understanding Object Types

Click Clear Property to clear property details, and disable the property. To define further
properties for the object, click the relevant tabs.
For help on the remaining properties tabs, see Defining Common Object Properties.
See Also
Text Properties - Appearance (Display Value)
Text Properties - Appearance Display Value (On/Off)
Text Properties - Appearance Display Value (Multi-state)
Text Properties - Appearance Display Value (Array)
Text Properties - Appearance Display Value (Numeric)

Number Objects
Use the Number tool to represent a tag or expression as a number. When you place a
number on your page, simply enter the relevant variable tag or expression. Numbers can
be moved, resized, brought to the front, and so on, and their properties edited just like
other types of object.
(The same functionality is also available through the Text tool.)
To add a number to your graphics page:

1. Click the Number tool.

2. Move the cursor to where you want the number to display and click the mouse but-
ton. The Text Properties dialog box appears where you enter the relevant variable tag
or expression.
For help on the various Properties tabs, see Text Properties - Appearance (General)
and Defining Common Object Properties.

Button Objects
Use the Button tool to draw buttons on graphics page. You can then assign security
rights and attach commands to it.

614
Chapter 20: Understanding Object Types

Buttons can be moved, resized, reshaped, brought to the front, and so on, and their prop-
erties edited just like other types of object.
To draw a button:

1. Click the Button tool.

2. Move the mouse to where you want the button to start and press (and hold) the
mouse button.
3. Drag the mouse to where you want the button to finish and release the mouse button.
When you release the mouse button, the object properties dialog is displayed.
See Also
Button Properties - Appearance (General)
Understanding Object Types

Button Properties - Appearance (General)

Buttons have the following General Appearance properties.

[Type] Text

Select this option to display text on the button. If you select this option, the Text and
Font fields will display to the right of the dialog.
If either the Text or Symbol type option is selected, you can use XP style buttons. To con-
figure a button to use the Windows XP style, select the XP Style check box. During run-
time an XP style button has a blue border when it has keyboard focus, and an orange
border when the mouse is on the button. When you place a button on a page, the XP
Style check box is selected by default.
Pressing '^n' or 'Enter' wraps the text onto the next line. For example, Start^nMotor
would display as:

Font
The font used to display the text. Use the scroll bar to the right to view available fonts, or
type part of a font name directly into this field.

615
Chapter 20: Understanding Object Types

Note: The Background Color property is no longer supported for button fonts. Any
imported buttons from a previous version will have the Background Color set to the
default color.

Style
Select whether you would like the text to be Regular, Bold, Bold Italic, or Italic.
Size
Define the size of the text (point size). Available sizes might vary according to the
selected printer and the selected font.
Custom Fill Color
Select this check box to enable the Fill Color Up and Fill Color down boxes.
Fill Color Up
The button color when in the Up state.
Fill Color Down
The button color when in the Down state.

Note: Fill Color Up and Down options available for Text and Symbol Types only.

[Alignment] Left
Select this radio button to left-align multi-line text. The aligned text will remain in the
center of the button. This has no effect on single lines of text.
[Alignment] Right
Select this radio button to right-align multi-line text. The aligned text will remain in the
center of the button. This has no effect on single lines of text.
[Alignment] Center
Select this radio button to center-align multi-line text. The aligned text will remain in the
center of the button. This has no effect on single lines of text.
[Effect] Strikeout
Select this box to make the text appear with a line through it.
[Effect] Underline
Select this box to underline the text.
Text

616
Chapter 20: Understanding Object Types

This field contains the text that will display on the page. You can enter any keyboard
character(s). You can edit the text here, or directly from the graphics page. It is useful to
edit text at this field, as you can apply text changes at the same time as you apply other
font and color changes.
This text changes automatically depending on the Display Value properties that you
define.
Foreground
The color of the text.

[Type] Symbol

Select this option to display a symbol on the button. If you select this option, the Set but-
ton will display to the right of the dialog.
Click Set to choose the symbol which is to display on the button. A picture of the
selected symbol will also display.

[Type] Target

When this option is selected, the button will not have any text or symbols on it, and it
will have a transparent face.
Mode
There are three different modes of transparent buttons:
l BORDER_3D: The button is drawn with only the 3-D border (transparent face).
l BORDER: The button is drawn with only a thin line border.
l TARGET: The button is totally transparent. This constitutes a screen target.
For help on the remaining properties tabs, see Defining Common Object Properties.

Symbol Set Objects

The Symbol Set tool allows you to represent changing runtime conditions with changing
symbols. By clicking on this tool, then clicking on the graphics page, you can define the
symbols which are to display for each condition.
After a symbol set has been added to the page, it can be moved, re-sized, re-shaped,
brought to the front etc., and its properties can be edited, just like any other type of object.

To add a Symbol Set:

1. Click the Symbol tool.

617
Chapter 20: Understanding Object Types

2. Move the mouse pointer to the desired position on the page, and click with the left
mouse button.
When you click the mouse button, the object properties dialog is displayed.
3. Fill out the relevant properties for the symbol set, and click OK.

Note: There are several radio buttons in Symbol Sets Appearance (described below).
When selected, these radio buttons change the appearance of the right hand side of
the dialog.

[Type] On / Off
Select this radio button to display one symbol when a particular expression is TRUE,
and another when it is FALSE. For example, you could display a red symbol when a par-
ticular variable tag is in alarm, and a green symbol when it is not.
See Symbol Set Properties - Appearance General (On/Off).
[Type] Multi-state
This option is useful when you have several possible conditions, occurring together in
different combinations, at different times. Select this option to display different symbols
for each combination.
For example, three digital variable tags (A,B, and C) can each be ON or OFF at any time.
You can display a different symbol for each ON/OFF combination. In other words, you
could display a different symbol for each of the following ON/OFF combinations ABC,
ABC, ABC, ABC, ABC, ABC, ABC, ABC.
See Symbol Set Properties - Appearance General (Multi-state).
[Type] Array
The Array option allows you to enter an expression which returns an integer. For each
unique integer (from 0 to 255), you can display a unique symbol. For example, you could
display a different symbol for each threshold of an analog alarm.
See Symbol Set Properties - Appearance General (Array).
[Type] Animated
Select this radio button to display an actual animation (several different symbols in
sequence).
When selected, the radio buttons on the dialog box change the appearance of the right
hand side of the dialog. These radio buttons are only documented once below.
See Symbol Set Properties - Appearance General (Animated).
See Also
Understanding Object Types

618
Chapter 20: Understanding Object Types

Symbol Set Properties - Appearance General (On/Off)

Symbol Sets have the following general appearance (On/Off) properties:
ON symbol when (128 Chars.)
The symbol entered in the ON symbol field (below) will display whenever the condition
entered here is TRUE. The symbol entered in the OFF symbol field (below) will display
whenever the condition entered here is FALSE.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options; Insert tag, and Insert Function.
OFF symbol
The symbol that will display whenever the condition entered above is false. Click Set to
select a symbol, or Clear to clear the current selection.
For example, you could display the OFF symbol when MIX_RUNNING is false.
ON symbol
The symbol that will display whenever the condition entered above is true. Click Set to
select a symbol, or Clear to clear the current selection.
For example, you could display the ON symbol when MIX_RUNNING is true.
Click Apply or OK to bring your changes into effect, or Cancel to discard them and exit.
Click ClearProperty to clear property details, and disable the property. To define further
properties for the object, click the relevant tabs.
See Also
Symbol Set Objects
Symbol Set Properties - Appearance General (Multi-state)
Symbol Set Properties - Appearance General (Array)
Symbol Set Properties - Appearance General (Animated)
Understanding Object Types

Symbol Set Properties - Appearance General (Multi-state)

Symbol Sets have the following general appearance (Multi-state) properties:
Conditions
The conditions you enter here will occur together in different ways, at different times.
You can use each different combination to determine which symbol will display.

619
Chapter 20: Understanding Object Types

To enter a condition, click the relevant line (A, B, C, etc.), and click Edit. You can add
more conditions (to a maximum of 5, providing 32 combinations), using the Add button.
To insert a tag or function, click the Wizard button. This button displays two options;
Insert Tag and Insert Function. You can also delete conditions using the Delete button,
but there needs to always be a condition in this field. Conditions which are left black
(instead of deleted) will be evaluated as false at runtime.
State symbols
The symbols that will display for each combination of the above conditions. Click the
Set button to select a symbol, or Clear to clear the current selection.
For example:
To display different symbols each time the status of a valve changes, you could fill out
the Conditions and State symbols fields as follows:

In this example, Open_Feedback, and Close_Feedback are variable tags representing

digital inputs on the valve, and Open_Output is a variable tag representing an output
on the valve. So, ABC means Open_Feedback is ON, and Close_Feedback and Open_
Output are both OFF. For this combination, the inoperable symbol will display, because
the valve is open when it is meant to be closed. The same type of logic applies to the rest
of the states.
Click Clear Property to clear property details, and disable the property. To define further
properties for the object, click the relevant tabs.
See Also
Symbol Set Objects
Symbol Set Properties - Appearance General (On/Off)
Symbol Set Properties - Appearance General (Array)
Symbol Set Properties - Appearance General (Animated)
Understanding Object Types

620
Chapter 20: Understanding Object Types

Symbol Set Properties - Appearance General (Array)

Symbol Sets have the following general appearance (Array) properties:
Array expression
Enter the expression which is to return one or more integers. For each returned integer, a
different symbol will be displayed.
If the return value is:
l Less than 0 (zero), it will be set to 0 (zero), and a runtime hardware alarm will be trig-
gered.
l Greater than 255, it will be set to 255, and a runtime hardware alarm will be trig-
gered.
l A real (non-integer) number, it will be rounded off to the nearest integer.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options; Insert tag, and Insert Function.
Array symbol
The symbol that is to display for each integer returned by the Array expression entered
above (symbol 0 will be used when the expression returns integer 0, symbol 1 will be
used when integer 1 is returned etc.).
Click the Set button to select a symbol, or Clear to clear the current selection.
For example, to display different symbols illustrating the various states of a motor, you
could fill out the Array expression and Array symbol fields as follows:

In this example, MOTOR_STATUS is an analog variable tag representing the status of

a motor. Each time the motor changes state, an integer is returned (0 = Running, 1 = Start-
ing etc.), and the appropriate symbol displays.

621
Chapter 20: Understanding Object Types

Click Clear Property to clear property details, and disable the property. To define further
properties for the object, click tabs.
See Also
Symbol Set Objects
Symbol Set Properties - Appearance General (On/Off)
Symbol Set Properties - Appearance General (Multi-state)
Symbol Set Properties - Appearance General (Animated)
Understanding Object Types

Symbol Set Properties - Appearance General (Animated)

Symbol Sets have the following general appearance (Animated) properties:
Animate when
Whenever this expression is true, the animation will run. Whenever the expression is
false, the Off frame (below) will display.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options; Insert tag, and Insert Function.
Animation frames
The symbols from Frame 1 onwards are those that will be used as the animation. They
are displayed in sequence when the expression above is TRUE. The frequency at which
the symbols are displayed is determined by the [Page]AnmDelay parameter. The symbol
in the Off frame will display when the expression above is FALSE.
For example, to animate a running auger, you could fill out the Animate when and
Animation frames fields as follows:

622
Chapter 20: Understanding Object Types

In this example, AUGER_RUNNING, is a variable tag which is TRUE when the auger
is running. The symbols in the animation frames (Frame 1 onwards) have been designed
so that when displayed in sequence, they animate a running auger. The symbol in the
Off animation frame will display when AUGER_RUNNING is FALSE.
Click Apply or OK to bring your changes into effect, or Cancel to discard them and exit.
Click Clear Property to clear property details, and disable the property. To define further
properties for the object, click the relevant tabs.
For help on the remaining properties tabs, see Defining Common Object Properties.
See Also
Symbol Set Objects
Symbol Set Properties - Appearance General (On/Off)
Symbol Set Properties - Appearance General (Multi-state)
Symbol Set Properties - Appearance General (Array)
Understanding Object Types

Trend Objects
The Trend tool allows you to add a trend to the graphics page with the mouse (click and
drag).
After a trend object is drawn, it can be moved, re-sized, re-shaped, brought to the front
etc., and its properties can be edited, just like any other type of object.
To add a trend to a page:

1. Click the Trend tool

or choose Objects | Trend.

2. Move the mouse to where you want the trend to start and click (and hold) the mouse
button.
3. Drag the mouse to the opposite corner of the trend and release the mouse button.
The Trend Properties dialog appears. Assign the Trend Tags to the pens, choosing
appropriate colors.
See Also
Trend properties
Insert Trend dialog box
Understanding Object Types

623
Chapter 20: Understanding Object Types

Trend properties
Trends have the following general appearance properties:
Cluster Name
The name of the cluster that runs the trends being graphed. Each trend graph can only
communicate with one cluster, so you cannot mix trends from multiple clusters on a sin-
gle trend graph.

Note: To mix trends from different clusters on a single trend graph you will need to
use Process Analyst.

If there is only one cluster, or, the client is connected to only one cluster, this property
can be left blank and the value of the single connected cluster is inferred.
If the client is connected to more than one cluster, then this field needs to be specified.
Pens
The pens (including color) to be displayed on the graph (31 characters maximum). You
can use up to eight pens.
Double-clicking a selected pen or clicking Edit allows you to change the trend tag and
pen color. To insert a trend tag, click Wizard to display theInsert Trend dialog box.
If more than one trend tag is displayed in a trend window and each has a different sam-
ple period, the trend with the smallest sample period is used as the general display
period.

Note: If the trend object is part of a group, part of a pasted Genie or symbol, or part
of the page's template, you can still access its properties: hold down the Control
(CTRL) key and double-click the object. Alternatively, choose Goto Object from the
Tools menu, click the object, then click OK. Be aware, however, that if it is part of a
pasted Genie or symbol, or part of the template, you cannot edit existing pens, only
new ones.

If you are configuring an SPC control chart, you need to add a suffix to the trend tag to
indicate the type of SPC. There are SPC templates that are easily configured through
Genies. Use the Genies rather than defining these trend tags for yourself.The following
table lists available SPC types:

SPC Definition SPC Type

624
Chapter 20: Understanding Object Types

<tag name>.X Mean of raw data in a subgroup (X - bar)

<tag name>.XCL Center line of X - bar

<tag name>.XUCL Upper control limit of X - bar

<tag name>.XLCL Lower control limit of X - bar

<tag name>.R Range of raw data in a subgroup (R - bar)

<tag name>.RCL Center line of R - bar

<tag name>.RUCL Upper control limit of R - bar

<tag name>.RLCL Lower control limit of R - bar

<tag name>.S Standard deviation of raw data in a subgroup (S - bar)

<tag name>.SCL Center line of S - bar

<tag name>.SUCL Upper control limit of S - bar

<tag name>.SLCL Lower control limit of S - bar

where <tag name> is any trend tag, for example:

Pen 1 PIC117_PV.XCL

Pen 2 PIC117_PV.XUCL

Pen 3 PIC117_PV.XLCL

Pen 4 PIC117_PV.X

If you are using the PageTrend() function to display this trend page, leave these fields
blank.
Display Trend Types as Periodic
When selected, enables trend pens (both periodic and event) to be displayed as periodic.
Event and periodic trend data can then be displayed on the same graph. If this box is
not selected, event and periodic pens have different styles and needs to be displayed on
separate graphs.

Note: This option is set by default in the predefined templates designed for use with

625
Chapter 20: Understanding Object Types

periodic trends. It will only need to be enabled for customized templates.

[Samples] Number of samples (5 Chars.)

The number of samples (1-32767) you can display in your trend window without scroll-
ing (i.e., the width of your trend object). The default depends on the number of pixels per
sample and your display resolution. The width of a trend object is equal to Pixels per
sample x Number of samples.

Note: For a meaningful trend graph, make Pixels per sample x Number of samples
less than the width of the display. For example, an XGA screen has a width of 1024
pixels. If you use 10 pixels per sample, 102 samples can be displayed on the screen
without scrolling.

[Samples] Pixels per sample (2 Chars.)

The display width of each sample. The width of a trend object is equal to Pixels per sam-
ple x Number of samples. The default is 1 pixel.
Click Clear Property to clear property details, and disable the property. To define other
properties for the object, click the relevant tabs.
For help on the remaining properties tabs, see Defining Common Object Properties.

Insert Trend dialog box

This dialog box lets you select a trend tag. To insert a trend tag, select the tag name, then
click OK. The tag is inserted at the location of the cursor.
See Also
Trend Objects
Understanding Object Types

Cicode Objects
The Cicode Object tool allows you to add a Cicode Object to the graphics page with the
mouse (click and drag).
A Cicode Object can be any command (such as a function and so on). When the graph-
ics page is displayed at runtime, the command is run continually. Cicode objects can
also be assigned a key sequence, allowing you to enter keyboard commands when it is
selected at runtime.
After a Cicode object is added, it can be moved and so on and its properties edited, just
like other types of object.

626
Chapter 20: Understanding Object Types

To add a Cicode Object to a page:

1. Click the Cicode Object tool,

or choose Objects | Cicode Object.

2. Move the mouse to where you want to add the object, and click the left mouse button.
3. Define the relevant properties for the object, and click OK.
See Also
Cicode Object Properties - Cicode (General)
Understanding Object Types

Cicode Object Properties - Cicode (General)

Cicode Objects have the following General properties:
Command (254 Chars.)
A Cicode command that is continually executed. You can use any Cicode command,
built-in Cicode function or user-written function. The command is executed continually
(while the page is displayed), for example:

Com- DspSymAnm(25, "Pumps.Slurry1", "Pumps.Slurry2", "Pumps.Slurry3");

mand

The command in this example uses the built-in function DspSymAnm(). The function
displays three symbols ("Pumps.Slurry1", "Pumps.Slurry2", "Pumps.Slurry3") continually
(at AN 25).
You can also write generic functions by using the Cicode function DspGetAnCur() to get
the AN number, for example:

Com- DspSymAnm(DspGetAnCur(), "Pumps.Slurry1", "Pumps.Slurry2",

mand "Pumps.Slurry3");

The command in this example displays three symbols ("Pumps.Slurry1", "Pumps.Slu-

rry2", "Pumps.Slurry3") continually (at the current AN).
If you are using an actual animation, each symbol is displayed at a frequency that is set
using the Computer Setup Wizard (also determined by the [Page] AnmDelay parameter).
To add just an animation point to the page, add a Cicode Object, without a command.
Click Clear Property to clear property details, and disable the property. To define other
properties for the object, click the relevant tabs.
For help on the remaining properties tabs, see Defining Common Object Properties.

627
Chapter 20: Understanding Object Types

Pasted Symbol Objects

The Paste Symbol tool allows you to insert a symbol from a library onto the graphics
page.

After a symbol is pasted using this tool, it can be moved, resized, reshaped, brought to
the front and so on, and its properties edited just like any other type of object.
Pasted [library] symbols can be linked to their source, so that changes made to the orig-
inal are inherited by the pasted symbol.
To display the properties of the objects in the symbol (after pasting), hold the Control
(CTRL) key down and double-click the specific object. Alternatively, choose Tools | Goto
Object, click the object, then click OK.
To learn more about creating symbols, see Using libraries.
To paste a symbol from the library to the page:

1. Click the Paste Symbol tool or choose Edit | Paste Symbol.

2. To paste a linked symbol, select the Linked check box. To paste an unlinked symbol,
deselect the Linked check box.
To break the link:

1. Select the symbol.

2. Choose Edit | Cut Link.
See Also
Paste Symbol dialog box
Symbol Properties - Appearance (General)

Paste Symbol dialog box

This dialog box lets you paste a symbol from a library to the graphics page (or template).

The Paste Symbol dialog box has the following properties:

Symbol
A table of symbols in the project.
To add a symbol to a graphics page, use the scroll bar to locate the thumbnail image of
the symbol, then select it and click OK (or double-click the thumbnail image). To edit the
object in the library, select it and click Edit. To create a new symbol, click New.

628
Chapter 20: Understanding Object Types

Note: If the symbol has a small diamond-shaped badge next to it, it indicates it is a
flashing symbol (see example below.)

Library
The library where the symbol is stored.
Linked
To paste a symbol that maintains the link with its library, check this box. A symbol that
is linked will be automatically updated if the symbol in the library is changed.
You can cut the link at any time with the Cut Link command from the Edit menu, but
you cannot re-link a symbol with the library after the link has been cut.
If you have selected Paste Symbol as Flashing, two dialog boxes appear in sequence,
allowing you to choose two images that you want to implement as a flashing symbol.
The Primary Select Symbol dialog allows you to select the initial image used, the Flash-
ing Select Symbol dialog the second image. If the bitmaps are different in size, the flash-
ing symbol is scaled to the size of the primary image. If one of the symbols is itself a
flashing symbol, only the primary state will be displayed.

Symbol Properties - Appearance (General)

This dialog displays a picture of the selected symbol, name, and path. Click Set to
change the symbol, or double-click the image. The Select Symbol dialog appears, letting
you select a new symbol.
For help on the remaining properties tabs, see Defining Common Object Properties.
To change the properties of an object in a pasted Symbol:

1. Click the Select tool.

2. Hold down the Control (CTRL) key and double-click the object.
3. Change the relevant properties in the dialog box. Alternatively, select Tools | Goto
Object, select the object, and then click OK.
See Also
Pasted Genie Objects
Understanding Object Types

629
Chapter 20: Understanding Object Types

Pasted Genie Objects

The Paste Genie tool allows you to insert a Genie onto the graphics page.

After a Genie is pasted using this tool, it can be resized, rotated, moved, copied, dupli-
cated, pasted, brought to the front, and so on.
To display the properties of the objects in the Genie (after pasting), hold the Control
(CTRL) key down and double-click the specific object.

ActiveX Objects
You can incorporate ActiveX objects into your project. This means you can use com-
ponents that have been developed independently of CitectSCADA.
The ActiveX tool can be used to insert ActiveX objects in graphics pages. After you have
selected and positioned an ActiveX object, it can be moved, re-sized, re-shaped, brought
to the front etc., and its properties can be edited, just like any other object.

Managing associated data sources

If an ActiveX object has an association with a data source (for example, it stores data to
a DBF file), you need to consider the impact of running a project that contains it on a dif-
ferent machine or via one of the Internet clients (Internet Display Client or Web Client).
If the path to the data source is hardcoded to a location on the local machine, the data
source will not be found if the project is moved or run remotely. For example, the Data-
base Exchange ActiveX control connects to a recipe.DBF file in the project path. If you
restore a project that uses it on a different computer with a different installation path,
you will need to recreate the data source to retrieve any recipes.

UNINTENDED EQUIPMENT OPERATION

l Whenever possible, avoid programming the literal paths to data sources in your
project.
l When a project or a data source is relocated to a different computer, examine the pro-
gram and program objects and correct any literal paths before placing the project
back into service.
Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

630
Chapter 20: Understanding Object Types

One way to avoid having to recreate data sources is to locate any associated data
sources in a central location on a network. For example, if the data source is located on a
SQL server, it will be accessible from every machine on the common network.
To insert an ActiveX Control:

1. Click the ActiveX tool,

or choose Edit | Insert ActiveX Control.

2. Select an ActiveX Control and click Insert.
See Also
ActiveX Object Properties
Tag Association
Object Identification

ActiveX Object Properties

The two properties tabs common to ActiveX objects are the Tag Association and Vis-
ibility tabs which appear vertically on the Appearance tab. The content and number of
other tabs depends on the individual design of each ActiveX object. This is determined
by the amount of flexibility and support its creator has included.
For details on configuring these additional tabs, refer to the documentation provided
with the ActiveX object.
See Also
Tag Association

Tag Association
You can create an association between a property of an ActiveX object and a variable
tag.
To create an association between a property of an ActiveX object and a variable tag:

1. Double-click the ActiveX object. The Properties dialog box appears.

2. Click the Tag Association tab.
3. Select a property from the Properties list.
4. Click the Wizard | Insert Tag button.
5. Select a tag from the list and click OK.
See Also
"ActiveX Object Properties" in CitectSCADA User Guide

631
Chapter 20: Understanding Object Types

"Understanding Object Types" in CitectSCADA User Guide

ActiveX Object Properties - Appearance (Tag Association)

ActiveX objects have the following appearance properties:
Properties
The "properties" of an ActiveX object relate to the elements that define the object's func-
tionality and appearance. The available properties for a selected ActiveX object are listed
here, as defined by the object's creator.
The check box to the left of each item on the list indicates whether or not a tag has been
associated with the Property. If the box is checked, it means an association has already
been defined for the property. If you want to clear this tag association, simply uncheck
the box, or clear the tag from the "Associate property with tag. . ." field.
Associate property with tag
You can create an association between an ActiveX object property and a variable tag so
that changing values in one are reflected in the other. To create an association, you need
to first choose a property from the property list. The label Associate property with tag
will change to display the property name.
Select the variable tag you would like to associate with a property by clicking on the Wiz-
ard button and choosing from the list of available tags. Alternatively, the tag name can
be typed in to the Associate property with tag field.

Note: You can only use variable tag names in this field. Functions, expressions and
constants are not supported when defining ActiveX property tag associations.

You can only associate a property with a variable tag if the tag type is compatible with
the property. To display a list of compatible tag types, select the property, and click List
Property Types. A list of compatible data types will display, or a message will inform
you that there are no compatible types.
If there are no types compatible with the property, the Associate Property with tag and
Update association on fields will be disabled.
If you specify a tag which might be inappropriate for the selected ActiveX property, the
Type Evaluation dialog will display an alert. This might happen if:
l The types compatible with the property are different from the tag type.
l The tag type is smaller than the types compatible with the property, meaning that
data could be truncated or lost.
Bindable

632
Chapter 20: Understanding Object Types

If an object property is "bindable", it means it can automatically send notification of

value changes to CitectSCADA, and acknowledge any value changes from an associated
tag. This means both the property and an associated tag will automatically update when-
ever the value for either changes.
If a property is not bindable, the property/tag association can only be synchronized
according to the event selected in the Update association on Event field.
Be aware that if an object property is bindable, the Update association on Event field
will be automatically set to <Property change notification> by default. You can change
this setting if you want the tag association to be updated by a more specific event.
For properties that are not bindable, you can mimic the behavior of <property change
notification> by selecting After update for the Update association on Event field.
Property status
This indicates the read/write status of the selected property. With ActiveX objects, some
properties are read-only, whereas others accept value changes. If a property is marked
"read only", it indicates that its value is fixed and can only be read by CitectSCADA. If
its status is read/write, can modify the property during runtime via a tag association.
Update association on Event:
This defines when you want a value update to occur for the selected property and its
associated tag. Use the menu to the right of the Event field to view events that can be
used to trigger a tag association update.
The available events that can be used with a particular property are predefined by an
object's creator. They typically include user interaction events (for example, mouse
clicks), time events (such as a new day or new month), or value changes (such as "after
update").
Property documentation
Most ActiveX objects have documentation describing the object's controls and func-
tionality. Some have a separate Help file included, others, simple text prompts to explain
each property. This depends on what an object's creator has included.
The Property documentation field displays Help information for a selected property, or
give instructions to obtain the Help necessary for a selected property. Usually the fol-
lowing message will appear:
"Click the '?' button to the right to display the Help topic for this property"
The Help button displays the ActiveX object Help file (if included), usually with the
topic displayed that relates to the selected property. It will also provide information
about settings provided on additional tabs the ActiveX object might call up on the prop-
erties dialog.
Clear Property

633
Chapter 20: Understanding Object Types

The Clear Property button clears the tag associations for each of the ActiveX object prop-
erties. To clear a tag association for a particular object property, clear the check box to the
left of the property.
If you accidentally click Clear Property, you can restore your tag associations by clicking
Cancel and reopening the ActiveX properties dialog.

Object Identification
You can identify your ActiveX object.
To identify your ActiveX object:

1. From Graphics Builder, double-click the ActiveX object. The Properties dialog
appears.
2. Click the Access tab.
3. Click the Identification tab.
4. Assign your ActiveX object a name in the Object Name field.
5. Assign your ActiveX object an Event Class.
6. Click OK.
See Also
Object Properties - Access (Identification)

Object Properties - Access (Identification)

Objects have the following Access Identification properties:
[Identification] Object Name
This field allows you to assign a name to your ActiveX object (254 characters max-
imum). It identifies the object when using the ObjectByName(), ANByName(), and Create-
ControlObject() Cicode functions.

The name can be any combination of alpha or numeric characters.

[Identification] Event Class
Allocate a name for the event class of your ActiveX object (16 characters). You can then
use this name to create a Cicode function to trap an event.
Don't change the default value if you want to access the ActiveX object using CitectVBA.
If you do, CitectVBA can't access the object. If the Event Class is changed, you can reset
it to the default value by clicking Clear Property.
[Persistence] Persist ActiveX data between page transitions

634
Chapter 20: Understanding Object Types

Select this check box to allow changes made to the control to be persisted between pages.
For example, you can select this check box if you want an ActiveX edit control to keep
the current text in the control, so that next time the page is entered, the same text is dis-
played.

Note: An ActiveX control may or may not implement data persistence in the manner
you expect. Some controls will not persist certain data, and therefore you will not be
able to save and restore that data.

Note: Even when an ActiveX control implements data persistence in an expected

manner, be advised that data is only persisted for the current session. If Citect-
SCADA runtime is shut down and restarted the updated data is not available.

Database Exchange Control Objects

The Database Exchange ActiveX control lets you connect to a data source (for example a
database), and extract, display, and edit recipe values. The control is inserted and con-
figured on a graphics page using the Citect Graphics Builder. For more information see
the Database Exchange online help.

Vijeo Web Gate Control Objects

The Vijeo Web Gate Control object provides a remote viewer for an HMI target that can
be embedded within a Vijeo Citect graphics page. Depending on the Web Gate setup,
you can remotely view the HMI displays, and read and write data on the target machine
from the remote PC. For more information see the Vijeo Web Gate Object online help.

635
Chapter 20: Understanding Object Types

636
Chapter 21: Defining Common Object Properties
This section describes properties that are common to several object types. Some are also
common to object groups.
See Also
3D Effects
Visibility
Movement
Scaling
Fill Color
Fill Level
Touch Commands
Keyboard Commands
Sliders
Access

3D Effects
You can apply 3D effects to objects to make them more realistic.
To apply 3D effects to an object:

1. Draw the object/group (or paste a symbol). The properties tab dialog will auto-
matically display, unless you have turned off the Display properties on new option
in the Graphics Builder. (For a group, the properties dialog will not display auto-
matically; you need to double-click the group).
2. Click the Appearance tab.
3. Click the 3D Effects tab (to the right of the dialog).
4. The dialog will then display several options to enable you to manipulate your object.
To activate any of these options click the option (or the radio bullet to the left of the
option).
5. By selecting certain options additional fields will display to enable you to further
manipulate your object. Enter further details as necessary, using the Help button for
detailed information about each field.
6. Click OK.
See Also
Object Properties - Appearance (3D Effects)
Defining Common Object Properties

637
Chapter 21: Defining Common Object Properties

Object Properties - Appearance (3D Effects)

Objects have the following 3D Effects properties.
[Effects] None
Select this option to display the object without any special effects (such as shadowing,
embossing and so on).
[Effects] Shadowed
Select this option to display the object with a shadow; for example:

Depth
The distance (in pixels) that the shadow extends below and to the right of the object.
This option alters the apparent distance between the object and its shadow, for example:

Shadow color
The color of the shadow. The shadow color will not change dynamically with runtime
conditions.
[Effects] Raised
Select this option to display the object as a raised three dimensional solid, for example:

Depth
The distance (in pixels) that the sides of the object extend out from the raised surface.
This option alters the apparent distance from the raised surface down to your graphics
page, for example:

638
Chapter 21: Defining Common Object Properties

Highlight color
The color of the directly illuminated "edges" of the object.

Lowlight color
The color of the "edges" of the object that are in shadow.

[Effects] Lowered
Select this option to display the object as if it is actually lower than your graphics page,
for example:

Depth
The distance (in pixels) that the sides of the object extend out from the lowered surface.
This option alters the apparent distance from the lowered surface up to your graphics
page, for example:

Highlight color
The color of the directly illuminated "edges" of the object.

639
Chapter 21: Defining Common Object Properties

Lowlight color
The color of the "edges" of the object that are in shadow.

[Effects] Embossed
Select this option to display the object as if it has been embossed on your graphics page,
for example:

Depth
The distance (in pixels) that the embossed surface is lowered. This option alters the
apparent distance from the embossed surface up to your graphics page, for example:

Highlight color
The color of the right and lower edges of the object.

Lowlight color
The color of the left and upper edges of the object.

Click Apply or OK to save your changes, or Cancel to exit. To define further properties
for the object, click the relevant tabs.

640
Chapter 21: Defining Common Object Properties

Visibility
You can determine whether an object is visible or not.
To hide/unhide an object:

1. Double click the object you would like to hide.

2. Select the Appearance tab.
3. Select the Visibility tab (to the right of the dialog).
4. Click the Wizard button to the right of the Hidden when field.
5. Select either Insert Tag or Insert Function depending on which you would like to
relate to your object.
6. Enter an expression in the Hidden when field. When this expression is true your
object will be hidden.
7. Click OK.
See Also
Object Properties - Appearance (Visibility)
Defining Common Object Properties

Object Properties - Appearance (Visibility)

Objects and groups have the following visibility properties:
Hidden when
The object/group will be hidden whenever the expression entered in this field is TRUE.
Enter an expression of 128 characters or less. For example, if you want the object/group
to be hidden for every operator except the superintendent, you could enter the following:
NOT GetPriv( _Super, _SectionA )

where _Super and _SectionA are labels.

To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

641
Chapter 21: Defining Common Object Properties

Note: If a group is hidden, every object (and other groups) in the group will also be
hidden regardless of their individual properties. If the group is visible, its objects will
behave according to their individual properties.

Click Clear Property to clear property details and disable the property.

Movement
You can control the movement of objects.
To configure an object or group that moves:

1. Draw the object/group (or paste a symbol). The properties tab dialog automatically
display, unless you have turned off the Display properties on new option in the
Graphics Builder. (For a group, the properties dialog will not display automatically;
you need to double-click the group.)
2. Click the Movement tab.
3. Click the Horizontal, Vertical or Rotational tab (to the right of the dialog).
4. Enter a Movement expression (the expression that will move the object/group at run-
time).
5. Enter further details as necessary, using the Help button for detailed information
about each field.
6. Click OK.
See Also
Object Properties - Movement (Horizontal)
Object Properties - Movement (Vertical)
Object Properties - Movement (Rotational)
Group and object movement - examples

Object Properties - Movement (Horizontal)

Objects and groups can be moved from side to side during runtime, changing dynam-
ically whenever the value of a particular expression changes. By default, as the value of
the expression increases, the object/group will move (in increments) to the right. As the
value of the expression decreases, the object/group will move (in increments) to the left.
This property could, for example, be used to display the position of a coal stacker mov-
ing along a stockpile.

Note: Horizontal movement cannot be used if the horizontal slider is enabled. A

642
Chapter 21: Defining Common Object Properties

group and its objects can be configured with any movement combination (i.e., a
group can move vertically while one of its objects rotates, and so on).

Objects and groups have the following horizontal movement properties:

Movement expression
The value of the expression entered in this field (253 characters maximum) will deter-
mine the horizontal movement of the object/group. By default, when the expression
returns its minimum value, the object/group will shift hard to the left. When the expres-
sion returns its maximum, the object/group will shift hard to the right. For intermediate
values, the object/group will move to the appropriate position between the minimum
and maximum offset.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

[Movement expression] Specify range

Select this box to manually specify Minimum and Maximum values for the movement
expression, rather than using the default values. For an expression containing an analog
variable tag, the defaults are the Engineering Zero and Full Scale values from the last
variable tag in the expression. If the analog variable tag does not have Engineering Zero
and Full Scale values, the defaults are 0 (zero) and 32000. For expressions without tags,
the defaults are 0 (zero) and 100.
[Movement expression] Minimum
Enter the minimum value for the expression. When this value is returned by the expres-
sion, the object/group will shift to the left, by the At minimum offset. You can only enter
a value here if you have selected the Specify range box.
[Movement expression] Maximum
Enter the maximum value for the expression. When this value is returned by the expres-
sion, the object/group will shift to the right, by the At maximum offset. You can only
enter a value here if you have selected the Specify range box.
[Offset] At minimum

643
Chapter 21: Defining Common Object Properties

The distance (number of pixels from the original object/group center) that the
object/group will shift to the left when the Movement expression returns its minimum
value.
You can change the offset value by pressing the up and down arrows to the right of the
field, or by entering another value in this field.
[Offset] At maximum
The distance (number of pixels from the original object/group center) that the
object/group will shift to the right when the Movement expression returns its maximum
value.
You can change the offset value by pressing the up and down arrows to the right of the
field, or by entering another value in this field.

Note: You can shift the object/group right at minimum and left at maximum, by
entering negative distances in the Offset fields, or by swapping the expression limits
(in the Minimum and Maximum fields).

Click Clear Property to clear property details, and disable the property.
See Also
Object Properties - Movement (Vertical)
Object Properties - Movement (Rotational)

Object Properties - Movement (Vertical)

Objects and groups can be moved up and down during runtime, changing dynamically
whenever the value of a particular expression changes. By default, as the value of the
expression increases, the object/group will move up (in increments). As the value of the
expression decreases, the object/group will move down (in increments).
This property could be used to display the movement of an elevator.

Note: Vertical Movement cannot be used if the Vertical Slider is enabled. A group
and its objects can be configured with any movement combination (i.e. a group can
move vertically while one of its objects rotates, and so on).

Objects and groups have the following vertical movement properties:

Movement expression

644
Chapter 21: Defining Common Object Properties

The value of the expression entered in this field (253 characters maximum) will deter-
mine the vertical movement of the object/group. By default, when the expression returns
its minimum value, the object/group will shift down to its lowest position. When the
expression returns its maximum, the object/group will shift up to its highest position.
For intermediate values, the object/group will move to the appropriate position between
the minimum and maximum offset.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

[Movement expression] Specify range

Select this box to manually specify Minimum and Maximum values for the movement
expression, rather than using the default values. For an expression containing an analog
variable tag, the defaults are the Engineering Zero and Full Scale values from the last
variable tag in the expression. If the analog variable tag does not have Engineering Zero
and Full Scale values, the defaults are 0 (zero) and 32000. For expressions without tags,
the defaults are 0 (zero) and 100.
[Movement expression] Minimum
Enter the minimum value for the expression. When this value is returned by the expres-
sion, the object/group will shift down, by the At minimum offset. You can only enter a
value here if you have selected the Specify range box.
[Movement expression] Maximum
Enter the maximum value for the expression. When this value is returned by the expres-
sion, the object/group will shift up, by the At maximum offset. You can only enter a
value here if you have selected the Specify range box.
[Offset] At maximum
The distance (number of pixels from the original object/group center) that the
object/group will shift up when the Movement expression returns its maximum value.
You can change the offset value by pressing the up and down arrows to the right of the
field, or by entering another value in this field.
[Offset] At minimum

645
Chapter 21: Defining Common Object Properties

The distance (number of pixels from the original object/group center) that the
object/group will shift down when the Movement expression returns its minimum
value.
You can change the offset value by pressing the up and down arrows to the right of the
field, or by entering another value in this field.

Note: You can shift the object/group up at minimum and down at maximum, by
entering negative distances in the Offset fields, or by swapping the expression limits
(in the Minimum and Maximum fields).

See Also
Object Properties - Movement (Horizontal)
Object Properties - Movement (Rotational)

Object Properties - Movement (Rotational)

Objects and groups can be dynamically rotated during runtime, whenever the value of a
particular expression changes. By default, as the value of the expression increases, the
object/group will rotate clockwise (in increments). As the value of the expression
decreases, the object/group will rotate anti-clockwise (in increments).
This property could be used to display an aerial view of the movement of a circular
stacker in a coal mining operation.

Note: Rotational Movement cannot be used if the Rotational Slider is enabled. A

group and its objects can be configured with any movement combination (i.e. a
group can move vertically while one of its objects rotates, and so on).

Objects and groups have the following rotational movement properties:

Angle expression(253 Chars.)
The value of the expression entered in this field will determine the rotation of the
object/group. During runtime, when the expression returns its minimum value, the
object/group will rotate to its anti-clockwise limit. When the expression returns its max-
imum, the object/group will rotate to its clockwise limit. For intermediate values, the
object/group will rotate to the appropriate position between the minimum and max-
imum limits.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

646
Chapter 21: Defining Common Object Properties

[Angle expression] Specify range

Select this box to manually specify Minimum and Maximum values for the angle expres-
sion, rather than using the default values. For an expression containing an analog var-
iable tag, the defaults are the Engineering Zero and Full Scale values from the last
variable tag in the expression. If the analog variable tag does not have Engineering Zero
and Full Scale values, the defaults are 0 (zero) and 32000. For expressions without tags,
the defaults are 0 (zero) and 100.
[Angle expression] Minimum
Enter the minimum value for the expression. When this value is returned by the expres-
sion, the object/group will rotate anti-clockwise, by the minimum offset. You can only
enter a value here if you have selected the Specify range box.
[Angle expression] Maximum
Enter the maximum value for the expression. When this value is returned by the expres-
sion, the object/group will rotate clockwise, by the maximum offset. You can only enter a
value here if you have selected the Specify range box.
[Angle] At minimum
The anti-clockwise angle (in degrees relative to 0 degrees) that the object/group will
rotate when the Angle expression returns its minimum value.
You can change the angle by pressing the up and down arrows to the right of the field,
or by entering another value in this field.
[Angle] At maximum
The clockwise angle (in degrees relative to 0 degrees) that the object/group will rotate
when the Angle expression returns its minimum value.
You can change the angle value by pressing the up and down arrows to the right of the
field, or by entering another value in this field.

Note:You can rotate the object/group clockwise at minimum and anti-clockwise at

maximum, by entering negative angles in the Angle fields, or by swapping the
expression limits (in the Minimum and Maximum fields).

[Center axis offset] Express

647
Chapter 21: Defining Common Object Properties

Click this radio button for the quick and easy way of selecting the point about which the
object/group will rotate. The express option gives you the choice of 9 points (Top Left,
Bottom Right and so on), which are displayed in the picture field to the right of the
dialog. To select one, just click it with your mouse.
[Center axis offset] Custom
Click this radio button to define your own center axis. When you select this radio button,
two fields will display to the right, allowing you to plot the position of your center axis.
Specify the distance to the right in the first field, and the distance down in the second.
The Center axis is plotted based on these two values.
For example, if you enter 8 as the horizontal offset, and 13 as the vertical offset, the
Center axis will be 8 pixels to the right, and 13 pixels below the center of the
object/group.
Enter negative values in the offset distance fields to move the Center axis left instead of
right, and up instead of down.
See Also
Object Properties - Movement (Horizontal)
Object Properties - Movement (Vertical)

Group and object movement - examples

A group and its objects can be configured with any combination of movement (hor-
izontal, vertical, and rotational). The following examples illustrate how some of these
combinations work.
Example 1: Rotating the group and moving the object left to right
If your group is configured to rotate from 0 degrees to 60 degrees, and one of its objects is
configured to move left and right, the object will do both. It will move left and right as
per its own properties, and, at the same time, it will rotate as part of the group.
Remember, however, that 'left' and 'right' are relative to the original orientation of the
group, not the page. As the group rotates, 'horizontal' also rotates. When the group has
rotated 15 degrees, 'left' is actually 285 degrees; (not 270 degrees), and 'right' is actually
105 degrees (not 90 degrees). When the group has rotated 50 degrees, 'left' is 320 degrees,
and 'right' is 140 degrees, and so on.
Original state of group

648
Chapter 21: Defining Common Object Properties

Group rotated right, and ellipse moved left

Example 2: Rotating the group and moving the object up and down
If your group is configured to rotate from 0 degrees to 60 degrees, and one of its objects is
configured to move up and down, the object will do both. It will move up and down as
per its own properties, and, at the same time, it will rotate as part of the group.
Remember, however, that 'up' and 'down' are relative to the original orientation of the
group, not the page. As the group rotates, 'vertical' also rotates. When the group has
rotated 15 degrees, 'up' is actually 15 degrees (not 0 degrees), and 'down' is actually 195
degrees (not 180 degrees). When the group has rotated 50 degrees, 'up' is 50 degrees, and
'down' is 230 degrees, and so on.
Original state of group

Group rotated right, and ellipse moved up

Example 3: Rotating the group clockwise and rotating the object anticlockwise

649
Chapter 21: Defining Common Object Properties

If your group is configured to rotate from 0 degrees-60 degrees, and one of its objects is
configured to rotate from 90 degrees-0 degrees, the object will do both. It will rotate as
per its own properties, and, at the same time, it will rotate as part of the group.
Remember, however, that the object's rotation is relative to the group, not the page. If the
group rotates 60 degrees to the right, and the object rotates 90 degrees to the left, the
object has only rotated 30 degrees to the left relative to the page.
Original state of group

Group rotated clockwise, and ellipse rotated anticlockwise

Note: By moving the ellipse as shown in the above examples, you are actually chang-
ing the overall size of the group. It is important to remember this as it might affect
object fill levels.

See Also
Movement
Defining Common Object Properties

Scaling
You can scale objects to the size you want.
To configure an object or group that changes size:

1. Draw the object (or paste a symbol). The object properties tab dialog will auto-
matically display, unless you have turned off the Display properties on new option
in the Graphics Builder.

650
Chapter 21: Defining Common Object Properties

2. Click the Scaling tab.

3. Click the Horizontal or Vertical tab (to the right of the dialog).
4. Enter a Scaling expression (the expression that will change the size of the object at
runtime).
5. Enter further object property details as necessary, using the Help button for detailed
information about each field.
6. Click OK.
See Also
Object Properties - Scaling (Horizontal)
Object Properties - Scaling (Vertical)
Defining Common Object Properties

Object Properties - Scaling (Horizontal)

The width of an object can be dynamically changed during runtime whenever the value
of a particular expression changes. As the value of the expression increases and
decreases, the width of the object increases or decreases accordingly as a percentage of
the original width; that is, when it was added to the graphics page.
For example, an aerial view of a paper roll (in a paper mill), could display changing roll
thickness:

Objects have the following horizontal scaling properties:

Scaling expression
The value of the expression entered in this field (253 characters maximum) will deter-
mine the horizontal scaling (width) of the object. By default, when the expression returns
its minimum value, the object will display at its minimum width (as defined in the Scal-
ing fields below). When the expression returns its maximum value, the object will dis-
play at its maximum width (as defined in the Scaling fields below).
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

651
Chapter 21: Defining Common Object Properties

[Scaling expression] Specify range

Select this box to manually specify Minimum and Maximum values for the scaling
expression, rather than using the default values. For an expression containing an analog
variable tag, the defaults are the Engineering Zero and Full Scale values from the last
variable tag in the expression. If the analog variable tag does not have Engineering Zero
and Full Scale values, the defaults are 0 (zero) and 32000. For expressions without tags,
the defaults are 0 (zero) and 100.
[Scaling expression] Minimum
Enter the minimum value for the expression. When this value is returned by the expres-
sion, the width of the object will be reduced to its minimum. You can only enter a value
here if you have selected the Specify range box.
[Scaling expression] Maximum
Enter the maximum value for the expression. When this value is returned by the expres-
sion, the width of the object will be increased to its maximum. You can only enter a
value here if you have selected the Specify range box.
[Scaling] At minimum
The minimum width of the object (as a percentage of its original width). The object will
be reduced to this width when the Scaling expression returns its minimum value.
You can change the percentage by pressing the up and down arrows to the right of the
field, or by entering another value in this field. Percentages of greater than 100% can be
entered.
[Scaling] At maximum
The maximum width of the object (as a percentage of its original width). The object will
grow to this width when the Scaling expression returns its maximum value.
You can change the percentage by pressing the up and down arrows to the right of the
field, or by entering another value in this field. Percentages of greater than 100% can be
entered.

Note: You can increase the width at minimum, and decrease it at maximum, by
swapping the percentages in the Scaling fields (i.e. put the high percentage in the At

652
Chapter 21: Defining Common Object Properties

minimum field, and the low in the At maximum), or by swapping the expression
limits (in the Minimum and Maximum fields).

[Center axis offset] Express

Click this radio button for the quick and easy way of selecting one of three of the object's
vertical axes (left, center, and right). These axes appear in the picture field to the right of
the dialog.
If you choose Left, width changes occur to the right of the object. (i.e., the left edge
remains anchored):

If you choose Center, width changes occur equally to both sides. (i.e., the vertical center
axis remains anchored):

If you choose Right, width changes occur to the left of the object. (i.e., the right edge
remains anchored):

[Center axis offset] Custom

Click this radio button to define your own center axis. A field appears to the right of the
dialog allowing you to specify how far from the object center (in pixels) you would like
to place the axis. Although this option gives you the option to place the center axis any-
where on the object, once placed, the scaling process works in exactly the same manner
as for the Express option (illustrated above).

653
Chapter 21: Defining Common Object Properties

For example, if you enter 20, the Center axis will be 20 pixels to the right of the object
center.
Enter a negative value to move the center axis left instead of right.

Note: If a group and its objects are configured to change size during runtime, the
group scaling effects will be combined with the object scaling effects. For example, if
a group is configured to double in size at runtime, and one of its objects is con-
figured to halve in size, the object will appear to remain the same size (it halves,
then doubles). Remember, however, that the object's position might change as the
group gets bigger.

See Also
Object Properties - Scaling (Vertical)

Object Properties - Scaling (Vertical)

You can change the height of an object during runtime. As the value of the expression
increases or decreases, the height of the object increases or decreases accordingly as a per-
centage of the original height; that is, when the object was added to the graphics page.
For example, an elevation of a paper roll (in a paper mill), could display changing roll
height (and width):

Objects have the following vertical scaling properties:

Scaling expression
The value of the expression entered in this field (253 characters maximum) will deter-
mine the vertical scaling (height) of the object. By default, when the expression returns
its minimum value, the object will display at its minimum height (as defined in the Scal-
ing fields below). When the expression returns its maximum value, the object will dis-
play at its maximum height (as defined in the Scaling fields below).
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

654
Chapter 21: Defining Common Object Properties

[Scaling expression] Specify range

Select this box to manually specify Minimum and Maximum values for the scaling
expression, rather than using the default values. For an expression containing an analog
variable tag, the defaults are the Engineering Zero and Full Scale values from the last
variable tag in the expression. If the analog variable tag does not have Engineering Zero
and Full Scale values, the defaults are 0 (zero) and 32000. For expressions without tags,
the defaults are 0 (zero) and 100.
[Scaling expression] Minimum
Enter the minimum value for the expression. When this value is returned by the expres-
sion, the height of the object will be reduced to its minimum. You can only enter a value
here if you have selected the Specify range box.
[Scaling expression] Maximum
Enter the maximum value for the expression. When this value is returned by the expres-
sion, the height of the object will be increased to its maximum. You can only enter a
value here if you have selected the Specify range box.
[Scaling] At minimum
The minimum height of the object (as a percentage of its original height). The object will
be reduced to this height when the Scaling expression returns its minimum value. You
can change the percentage by pressing the up and down arrows to the right of the field,
or by entering another value in this field. Percentages of greater than 100% can be
entered.
[Scaling] At maximum
The maximum height of the object (as a percentage of its original height). The object will
grow to this height when the Scaling expression returns its maximum value.
You can change the percentage by pressing the up and down arrows to the right of the
field, or by entering another value in this field. Percentages of greater than 100% can be
entered.

Note: You can increase the height at minimum, and decrease it at maximum, by
swapping the percentages in the Scaling fields (i.e. put the high percentage in the At

655
Chapter 21: Defining Common Object Properties

minimum field, and the low in the At maximum), or by swapping the expression
limits (in the Minimum and Maximum fields).

[Center axis offset] Express

Click this radio button to select one of three of the object's horizontal axes (top, middle,
and bottom). These axes appear in the picture field to the right of the dialog. Click an
axis to select it.
If you choose the top, height changes will occur from the top of the object down. (i.e. the
top edge will remain anchored):

If you choose the middle, height changes will occur equally above and below the axis.
(i.e. the horizontal center axis will remain anchored):

If you choose the bottom, width changes will occur to the top edge of the object. (i.e. the
bottom edge will remain anchored):

[Center axis offset] Custom

Click this radio button to define your own center axis. A field will display to the right of
the dialog, allowing you to specify how far from the object center (in pixels) you would
like to place the axis. Although this option gives you the freedom to place the center axis
anywhere on the object, once placed, the scaling process works in exactly the same
manner as for the Express option (illustrated above).

656
Chapter 21: Defining Common Object Properties

For example, if you enter 20, the Center axis will be 20 pixels below the object center.
Enter a negative value to move the Center axis up instead of down.
Notes:
l If a group and its objects are configured to change size during runtime, the group
scaling effects will be combined with the object scaling effects. For example, if a group
is configured to double in size at runtime, and one of its object is configured to halve
in size, the object will appear to remain the same size (it halves, then doubles).
Remember, however, that the object's position might change as the group gets bigger.
l When the radio buttons in Object Properties - Fill Color (On/Off, Multi-state and so
on) are selected, they change the appearance of the right-hand side of the dialog.
See Also
Object Properties - Scaling (Horizontal)

Fill Color
You can control the fill color to use for your objects.
To configure an object or group with changing fill color:

1. Draw the object/group (or paste a symbol). The properties tab dialog will auto-
matically display, unless you have turned off the Display properties on new option
in the Graphics Builder. (For a group, the properties dialog will not display auto-
matically; you need to double-click the group.)
2. Click the Fill tab.
3. Click the Color tab (to the right of the dialog).
4. Select the type of color change (On/Off, Multi-state and so on).
5. Enter the expression/conditions that will change the object's fill color at runtime.
6. Enter additional object property details as necessary.
7. Click OK.
See Also
Object Properties - Fill Color (On/Off)
Object Properties - Fill Color (Multi-state)
Object Properties - Fill Color (Array)
Object Properties - Fill Color (Threshold)
Object Properties - Fill Color (Gradient)

Object Properties - Fill Color (On/Off)

Objects and groups have the following Fill Color (On/Off) properties:

657
Chapter 21: Defining Common Object Properties

[Type] On / Off
Select this radio button to fill the object/group with one color when a particular expres-
sion is TRUE, and another when it is FALSE. For example, you could fill an object/group
with red when a particular variable tag is in alarm, and green when it is not.
[Type] Multi-state
This option is useful when you have several possible conditions, occurring together in
different combinations, at different times. Select this option to fill the object/group with a
different color for each combination.
For example, three digital variable tags (A,B, and C) can each be ON or OFF at any time.
You can fill the object/group with a different color for each ON/OFF combination. In
other words, you could use a different fill color for each of the following ON/OFF com-
binations ABC, ABC, ABC, ABC, ABC, ABC, ABC, ABC.
[Type] Array
The Array option allows you to enter an expression which returns an integer. For each
unique integer (from 0 to 255), you can fill the object/group with a different color. For
example, you could use a different fill color for each threshold of an analog alarm.
[Type] Threshold
Select this radio button to dynamically change the fill color when an expression reaches
a specific value (threshold). For example, you might decide that the fill color will change
to red when the speed of a motor is greater than or equal to 4500 rpm, and to white
when less than or equal to 100 rpm, but remains gray for every speed in between.
[Type] Gradient
Select this radio button to dynamically graduate the fill color, displaying a different color
for each unique value returned by a particular expression. This option allows you to
select two colors, to be used as the color limits. The color for each value returned is auto-
matically selected from within the range defined by these limits. The result is a fade
from one color to another.
ON color when
The color selected as the ON color (below) will be used as the fill color whenever the con-
dition entered here (128 characters maximum) is TRUE. The color selected as the OFF
color (below) will be used as the fill color whenever this condition is FALSE. For exam-
ple, you could fill an object/group with blue when MIX_RUNNING is TRUE, and white
when it is FALSE.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

658
Chapter 21: Defining Common Object Properties

OFF color
The fill color whenever the condition entered above is FALSE. For example, you could
fill the object/group with white when MIX_RUNNING is FALSE.

Note: The color that you select here will change any Fill color specified through
Appearance (General) properties tab.

ON color
The fill color whenever the condition entered above is TRUE. For example, you could fill
the object/group with blue when MIX_RUNNING is TRUE.

Note: Group fill color is only applied if the individual objects in the group do not
have their own fill colors defined.

See Also
Object Properties - Fill Color (Multi-state)
Object Properties - Fill Color (Array)
Object Properties - Fill Color (Threshold)
Object Properties - Fill Color (Gradient)

Object Properties - Fill Color (Multi-state)

Objects and groups have the following Fill Color (Multi-state) properties:
[Type] On / Off
Select this radio button to fill the object/group with one color when a particular expres-
sion is TRUE, and another when it is FALSE. For example, you could fill an object/group
with red when a particular variable tag is in alarm, and green when it is not.
[Type] Multi-state
This option is useful when you have several possible conditions, occurring together in
different combinations, at different times. Select this option to fill the object/group with a
different color for each combination.

659
Chapter 21: Defining Common Object Properties

For example, three digital variable tags (A,B, and C) can each be ON or OFF at any time.
You can fill the object/group with a different color for each ON/OFF combination. In
other words, you could use a different fill color for each of the following ON/OFF com-
binations ABC, ABC, ABC, ABC, ABC, ABC, ABC, ABC.
[Type] Array
The Array option allows you to enter an expression which returns an integer. For each
unique integer (from 0-255), you can fill the object/group with a different color. For exam-
ple, you could use a different fill color for each threshold of an analog alarm.
[Type] Threshold
Select this radio button to dynamically change the fill color when an expression reaches
a specific value (threshold). For example, you might decide that the fill color will change
to red when the speed of a motor is greater than or equal to 4500 rpm, and to white
when less than or equal to 100 rpm, but remains gray for every speed in between.
[Type] Gradient
Select this radio button to dynamically graduate the fill color, displaying a different color
for each unique value returned by a particular expression. This option allows you to
select two colors, to be used as the color limits. The color for each value returned is auto-
matically selected from within the range defined by these limits. The result is a fade
from one color to another.
Conditions
The conditions you enter here (using a maximum of 128 characters per condition) will
occur together in different ways, at different times. You can use each unique combination
to force a different fill color for the object/group.
To enter a condition, click the relevant line (A, B, C, and so on), click Edit, and type in
the condition. You can add more conditions (to a maximum of 5, providing 32 com-
binations), using the Add button. To insert a tag or function, click the Wizard button.
This button displays two options: Insert Tag and Insert Function.

You can also remove conditions by clicking Delete, but you need to always provide at
least one condition in this field. Conditions left blank (instead of deleted) are evaluated
as false at runtime.
State colors

660
Chapter 21: Defining Common Object Properties

The fill colors that will be used for each combination of the above conditions.

Note: The color that you select as ABC (all conditions false) will change any Fill
color specified through Appearance (General) properties tab.

For example:
To fill the object/group with a different color each time the status of a valve changes, you
could fill out the Conditions and State symbols fields as follows:

In this example, Open_Feedback, and Close_Feedback are variable tags representing

digital inputs on the valve, and Open_Output is a variable tag representing an output
on the valve. So, ABC means Open_Feedback is ON, and Close_Feedback and Open_
Output are both OFF. For this combination, the red is used as the fill color to indicate
that the valve is not responding to commands, because it is open when it is meant to be
closed. The same type of logic applies to the rest of the states.

Note: Group fill color is only applied if the individual objects in the group do not
have their own fill colors defined.

See Also
Object Properties - Fill Color (On/Off)
Object Properties - Fill Color (Array)
Object Properties - Fill Color (Threshold)
Object Properties - Fill Color (Gradient)

Object Properties - Fill Color (Array)

Objects and groups have the following Fill Color (Array) properties:
[Type] On / Off

661
Chapter 21: Defining Common Object Properties

Select this radio button to fill the object/group with one color when a particular expres-
sion is TRUE, and another when it is FALSE. For example, you could fill an object/group
with red when a particular variable tag is in alarm, and green when it is not.
[Type] Multi-state
This option is useful when you have several possible conditions, occurring together in
different combinations, at different times. Select this option to fill the object/group with a
different color for each combination.
For example, three digital variable tags (A,B, and C) can each be ON or OFF at any time.
You can fill the object/group with a different color for each ON/OFF combination. In
other words, you could use a different fill color for each of the following ON/OFF com-
binations ABC, ABC, ABC, ABC, ABC, ABC, ABC, ABC.
[Type] Array
The Array option allows you to enter an expression which returns an integer. For each
unique integer (from 0-255), you can fill the object/group with a different color. For exam-
ple, you could use a different fill color for each threshold of an analog alarm.
[Type] Threshold
Select this radio button to dynamically change the fill color when an expression reaches
a specific value (threshold). For example, you might decide that the fill color will change
to red when the speed of a motor is greater than or equal to 4500 rpm, and to white
when less than or equal to 100 rpm, but remains gray for every speed in between.
[Type] Gradient
Select this radio button to dynamically graduate the fill color, displaying a different color
for each unique value returned by a particular expression. This option allows you to
select two colors, to be used as the color limits. The color for each value returned is auto-
matically selected from within the range defined by these limits. The result is a fade
from one color to another.
Array expression (128 Chars.)
Enter the expression which is to return an integer. For each value returned, a different
color will fill the object/group.
If the return value is:
l Less than 0 (zero), it will be set to 0 (zero), and a runtime hardware alarm will be trig-
gered.
l Greater than 255, it will be set to 255, and a runtime hardware alarm will be trig-
gered.
l A real (non-integer) number, it will be truncated (for example 8.1 and 8.7 would both
be truncated to 8).

662
Chapter 21: Defining Common Object Properties

To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

Array colors
The fill colors that will be used for each integer returned by the Array expression entered
above (color 0 will be used when the expression returns integer 0, color 1 will be used
when integer 1 is returned and so on).

Note: The color that you select for color 0 (zero) will change any Fill color specified
through Appearance - General tab.

For example, to display different symbols illustrating the various states of a motor, you
could fill out the Array expression and Array symbol fields as follows:

In this example, MOTOR_STATUS is an analog variable tag representing the status of

a motor. Each time the motor changes state, an integer is returned (0 = Running, 1 = Start-
ing and so on), and the appropriate color fills the object/group. Color 5 onwards have no
bearing on the fill color, because the tag only returns 5 unique integers (0-4).

Note: Group fill color is only applied if the individual objects in the group do not
have their own fill colors defined.

See Also
Object Properties - Fill Color (On/Off)
Object Properties - Fill Color (Multi-state)

663
Chapter 21: Defining Common Object Properties

Object Properties - Fill Color (Threshold)

Object Properties - Fill Color (Gradient)

Object Properties - Fill Color (Threshold)

Objects and groups have the following fill color (threshold) properties.
[Type] On / Off
Select this radio button to fill the object/group with one color when a particular expres-
sion is TRUE, and another when it is FALSE. For example, you could fill an object/group
with red when a particular variable tag is in alarm, and green when it is not.
[Type] Multi-state
This option is useful when you have several possible conditions, occurring together in
different combinations, at different times. Select this option to fill the object/group with a
different color for each combination.
For example, three digital variable tags (A,B, and C) can each be ON or OFF at any time.
You can fill the object/group with a different color for each ON/OFF combination. In
other words, you could use a different fill color for each of the following ON/OFF com-
binations ABC, ABC, ABC, ABC, ABC, ABC, ABC, ABC.
[Type] Array
The Array option allows you to enter an expression which returns an integer. For each
unique integer (from 0-255), you can fill the object/group with a different color. For exam-
ple, you could use a different fill color for each threshold of an analog alarm.
[Type] Threshold
Select this radio button to dynamically change the fill color when an expression reaches
a specific value (threshold). For example, you might decide that the fill color will change
to red when the speed of a motor is greater than or equal to 4500 rpm, and to white
when less than or equal to 100 rpm, but remains gray for every speed in between.
[Type] Gradient
Select this radio button to dynamically (and smoothly) graduate the fill color, displaying
a different color for each unique value returned by a particular expression. This option
allows you to select two colors, to be used as the color limits. The color for each value
returned is automatically selected from within the range defined by these limits. The
result is a smooth fade from one color to another.
Color expression
The value of the expression entered in this field (128 characters maximum) determines
the fill color of the object/group. i.e. When the value of this expression reaches a thresh-
old value (as defined below), fill color will change.

664
Chapter 21: Defining Common Object Properties

To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

[Color expression] Specify range

Select this box to manually specify Minimum and Maximum values for the Color expres-
sion, rather than using the default values. (Threshold values are percentages of the range
between Minimum and Maximum.) For an expression containing an analog variable
tag, the defaults are the Engineering Zero and Full Scale values from the last variable tag
in the expression. If the analog variable tag does not have Engineering Zero and Full
Scale values, the defaults are 0 (zero) and 32000. For expressions without tags, the
defaults are 0 (zero) and 100.
[Color expression] Minimum
Enter the minimum value for the expression. In terms of thresholds, the Minimum is
0%. You can only enter a value here if you have selected the Specify range box.
[Color expression] Maximum
Enter the maximum value for the expression. In terms of thresholds, the Maximum is
100%. You can only enter a value here if you have selected the Specify range box.
Thresholds (%)
The thresholds and their associated colors. A threshold is entered as a percentage of the
expression range (the range of values that can be returned by the expression). For exam-
ple, if the expression's minimum is 0 and its Maximum 200, the default thresholds
would have the following effects:

Thresh- Asso- Meaning

old ciated
Color

< 5% Bright Blue When the expression returns less than 10, the color fill
will be Bright Blue.

< 15% Blue When the expression returns less than 30, the color fill
will be Blue.

> 85% Red When the expression returns greater than 170, the color

665
Chapter 21: Defining Common Object Properties

fill will be Red.

> 95% Bright Red When the expression returns greater than 190, the color
fill will be Bright Red.

You can add up to 100 threshold color combinations. To add a combination, click Add
and enter the relevant details. To edit an existing combination, click the relevant line.
You can also remove combinations by clicking Delete.
Any values not included in a range (for example between 15% and 85% in the example
above) produce a static fill color as specified through Appearance - General tab.

Note: Group fill color is only applied if the individual objects in the group do not
have their own fill colors defined.

See Also
Object Properties - Fill Color (On/Off)
Object Properties - Fill Color (Multi-state)
Object Properties - Fill Color (Array)
Object Properties - Fill Color (Gradient)

Object Properties - Fill Color (Gradient)

Objects and groups have the following Fill Color (Gradient) properties:
[Type] On / Off
Select this radio button to fill the object/group with one color when a particular expres-
sion is TRUE, and another when it is FALSE. For example, you could fill an object/group
with red when a particular variable tag is in alarm, and green when it is not.
[Type] Multi-state
This option is useful when you have several possible conditions, occurring together in
different combinations, at different times. Select this option to fill the object/group with a
different color for each combination.
For example, three digital variable tags (A,B, and C) can each be ON or OFF at any time.
You can fill the object/group with a different color for each ON/OFF combination. In
other words, you could use a different fill color for each of the following ON/OFF com-
binations ABC, ABC, ABC, ABC, ABC, ABC, ABC, ABC.
[Type] Array
The Array option allows you to enter an expression which returns an integer. For each
unique integer (from 0 to 255), you can fill the object/group with a different color. For
example, you could use a different fill color for each threshold of an analog alarm.

666
Chapter 21: Defining Common Object Properties

[Type] Threshold
Select this radio button to dynamically change the fill color when an expression reaches
a specific value (threshold). For example, you might decide that the fill color will change
to red when the speed of a motor is greater than or equal to 4500 rpm, and to white
when less than or equal to 100 rpm, but remains gray for every speed in between.
[Type] Gradient
Select this radio button to dynamically graduate the fill color, displaying a different color
for each unique value returned by a particular expression. This option allows you to
select two colors, to be used as the color limits. The color for each value returned is auto-
matically selected from within the range defined by these limits. The result is a fade
from one color to another.
Color expression
The value of the expression entered in this field (128 characters maximum) will deter-
mine the fill color of the object/group. By default, when the expression returns its mini-
mum value, the fill color will be the At minimum color (as defined below). When the
expression returns its maximum value, the fill color will be the At maximum color (as
defined below). When the expression returns a value half-way between its minimum
and maximum, a color will be selected from the half-way point of the range defined by
the At minimum and At maximum colors.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

[Color expression] Specify range

Select this box to manually specify Minimum and Maximum values for the Color expres-
sion, rather than using the default values. For an expression containing an analog var-
iable tag, the defaults are the Engineering Zero and Full Scale values from the last
variable tag in the expression. If the analog variable tag does not have Engineering Zero
and Full Scale values, the defaults are 0 (zero) and 32000. For expressions without tags,
the defaults are 0 (zero) and 100.
[Color expression] Minimum

667
Chapter 21: Defining Common Object Properties

Enter the minimum value for the expression. When this value is returned by the expres-
sion, the fill color of the object/group will be the At minimum color. You can only enter a
value here if you have selected the Specify range box.
[Color expression] Maximum
Enter the maximum value for the expression. When this value is returned by the expres-
sion, the fill color of the object/group will be the At maximum color. You can only enter
a value here if you have selected the Specify range box.
At minimum
The fill color of the object/group when the Color expression returns its minimum value.

Note: The color that you select here will change any Fill color specified through
Appearance - General tab.

At maximum
The fill color of the object/group when the Color expression returns its maximum value.

Note: Group fill color is only applied if the individual objects in the group do not
have their own fill colors defined.

See Also
Object Properties - Fill Color (On/Off)
Object Properties - Fill Color (Multi-state)
Object Properties - Fill Color (Array)
Object Properties - Fill Color (Threshold)

Fill Level
You can control the fill level shown in your objects.
To configure an object or group with changing fill level:

668
Chapter 21: Defining Common Object Properties

5. Enter additional properties as necessary.

6. Click OK.
See Also
Object Properties - Fill (Level)
Defining Common Object Properties

Object Properties - Fill (Level)

The fill level of an object/group can be changed during runtime, increasing or decreasing
dynamically whenever the value of a particular expression changes. As the value of the
expression increases and decreases, the fill level will increase and decrease accordingly
(as a percentage of the full capacity of the object/group). If the object/group resizes at run-
time, the fill level will adjust automatically in order to maintain the correct percentage.
The color that is used is set through either General Appearance, or Color Fill.
This property could be used to display temperature variations. You could even combine
the Fill Color and Fill Level properties to produce a thermometer with mercury that rises
and changes color with rising temperature.
Objects and groups have the following Fill Level properties:
Level expression
The value of the expression entered in this field (253 characters maximum) will deter-
mine the fill level of the object/group. By default, when the expression returns its mini-
mum value, the object/group will be filled to the At minimum level. When the
expression returns its maximum value, the object/group will be filled to the At max-
imum level. When the expression returns a value half-way between its minimum and
maximum, the object/group will be filled to half-way between the At minimum and At
maximum levels.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

[Level expression] Specify range

669
Chapter 21: Defining Common Object Properties

Select this box to manually specify Minimum and Maximum values for the Level expres-
sion, rather than using the default values. For an expression containing an analog var-
iable tag, the defaults are the Engineering Zero and Full Scale values from the last
variable tag in the expression. If the analog variable tag does not have Engineering Zero
and Full Scale values, the defaults are 0 (zero) and 32000. For expressions without tags,
the defaults are 0 (zero) and 100.
[Level expression] Minimum
Enter the minimum value for the expression. When this value is returned by the expres-
sion, the object/group will fill to the At minimum level. You can only enter a value here
if you have selected the Specify range box.
[Level expression] Maximum
Enter the maximum value for the expression. When this value is returned by the expres-
sion, the object/group will fill to the At maximum level. You can only enter a value here
if you have selected the Specify range box.
At minimum
The level to which the object/group will be filled when the Level expression returns its
minimum value. For example, if you enter 30, the object/group will be 30% full when the
expression returns its minimum value.
You can change the percentage by pressing the up and down arrows to the right of the
field, or by entering another value in this field.
At maximum
The level to which the object/group will be filled when the Level expression returns its
maximum value. For example, if you enter 90, the object/group will be 90% full when the
expression returns its maximum value.
You can change the percentage by pressing the up and down arrows to the right of the
field, or by entering another value in this field.
Fill Direction
The direction in which the color will spread when increasing. There are four options
(each represented by an arrow): Up, Down, Left, Right. If you choose Up, the
object/group will be filled from the bottom up. If you choose Left, the object/group will be
filled from right to left, and so on
Background color
The color of any unfilled part of the object/group (for example, if the object/group is only
90% full, the unfilled 10% will be display using this color). The background is often
made transparent. Using transparent, you would see the outline of the object/group, and
anything behind the object/group on the page.

670
Chapter 21: Defining Common Object Properties

Note: If an object in a group is a slider, it might change the overall size of the group
when used at runtime. If it does, the fill level of the group will adjust accordingly.

Group and Object Fill Level: Examples

A group and its objects can be configured with different fill levels. The group fill level,
however, is usually thought of as a reveal of the objects in the group. Group fill level
and object fill level operate independently of each other; the group fill level just deter-
mines how much of the objects display.
Example 1: The fill level of the objects:

Example 2: Group the objects and configure a fill level for the group as well

671
Chapter 21: Defining Common Object Properties

In this example, the objects' fill levels can still be adjusted normally. The group's fill
level determines how much of the objects you can see (and how much will be obscured
by the groups background color; white, in this case).

Touch Commands
You can assign touch commands to an object or group.
To assign a touch command to an object or group:

672
Chapter 21: Defining Common Object Properties

See Also
Object Properties - Input (Touch)
Defining Common Object Properties

Object Properties - Input (Touch)

The touch property lets you assign commands to the object/group. These commands are
then executed when the object/group is touched at runtime (i.e., an operator clicks on the
object/group). You can also define messages which will log at these times.
For example, a drive can be jogged by starting it when the mouse button is depressed
and stopping it when the mouse button released; variables can be incremented while the
mouse button is held, and so on. At the same time, it could log the time and date, and
the name of the operator.
Operators who do not satisfy the access requirements cannot touch the object/group at
runtime.
Objects and groups have the following input (touch) properties.
Action
There are three actions to which commands can be attached. You can select more than
one type of action. Unique commands and log messages can be attached to each action
(i.e. you can perform one task on the down action, and another on the up action, and log
a separate message for each).
[Action] Up
Select this option if you want a command to be executed (and a unique message to be
logged) when the operator positions the mouse pointer over the object/group, and clicks
and releases the left mouse button.
As with standard Windows buttons, if the operator moves the cursor away from the
object/group before releasing the mouse button, the command isn't executed (unless you
also select the Down option).
[Action] Down
Select this option if you want a command to be executed (and a unique message to be
logged) when the operator positions the mouse pointer over the object/group, and clicks
the left mouse button. The command will execute as soon as the mouse button is clicked.

[Action] Repeat

673
Chapter 21: Defining Common Object Properties

Select this option if you want a command to execute continually (and a unique message
to log continually) whenever the operator has the mouse pointer positioned over the
object/group, and is holding the left mouse button depressed. If the operator moves the
mouse pointer away from the object/group without releasing the mouse button, the com-
mand will stop executing, but will start again as soon as the mouse pointer is re-posi-
tioned over the object/group. The only exception is when you also have the Down option
selected, in which case, the command will execute continually even if the mouse pointer
has been moved away from the object/group.
To set the delay which precedes the first execution of the command (and the first log of
the message), and the delay between each repeat.
Up/Down/Repeat command
The commands (set of instructions) to be executed immediately when the selected action
is performed. The command(s) can be a maximum of 253 characters long.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

[Logging] Log Message

The text message sent to the MsgLog field of the Log Device when the selected action is
performed by the operator at runtime. The message is plain text, and can include tag
name substitutions using Genie or Super Genie syntax. When using Super Genie syntax,
the data type needs to be specified. The name of the tag will then be included in the text.
The log message can be a maximum of 32 characters long.

To include field data as part of a logged message, insert the field name as part of the
device format when configuring the device. For instance, in the Format field of the
Devices form, you could enter {MsgLog,20} {FullName,15}. This would accommodate the
logging of messages such as P2 started by John Smith.
The log device to which the message is sent is specified through the General Access tab.

Note: If the object is part of a Genie or symbol, this property can be defined after the

674
Chapter 21: Defining Common Object Properties

Genie/symbol is pasted onto a page. (Hold down the Control (CTRL) key and double-
click the object.) If you define it before pasting (i.e. you define it for the original in the
library), you cannot edit it after. Similarly, if the object is part of a template, it can be
defined after a page has been created using that template (again, with Control + dou-
ble-click). If you define it for the actual template, you cannot edit it for pages based
on the template.

Repeat rate
This option sets the delay which precedes the first execution of the command(s), and the
delay between each subsequent repeat of the command(s).
You can change the rate by pressing the up and down arrows to the right of the field, or
by entering another value in this field.

Note: If you define a touch command for an object in a group, the group's touch com-
mand will not work.

Keyboard Commands
You can assign a keyboard command to an object or group.
To assign a keyboard command to an object or group:

1. Draw the object/group (or paste a symbol). The object properties tab dialog will auto-
matically display, unless you have turned off the Display properties on new option
in the Graphics Builder. (For a group, the properties dialog will not display auto-
matically; you need to double-click the group.)
2. Click the Input tab.
3. Click the Keyboard Commands tab (to the right of the dialog).
4. Enter the key sequence.
5. Enter a command in the command field (the command that will be executed when
the key sequence above is entered by the operator at runtime).
6. Enter additional details as necessary.
7. Click OK.
See Also
Object Properties - Input (Keyboard Commands)
Defining Common Object Properties

675
Chapter 21: Defining Common Object Properties

Object Properties - Input (Keyboard Commands)

The keyboard commands property lets you assign keyboard commands to the
object/group. A keyboard command is a particular key sequence which executes a com-
mand when it is typed in by the operator at runtime. To execute an object/group key-
board command, the operator positions the cursor over the object/group and enters the
key sequence using the keyboard.
You can also define a message which will log every time the key sequence is entered.
For example, the operator could change the water level in a tank by placing the mouse
over the symbol representing the tank, and typing in the new level. At the same time, a
message could be logged, listing the time and date, and the name of the operator.
Operators who do not satisfy the access requirements specified under Security below can-
not enter keyboard commands for this object/group at runtime.
For a detailed explanation of keyboard command input see the topic Getting Runtime
Operator Input in the Cicode Programming Reference.
Objects and groups have the following keyboard commands input properties:
Key sequence
Enter the key sequences that the operator can enter to execute a command. For example,
you might define the key sequence ### Enter. During runtime, this key sequence would
allow you to type in any three digit number, and click Enter to change variable tag
values from mimic pages and so on
You can enter as many key sequences as you like. To add a key sequence, click Add and
type in the sequence or select one from the menu. To edit an existing sequence, click the
relevant line and click Edit. You can also remove key sequences by clicking Delete.
Key sequence command
The commands (set of instructions) to be executed immediately when the selected key
sequence is entered. The commands can be a maximum of 253 characters long.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

[Security] Same area as object/group

676
Chapter 21: Defining Common Object Properties

Select this box to assign the keyboard command to the same area as the object/group.
Only users with access to this area (and any necessary privileges) will be able to issue
this command or log the message. If you want to assign this keyboard command to
another area, do not select this box; instead, enter another area below.
[Security] Command area
Enter the area to which this keyboard command belongs. Only users with access to this
area (and any necessary privileges) will be able to issue this command or log the mes-
sage. For example, if you enter Area 1 here, operators need to have access to Area 1 (plus
any necessary privileges) to issue this command.
Click the menu to the right of this field to select an area, or type in an area number
directly.

Note: If the object is part of a Genie or symbol, this property can be defined after the
Genie/symbol is pasted onto a page (Ctrl + double-click). Similarly, if the object is
part of a template, this property can be defined after a page has been created using
that template (Ctrl + double-click).

You can leave this field blank by selecting the Same privilege as object/group box.
[Security] Same privilege as object/group
Select this box to assign the keyboard command the same privilege as the object/group.
Only users with this privilege level will be able to issue this command, or log the mes-
sage. If you want to assign this keyboard command a different privilege, do not select
this box; instead, enter another privilege below.
[Security] Privilege level
Enter the privilege level that a user needs to possess to be able to issue this command or
log the message. For example, if you enter Privilege Level 1 here, operators need to pos-
sess Privilege Level 1 to be able to issue this command. You can also combine this
restriction with area restrictions. For example, if you assign the keyboard command to
Area 5, with Privilege Level 2, the user needs to be set up with Privilege 2 for Area 5.
Click the menu to the right of this field to select a privilege, or type in an area number
directly.

You can leave this field blank by selecting the Same privilege as object/group box.
[Logging] Log Message

677
Chapter 21: Defining Common Object Properties

If you want to include field data as part of a logged message, you need to insert the field
name as part of the device format when you configure the device. For instance, in the
Format field of the Devices form, you could enter {MsgLog,20} {FullName,15}. This
would accommodate the logging of messages such as P2 started by John Smith.
The log device to which the message is sent is specified through the General Access tab.

Note: If a group and one of its objects are both assigned a keyboard command with
the same key sequence, the object's command will take precedence (i.e., the group's
command will not execute).

Sliders
You can create sliders to have on your graphics pages.
To configure a slider:

678
Chapter 21: Defining Common Object Properties

Object Properties - Slider (Horizontal)

Objects and groups can be linked to variable tags in such a way that horizontal sliding
of the object/group changes the value of the tag. As the slider moves to the right, the var-
iable tag increases in value. As the slider moves to the left, the variable tag decreases in
value. The slider also moves automatically to reflect the changing values of the tag.

Note: The horizontal slider cannot be used if the rotational slider is enabled, or if hor-
izontal movement is enabled.

Objects and groups have the following horizontal slider properties.

Tag
The value of the tag entered in this field (79 characters maximum) will change when the
slider is moved left or right. You can define two slider limits on your graphics page. The
object/group will not slide beyond these two points. During runtime, when the slider
reaches its left-hand limit (Offset At minimum), the tag value changes to its minimum
limit. When the slider reaches its right-hand limit (Offset At maximum), the tag value
changes to its maximum limit.
To insert a tag, click the Wizard button to the right of this field.

[Tag] Continuous update of tag

679
Chapter 21: Defining Common Object Properties

The distance (number of pixels from the original object/group center) that the
object/group can slide to the right. When it reaches the point defined by this distance, the
tag value changes to its maximum limit.
You can change the offset value by pressing the up and down arrows to the right of the
field, or by entering another value in this field.
You can increase the value of the tag with a left-slide, and decrease it with a right-slide,
by entering negative distances in the Offset fields.

Note: If an object in a group is a slider, it might change the overall size of the group
when used at runtime. If it does, the fill level of the group will adjust accordingly. If
a group and one of its objects are both defined as sliders, and they slide in the same
direction or one is rotational, the object will take precedence (i.e. only the object will
operate as a slider).

See Also
Object Properties - Slider (Vertical)
Object Properties - Slider (Rotational)

Object Properties - Slider (Vertical)

You can link objects and groups to variable tags in such a way that vertical sliding of
the object/group changes the value of the tag. As the slider moves to the up, the variable
tag increases in value. As the slider moves to the down, the variable tag decreases in
value. The slider also moves automatically to reflect the changing values of the tag.

Note: The vertical slider cannot be used if the rotational slider is enabled, or if ver-
tical movement is enabled.

Objects and groups have the following vertical slider properties:

Tag
The value of the tag entered in this field (79 characters maximum) will change when the
slider is moved up or down. You can define two slider limits on your graphics page.
The object/group will not slide beyond these two points. During runtime, when the slider
reaches its upper limit (Offset At maximum), the tag value changes to its maximum
limit. When the slider reaches its lower limit (Offset At minimum), the tag value
changes to its minimum limit.
To insert a tag, click the Wizard button to the right of this field.

680
Chapter 21: Defining Common Object Properties

[Tag] Continuous update of tag

Select this box if you want the variable tag to be updated continuously while the slider is
being moved. If you do not select this box, the tag will only be updated when the slider
has been released (i.e., it has been moved, and the operator has released the mouse but-
ton).
[Offset] At maximum
The distance (number of pixels from the original object/group center) that the
object/group can slide up. When it reaches the point defined by this distance, the Tag
value changes to its maximum limit.
You can change the offset value by pressing the up and down arrows to the right of the
field, or by entering another value in this field.
[Offset] At minimum
The distance (number of pixels from the original object/group center) that the
object/group can slide down. When it reaches the point defined by this distance, the tag
value changes to its minimum limit.
You can change the offset value by pressing the up and down arrows to the right of the
field, or by entering another value in this field.
You can increase the value of the tag with a down-slide, and decrease it with an up-
slide, by entering negative distances in the Offset fields.

Note: If an object in a group is a slider, it might change the overall size of the group
when used at runtime. If it does, the fill level of the group will adjust accordingly. If
a group and one of its objects are both defined as sliders, the object will take prec-
edence (i.e. only the object will operate as a slider).

See Also
Object Properties - Slider (Horizontal)
Object Properties - Slider (Rotational)

681
Chapter 21: Defining Common Object Properties

Object Properties - Slider (Rotational)

Objects and groups can be linked to variable tags in such a way that rotational sliding of
the object/group changes the value of the tag. As the slider rotates clockwise, the variable
tag increases in value. As the slider rotates anti-clockwise, the variable tag decreases in
value. The slider also moves automatically to reflect the changing values of the tag.

Note: The rotational slider cannot be used if either of the other sliders is enabled, or
if rotational movement is enabled.

Objects and groups have the following rotational slider properties.

Tag
The value of the tag entered in this field (79 characters maximum) will change as the
slider is rotated. You can define two slider limits on your graphics page. The
object/group will not rotate beyond these two points. During runtime, when the slider
reaches its anti-clockwise limit (Offset At minimum), the tag value changes to its mini-
mum limit. When the slider reaches its clockwise limit (Offset At maximum), the tag
value changes to its maximum limit.
To insert a tag, click the Wizard button to the right of this field.

[Tag] Continuous update of tag

682
Chapter 21: Defining Common Object Properties

Enter an clockwise angle (in degrees relative to 0 degrees). The slider cannot rotate clock-
wise beyond this limit. When it reaches this limit, the Tag value changes to its max-
imum limit.
You can change the angle value by pressing the up and down arrows to the right of the
field, or by entering another value in this field.

Note:You can increase the value of the tag with an anti-clockwise slide, and decrease
it with a clockwise-slide, by entering negative distances in the Angle fields.

[Center axis offset] Express

Click this radio button for the quick and easy way of selecting the point about which the
object/group will rotate. The express option gives you the choice of 9 points (Top Left,
Bottom Right and so on), which are displayed in the picture field on the dialog. To select
one, just click it with your mouse.
[Center axis offset] Custom
Click this radio button to define your own center axis. When you select this radio button,
two fields will display to the right, allowing you to plot the position of your center axis.
Specify the distance to the right in the first field, and the distance down in the second.
The Center axis is plotted based on these two values.
For example, if you enter 8 as the horizontal offset and 13 as the vertical, the center axis
will be 8 pixels to the right and 13 pixels below the center of the object/group.
Enter negative values in the offset distance fields to move the center axis left instead of
right, and up instead of down.

Note:If a group and one of its objects are both defined as sliders, the object will take
precedence (i.e., only the object will operate as a slider).

See Also
Object Properties - Slider (Horizontal)
Object Properties - Slider (Vertical)

Access
You can determine the kind of access you want to have to your objects.
l General Access to Objects
l Disable Access to Objects

683
Chapter 21: Defining Common Object Properties

General Access to Objects

Use the General tab to define the general access characteristics of objects.
To define general access properties for objects:

1. Double-click the object.

2. Click the Access tab.
3. Click the General tab.
4. Enter details as necessary, then click OK.
See Also
Object Properties - Access (General)
Defining Common Object Properties

Object Properties - Access (General)

Use the Object Properties dialog to set up general identification, security, logging, and
privilege parameters for your ActiveX object.
Objects and groups have the following general access properties.
[Identification] Object/Group AN
Displays the Animation number of the object/group. The AN uniquely identifies the
object/group, and can be used in Cicode functions and so on.

Note: If the object is part of a Genie or symbol, the following properties can be com-
pleted after the Genie/Symbol is pasted onto a page (Ctrl + double-click). Similarly, if
the object is part of a template, the properties can be defined after a page has been
created using that template (Ctrl + double-click).

[Identification] Description
Enter a description of the object/group, and its various functions and so on. This field is
purely for the entry of information which you consider beneficial to the smooth running
and maintenance of your system. It will not affect the way the system runs, and it will
not display during runtime.
[Identification] Tool tip
Enter a short, meaningful description (48 characters maximum) of the object/group. Dur-
ing runtime, this description appears when the operator moves the cursor onto the
object/group. The message can be plain text, Super Genie syntax or both. When using
Super Genie syntax, the data type needs to be included. The name of the tag will then be
included in the text.

684
Chapter 21: Defining Common Object Properties

If an object in a group has a tool tip, this object's tool tip will be displayed, and not the
group's tool tip. If the object does not have a tool tip, the group tool tip will display. In
this instance, if the object is a member of a group, and that group is part of another
group, the tool tip for the first group will display.
If you place an object behind a group, its tool tip will not display. Remember, however,
that group boundaries are rectangular, no matter what shape is formed by the objects in
the group. This means that 'blank' spaces between objects in a group are actually part of
the group. Even if you can see the individual object, if it is behind the group, its tool tip
will not display.
[Security] Same area as page
Select this box to assign the object/group to the same area as the page on which it has
been drawn; otherwise, leave it blank, and enter another area in the Object/Group area
field (below).
[Security] Object/Group area
Enter the area to which this object/group belongs. Users without access to this area (and
any necessary privileges) will not be able to make full use of the object/group. They will
not be able to use touch command, keyboard commands, movement, sliders and so on.
(In order to avoid confusion for such operators, it is sometimes a good idea to disable
the object/group when it is unavailable due to lack of security rights. Disabled
objects/groups can be grayed, hidden or embossed.) For example, if you enter Area 1
here, operators need to have access to Area 1 (plus any necessary privileges) to make use
of this object/group.
Click the menu to the right of this field to select an area, or type in an area number
directly.
[Security] No privilege restrictions
Select this box to disable privilege restrictions; otherwise, leave it blank, and enter
another privilege below. The implications of not assigning a privilege restriction depend
upon whether you have used areas in your security setup:
l No Areas: Every operator has full control of the object/group.
l Areas: An operator will only need view access to control the object/group if it does
not have privilege restrictions.
[Security] Privilege level
Enter the privilege level necessary for an operator to use this object/group. Operators
without the necessary privileges will not be able to make full use of the object/group.
They will not be able to use touch command, keyboard commands, movement, sliders
and so on. (To avoid confusion for such operators, disable the object/group when it is
unavailable due to lack of security rights. Disabled objects/groups can be grayed, hidden
or embossed.) For example, if you enter Privilege Level 1 here, operators need to possess

685
Chapter 21: Defining Common Object Properties

Privilege Level 1 to use of this object/group. You can also combine this restriction with
area restrictions. For example, if you assign the object/group to Area 5, with Privilege
Level 2, the user needs to have Privilege 2 for Area 5.
Click the menu to the right of this field to select a privilege, or type in an privilege
number directly.

Note: If an object is part of a group, users need to have access to the group in order
to have access to the object.

[Logging] Log device

This is the device to which messages will be logged for the object/group's keyboard and
touch commands. Click the menu to the right of the field to select a device, or type a
device name.

Note: You need to include the MsgLog field in the format of the log device for the
message to be sent.

Disable Access to Objects

If you need to, you can disable access to objects.
To disable access to an object:

1. Double-click the object.

2. Click the Access tab.
3. Click the Disable tab.
4. Specify the condition which will disable the object as well as the appearance of the
object when disabled.
5. Click OK.
See Also
Object Properties - Access (Disable)
Defining Common Object Properties

Object Properties - Access (Disable)

Objects and groups have the following access (disable) properties
Disable when

686
Chapter 21: Defining Common Object Properties

The object/group will be disabled whenever the expression entered here (128 characters
maximum) is true. If the object/group is disabled, the operator will not be able to use any
form of input, such as sliders, touch commands, keyboard commands and so on.
To insert a tag or a function, click the Wizard button to the right of this field. This button
displays two options: Insert Tag and Insert Function.

There are three ways of indicating a disabled object/group: Embossed, Grayed, and Hid-
den.
[Disable when] Disable on insufficient area or privilege
The object/group will be disabled for operators whose area and privilege rights do not
satisfy the requirements defined in the Access.
Disable style:
l Embossed - When disabled, the object/group will look as if it has been embossed on
the graphics page.
l Grayed - When disabled, the object/group will be grayed out (all color detail will be
removed).
l Hidden - When disabled, the object/group will be entirely hidden from view.

Note: If a group is disabled, objects in that group are also disabled. The disabled
style of the group is applied to all the objects within the group. When the group is
enabled, each object uses the disabled style of itself.

687
Chapter 21: Defining Common Object Properties

688
Chapter 22: Defining Commands and Controls
Commands allow your operators to interact with the runtime system. You can define
three types of direct command controls:
l Touch commands that your operators issue by clicking specific graphics object (dis-
played on a graphics page).
l Keyboard commands that your operators issue by typing instructions on the key-
board.
l Slider controls that your operators use to change the values of analog variables.
You can assign privileges to commands and controls, and send a message to the com-
mand log each time an operator issues a command.

Touch commands
You can assign Touch commands to the objects that you create on your graphics pages.
Touch commands allow the operator to send commands to the runtime system, by click-
ing (with the mouse or similar) on an object on the graphics page. (For buttons, the com-
mand can be executed by highlighting the button with the cursor keys on the keyboard
and pressing Enter.)
You can define several commands for an object, one command to execute when the oper-
ator clicks on the object, another for when the operator releases the mouse button, and
another to operate continuously while the operator holds the mouse button down. For
example, a drive can be jogged by starting it when the mouse button is depressed and
stopping it when the mouse button released; variables can be incremented while the
mouse button is held, and so on.
You can also associate a tool tip (Help text) with an object; if the operator holds the
mouse pointer over the object, the tool tip will display in a pop-up window.

Note: You can define a disable condition for any object on a page (including but-
tons). When the condition is active, the object is grayed and the operator cannot
select it.

System Keyboard Commands

You can define system keyboard commands.
To configure a system keyboard command:

690
Chapter 22: Defining Commands and Controls

1. If you plan to use any special keys, you need to first define your keys.
2. In the Project Editor, choose System | Keyboard Commands.
3. Complete the properties in the System Keyboard Commands form that appears. You
need to enter a key sequence and a command.
4. Click Add to append a record you have created, or Replace to modify a record.
See Also
System keyboard command properties
Defining Commands and Controls

System keyboard command properties

System keyboard commands have the following properties:
Key Sequence (32 Chars.)
The key sequence for the command.
Command (253 Chars.)
The commands (set of instructions) to execute when an operator enters the key sequence.

Privilege (16 Chars.)

The privilege necessary by an operator to issue the command.
Comment (48 Chars.)
Any useful comment.

Extended forms fields

The following fields are implemented with extended forms (press F2).
Area (16 Chars.)
The area to which the command belongs. Only operators who belong to this area will be
able to issue this command. For example, if you enter Area 1 here, operators need to
have access to Area 1 (plus any necessary privileges) to issue this command.
Message Log (32 Chars.)
A text message sent to the MsgLog field of the Log Device when the selected action is per-
formed by the operator at runtime. The message needs to be plain text:
If you want to include field data as part of a logged message, you need to insert the field
name as part of the device format when you configure the device. For instance, in the
Format field of the Devices form, you could enter {MsgLog,20} {FullName,15}. This
would accommodate the logging of messages such as P2 started by John Smith.
The log device to which the message is sent is specified in the Log Device field below.

691
Chapter 22: Defining Commands and Controls

Log Device (16 Chars.)

The device to which the Message Log is sent when the command is issued.

Note: You need to include the MsgLog field in the format of the log device for the
message to be sent.

Keyboard Keys
You can define keyboard keys to make it easier to issue commands.
To define a keyboard key:

1. Choose System | Keyboard Keys. The Keyboard Keys dialog box appears.
2. Enter the Key Name and Key Code (and Comment if applicable).
3. Click Add to append a new record, or Replace to modify an existing record.
See Also
Keyboard keys properties
Defining Commands and Controls

Keyboard keys properties

Keyboard Keys have the following properties:
Key Name
The name assigned to the key. Enter a value of 16 characters or less. You can define a
meaningful name for any key on your keyboard, and use these keys in any keyboard
command. For example, you can define the F1 key as the Login key. When the Login key
is subsequently referenced in the system, it refers to the F1 key.
You can assign a key name to any key on the keyboard (including the alphanumeric
keys A-Z, a-z, and 0-9). However, after a key is defined as a command key it can only be
used as a command key. If you do assign a definition to an alphanumeric key (for exam-
ple the character A), then that key can not be used as a data key. Each time it is pressed,
the definition for the key is recognized and not the keyboard character itself. Keyboard
key definitions are usually only used with non-alphanumeric characters (for example the
function keys).
Key Code
The code assigned to the key name. Enter a value of 16 characters or less. The Key Code
is what links your Key Name to the actual key. You can specify the key code either as a
hexadecimal value or use the standard label already associated with the key.

692
Chapter 22: Defining Commands and Controls

Comment
Any useful comment. Enter a value of 48 characters or less.

Extended forms fields

The following fields are implemented with extended forms (press F2).
Echo
Determines if the key is echoed on the screen (when the key is used). Enter a value of 8
characters or less.

Echo TRUE

(Display (echo) the Key Name when the key is pressed. The key name is displayed on
the graphics page in the keyboard entry line - AN1)

Echo FALSE

(Do not display (echo) the Key Name when the key is pressed)
This property is optional. If you do not specify Echo, Echo defaults to True.
Keyboard Type (16 Chars.)
The type of keyboard. This field is only necessary if you have more than one type of key-
board on the same system.
If you do have more than one type of keyboard, use Keyboard Type 1 for your first type
of keyboard, use a separate number for each type (1, 2, 3, etc.), and define keys for each
keyboard. You can use the default (Type 0) for common keys.

Keyboards
You can use non-standard keyboards (as well as multiple keyboards) to control Citect-
SCADA. You can also define key names.
Using non-standard keyboards
You can use many types of keyboards with your runtime system. The most common key-
boards are IBM compatible keyboards; this type of keyboard is used as a default. Many
industrial keyboards do not conform with this standard; if you use a non-standard key-
board, you need to define each of the keyboards in the database.
Using multiple keyboards

693
Chapter 22: Defining Commands and Controls

Sometimes you might need to use keyboards of different types; for example, an IBM com-
patible keyboard in your control room and a sealed-membrane keyboard on the plant
floor. If you use more than one type of keyboard, you need to define every key for each
keyboard and assign each keyboard type to the respective computer.
You need to set the keyboard type for each computer, with the [Keyboard]Type parameter.

Note: If you define commands that use mouse buttons, test that a double-click com-
mand cannot be mistaken for a single-click command. A double-click is an extension
of a single click; a single click message will be received before a double-click mes-
sage.

Defining key names

You can refer to a keyboard key by a meaningful name, rather than by the key itself. For
example, you can refer to the F1 key as the "Help" key and the F2 key as the "Login" key.
When you use the key in a command, you can use the name you have defined.
You can assign a key name to any key on the keyboard (including the alphanumeric
keys A - Z, a -z, and 0 - 9). However, after a key is defined as a command key it can only
be used as a command key. If you do assign a definition to an alphanumeric key (for
example the character A), that key can not be used as a data key. Each time it is pressed,
the definition for the key is recognized and not the keyboard character itself. Keyboard
key definitions are usually only used with non-alphanumeric characters (for example the
function keys).
See Also
Defining Key Sequences for Commands
Defining Commands and Controls

Defining Key Sequences for Commands

To define a command, you need to specify the key sequence that the operator types to
issue the command. You can specify a single key for the key sequence, for example, the
function key F2:

Key Sequence F2

Alternatively, you can specify several keys that needs to be typed in sequence, for exam-
ple, the function key F2 followed by the Enter key:

Key Sequence F2 Enter

694
Chapter 22: Defining Commands and Controls

Note: If you use more than one key for the sequence, you need to separate each key
with a space.

You will want to avoid the ambiguity in keyboard commands that can occur if you
define separate commands that use a common key. For example, if you define a key
sequence for one command as F3, and the key sequence for a second command as F3 F4,
then when F3 is pressed, the first command would execute immediately; the second com-
mand could not execute. To avoid overlapping keyboard commands, add a delimiter to
common keyboard commands, for example:

Key Sequence F3 Enter

Command SP1 = 50;

Key Sequence F3 F4 Enter

Command SP1 = 100;

These commands do not execute until the operator types the delimiter (the Enter key).
See Also
Using a hot key
Using variable data input
Passing multiple arguments
Passing keyboard arguments to functions

Using a hot key

A command defined with a 'hot' key executes immediately the key is pressed. You can
only define a single key in the key sequence, and only use a 'hot' key to define com-
mands that act on the current keyboard buffer (for example the Backspace and Delete
keys). To define a 'hot' key, prefix the key sequence with an asterisk (*) as in the fol-
lowing example:

Key Sequence *Backspace

Command KeyBs()

At run time, this command operates in exactly the same way as the Backspace key on a
standard computer keyboard, to correct typing errors. (Each time the Backspace key is
pressed, the last key in the command line is removed.)

695
Chapter 22: Defining Commands and Controls

Note: You can only define a 'hot' key command as a system (global) command.

Using variable data input

You can configure a keyboard command to accept variable data at run time. When the
system is running, an operator can enter a value with the command, and the value is
passed as an argument (or arguments) into the Cicode command. You can therefore
define a single keyboard command that your operators use with different values. For
example, you could define the following command to set the variable SP1 at run time:

Key Sequence F3 ### Enter

Command SP1 = Arg1;

In this example, an operator can set the variable SP1 to a new value by first pressing the
F3 function key, entering the new value, and pressing the Enter key, for example:

sets the value of SP1 to 10.

Each `#' character (in the Key Sequence) represents one keyboard character that an oper-
ator can enter in the command. In the above example, the operator can enter up to three
keyboard characters when issuing the command. (The number of # characters deter-
mines the maximum number of characters that an operator can enter for the argument; if
the operator enters more than three characters, an "Invalid Command" alert message dis-
plays.)
The command in the above example could be issued as follows:

696
Chapter 22: Defining Commands and Controls

When the command is issued (the operator presses the Enter key), the value is passed to
the command at Arg1.

Note: If an operator does not enter any data (i.e., the key sequence:

is used), the value of Arg1 is zero, and the variable is set to zero. To prevent this from
happening, use the ArgValue1 label, for example:

Command SP1 = ArgValue1;

The ArgValue1 label checks for invalid input; if the input is invalid, the value of the var-
iable is not changed and the command halts. Any instructions following and invalid
Argvalue1 do not execute. You can also use the StrToValue() function.
See Also
Passing multiple arguments

697
Chapter 22: Defining Commands and Controls

Passing multiple arguments

You can pass multiple arguments into a Cicode command by separating each argument
with a comma (,). Each argument is passed into the command in sequence, and is
referred to in the command field as Arg1, Arg2, Arg3, and so on. For example:

Key Sequence F3 ###, ### Enter

Command SP1 = Arg1; SP2 = Arg2;

In this case, an operator can set two variables with the same command, for example:

sets the variables SP1 to 20 and SP2 to 35.

You can use up to eight arguments. However, avoid passing many arguments.

Note: There is no way to check if the input for each argument is valid. If an operator
does not enter any data for one of the arguments (i.e. the key sequence:

is used), the value of Arg2 is zero, and the second variable is set to zero. Do not use mul-
tiple arguments in a command if invalid input might generate undesired behavior in the
project or in the larger system.

UNINTENDED EQUIPMENT OPERATION

Do not use keystroke sequences to pass multiple arguments to Cicode commands unless
possible input combinations have been tested and determined to be safe.

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

See Also
Passing keyboard arguments to functions

698
Chapter 22: Defining Commands and Controls

Passing keyboard arguments to functions

You can also pass arguments directly to functions at run time, as in the following exam-
ple:

Key Sequence F4 ######## Enter

Command PageDisplay(Arg1);

In this example, an operator can select any graphics page (defined in the project) with a
single command, for example:

selects the "Mimic" page.

Note: Keyboard arguments are passed as string values. If the command (or function)
requires a numeric value, Cicode converts the string to a numeric value before it is
used.

If you use variable data, the operator can only enter alphanumeric characters (A - Z, a-z,
and 0 - 9) for the data. Do not use variable data input as the last item in a key sequence,
as ambiguity could occur; always use a delimiter.

Configuring Page Menus

You can configure a menu structure and use it in your graphical pages. Using the built-
in menu configuration dialog in Project Editor, you can define menu items in a hier-
archical tree structure for your project. You can assign individual menu items to a par-
ticular page, or make them available to every page. Menu items configured in included
projects will be merged with the ones configured in the main project, into a single menu
tree structure when you compile your main project. This allows extra menu items to be
automatically added to your project depending on what projects are included.

Note: A set of page templates known as StruxureWare Templates is provided with

the product.No default menus are provided with the templates themselves; however
if your project is created from a StruxureWare starter project, some common menu
items are already pre-configured in the menu configuration database (as part of the

699
Chapter 22: Defining Commands and Controls

starter project). They will be displayed on the page automatically at runtime. To view
additional pages in your project at runtime you will need to manually configure the
menu items.

Note: A set of page templates known as Tab Style Templates is provided with the
product. These templates already contain a tabbed menu system. If your pages are
based on these templates, the menu items configured in the menu configuration data-
base will be displayed on the page automatically at runtime. If no menu is defined in
the project, a default menu will be created at runtime to provide access to pages in
the project. The default menu functionality can be changed using [Page]Add-
DefaultMenu parameter.

At runtime, two types of menu trees are created.

1. The first type of menu tree allows you to access the configured menu items for
generic (all) pages or a specific page . You can access this menu tree using the Cicode
function MenuGetGenericNode. to get the page node for the generic pages, and Menu-
GetPageNode to get the menu items specific to a page.
2. The second menu tree automatically merges the menu items for the generic pages
and the items specified for the current page. You can access this menu tree using
Cicode function MenuGetWindowNode to get the root node of this menu tree.
Through the combination of Cicode and graphical objects, you can create a custom
menu system that suits your project.

Note: For existing users of the CSV_Include project, the menu definition would have
been defined in a file called Menu.dbf in your project folder. You can migrate the
menu definition in this file to the built-in menu configuration database using the
migration tool, although the CSV_Include project will continue to use the Menu.dbf
file for its page templates. This step is useful if you plan to migrate your project from
CSV_Include project to the newer set of built-in templates.

To configure menus for Tab Style templates, see Creating Custom Menus for Strux-
ureWare templates.
To configure menus for Tab Style templates, see Creating Custom Menus for Tab Style
templates.
To configure menus for CSV templates, see Creating Custom Menus for CSV templates.
See Also
Menu Configuration Properties
Menu Cicode Functions

700
Chapter 22: Defining Commands and Controls

Menu Configuration Properties

The Menu Configuration dialog has the following properties:
Level 1-4
Gives the menu hierarchy path of the entry. String length: 64 characters. Up to 4 levels of
menu hierarchy are supported. Menu entries that have the same upper levels are con-
sidered to be under the same hierarchical branch.
Menu Command
The Cicode expression to be executed when the menu item is selected. String of 256 char-
acters.
Comment
A comment about the menu entry. String of 128 characters.
Order
The relative position of a menu entry with respective to the other menu entries in the
same hierarchy level. This affects the order that the menu entries are returned through
the menu Cicode functions. If this field is left blank, it will take the default value of 0.
The relevant menu entries will be returned at the start as a result. If more than one entry
of the same order exists, they are displayed in the same order as they are defined in the
database.
Symbol
The symbol to associate with the menu entry. The String length:128 characters. A symbol
needs to be already defined in the project / included project, and specified in the format
of <library name>.<symbol name>.
Page
The page on which this entry will exist. If blank, the entry exists on every page.
Hidden when
Cicode expression to determine when the menu entry is hidden on the page. String of
256 characters.
Disabled when
Cicode expression to determine when the menu entry is disabled on the page. String of
256 characters.
Disabled style
A number to indicate how the disabled entry is displayed in the menu. It is up to the
user to decide what the numbers mean.

701
Chapter 22: Defining Commands and Controls

Width
The width of the menu entry on the page. It is up to the user to decide what units to be
used.
Checked
Whether the menu entry is initialized with a checked status.
Privilege
The user privilege of (0-8) necessary to select the menu entry.
Area
The user area (0-255) necessary to select the menu entry.

Note: At runtime, you can use the Menu family of Cicode functions to access the
information entered in the Menu Configuration dialog.

See Also
Defining Page Menus for Tab Templates

Displaying Tags
You can apply visual cues to a tag displayed on a graphics page, providing greater
emphasis to the data presented. For example, you could highlight a bad quality tag
value by presenting it in a different color or style.
This type of activity is enabled using the [Page]IgnoreValueQuality parameter, which
can be used to display a graphical representation of data quality.
[Page]IgnoreValueQuality can be used in tandem with a number of [Page] parameters to
provide different visual outcomes based on the state of a tag. For example, you could
change the text background color for a tag according to its current state using the fol-
lowing parameters:
l [Page]BadTextBackgroundColor
l [Page]ErrorTextBackgroundColor
l [Page]UncertainTextBackgroundColor
l [Page]OverideTextBackgroundColor
l [Page]ControlInhibitTextBackgroundColor
You can also use the parameter [Page]EnableQualityTooltip to enable tool tips that
present quality and timestamp data when the cursor is held over a tag.
The Tag Extension Parameters page in the CitectSCADA Example Project provides an
interactive example of how these parameters can be implemented.

702
Chapter 22: Defining Commands and Controls

Pre-requisite Alarm Information

Before configuring alarms in your project it is recommended you understand the fol-
lowing features and concepts:
l Alarm Server Redundancy
l Alarm Server Side Synchronization
l Understanding Alarms and Events in SCADA
l Understanding how the alarm information is retrieved

Understanding Alarms and Events in SCADA

Alarms and events are similar in that each is a detectable condition within your SCADA
system, but it is there the similarity ends.

705
Chapter 23: Using Alarms in SCADA

What is an Alarm?

An alarm is an indication of an undesirable condition detected by your system such as a

device that is not responding to input commands. The alarm alerts operators that this
condition needs to be fixed.
In CitectSCADA there are hardware alarms that are fully integrated into the product, and
alarms that you configure in your system.
l Hardware alarms- Diagnostic routines are continually run to check peripheral equip-
ment, such as I/O Devices. Undesirable conditions and events are reported auto-
matically to the operator. No configuration is necessary.
l Configured alarms - Alarms that report undesirable conditions in your plant (for
example, when a tank level is too high or when a motor overheats). Unlike hardware
alarms, you need to configure these alarms in your system.

Note: For the remainder of the Alarming section Configured alarms will be referred
to as Alarms.

To assist operators with alarms, you can then create graphics pages that contain infor-
mation about the alarms (such as the action an operator needs to perform to correct the
situation). Display these pages automatically when the alarm occurs, or only when an
operator uses the Alarm Help keyboard command.
Alarm properties can also be used anywhere a normal variable tag can be used. For
example the status of an alarm could be used to change the color of a symbol on a graph-
ics page.
You can view an example of alarms and some operator actions in the example project.
In the example project (at runtime) you can simulate up to ten alarms and view these
alarms on the active, disabled, alarm summary and sequence of events alarm pages.
Operator actions on alarms will vary according to the alarm page and type of alarm.

What is an Event?

Event is a detectable occurrence which is of significance to the change of SCADA. There

are three types of events: simple, tracking and condition.
l Simple Events - Simple events are typically informational messages that do not
require any particular action be taken. Such as startup or shutdown, operator logon
or logoff
l Tracking Events - Tracking events are similar to simple events. However, tracking
events typically indicate that some specific action was performed on the source by
some specific actor. Examples of tracking events are operator process actions such as
report execution, system configuration changes, access violations, etc.

706
Chapter 23: Using Alarms in SCADA

l Condition Events - Condition events are associated with the detection of some con-
dition in the supplier system that generally requires some sort of response or acknowl-
edgement by the user or operator. Example of condition events are all categories of
alarms.
You can view a snapshot of events using the sequence of events page at runtime.
See Also

Understanding how the alarm information is retrieved

In CitectSCADA alarm information is retrieved by subscribing to tags on the IO Server.
The requested update rate for these subscriptions is determined by the parameter
[Alarm]ScanTime. Set in milliseconds it is the minimum rate the IO server polls for new
values. When a tag value is changed, notification is sent to the alarm server and cor-
responding alarms are added to a queue for later processing. Twice every [Alarm]ScanT-
ime, the alarm server evaluates each alarm in the queue and if it meets the defined
alarm condition, the alarm is triggered. The exception to this sequence of events is
Advanced alarms which are evaluated every [Alarm]ScanTime regardless of IO updates.

Digital, Multi-digital and Time stamped alarm conditions can be configured using var-
iable or multiple variable tags only, while analog, and advanced alarms can be con-
figured using a Cicode expression. This Cicode expression can be a single variable tag or
a complex expression.
For alarms dependent on multiple variable tags for their trigger condition (including
Cicode expressions), conditions may occur that could lead to phantom alarms. For exam-
ple, if the tag values transition within close proximity to one another, there may be an
intermediate state that is not expected.

707
Chapter 23: Using Alarms in SCADA

To counter this from occurring, evaluation of each multi-variable tag alarm is delayed
an extra ½ [Alarm]ScanTime from when the first IO update is received by the alarm
server. This Multivariable delay (MVD) is hard coded into the system, with the intention
to wait until all related IO updates are received before evaluating if the alarm condition
has been met. You can increase [Alarm]ScanTime to minimize the chance of phantom
alarms at the cost of a larger propagation delay.

708
Chapter 23: Using Alarms in SCADA

Refer to the topic 'Using alarm delay' for information regarding the alarm property
option 'alarm delay' and how (if set) it works with Multivariable Delay.
See Also
Using Alarm Delay

Configuring alarms
To configure alarms in your project you need to complete the following:
1. Add Alarms - choose one or all of the seven types of alarms to add.
2. Define categories for your Alarms – though this task is optional, if configured you
can assign each of your alarms to separate categories, where they can be prioritized.
You can then display, acknowledge, reset, and log alarms in a particular category.
3. Assign Alarms to categories
4. Configure the Alarm Runtime Display – using the Alarm Category dialog you can
configure how the alarms will be displayed at runtime on the alarm summary and
sequence of events pages using the SummarySort and SummarySort Mode.
See Also
Adding a new alarm
Alarm Categories

709
Chapter 23: Using Alarms in SCADA

Adding a new Alarm

In CitectSCADA you can configure one or all seven types of alarms. The seven types of
alarms are described briefly in the table below:

Alarm Type Description

Digital Alarms You can configure digital alarms to activate

based on the state of one or two digital var-
iables. The alarm becomes active when the trig-
gering condition spans the duration of a
specified delay period.
The variables configured for a digital alarm are
polled at the rate set by the Citect.ini parameter
[Alarm]ScanTime.

Multi-digital Multi-digital alarms use the output from three

Alarms
digital variables (for example: tags A, B, and C)
to define eight states. The states represent every
possible combination of true/false values the
variables can have.
The tag values in each state are represented in
the order tag C, tag B, tag A. A true value is rep-
resented by the tag letter, and 0 (zero) represents
false.
When configuring the multi-digital alarm prop-
erties, you can set which states will trigger an
alarm, and specify Cicode functions to be called
when alarms become active and inactive.
The variables configured for a multi-digital
alarm are polled at the rate set by the Citect.ini
parameter [Alarm]ScanTime. If an alarm state
changes, notification will occur the next time
the variables are polled. The time associated
with the alarm state will be the timestamp of
when the element was last updated.

Time-stamped Time-stamped alarms are similar to digital

Alarms
alarms, except that a counter is used to provide
an accurate timestamp of when a triggering con-

710
Chapter 23: Using Alarms in SCADA

Alarm Type Description

An alarm's variables are polled at the rate set

by [Alarm]ScanTime, however, the timer value
is used to define the time associated with a
change of state.
You can use one of three types of counter or
timer to record the triggering of time-stamped
alarms:
l Continuous counter. A continuous counter
is read in the unit to determine the sequence
in which the alarms are triggered. The
alarms are sorted based on the value of the
counter when the alarm was triggered (the
exact time is not recorded).
l Millisecond counter. If your unit supports a
millisecond counter, you can program a
counter (in the unit) to count (in mil-
liseconds) for 24 hours, and then reset (at
midnight). The value of this timer variable
(in the unit) is read to determine the exact
time when the alarm was triggered.
l LONGBCD timer. Using a LONGBCD
timer, you can log the exact time when a
time-stamped alarm becomes active. This
variable is read, along with the alarm tag
when the alarm activates.

Analog Alarms Analog alarms are triggered when an analog

variable changes beyond one or more specific
limits. Each alarm can be configured as any
combination of the following types.
l high and high high alarms - where the
value reaches an atypical high
l low and low low alarms - where the value
reaches an atypical low
l deviation alarm - where the values moves
away from a predefined set point
l rate of change alarm - where a dramatic

711
Chapter 23: Using Alarms in SCADA

Alarm Type Description

value change occurs within a specified

period of time
The variables configured for an analog alarm
are polled at the rate set by the Citect.ini param-
eter [Alarm]ScanTime.

Advanced An advanced alarm becomes active when the result of the Cicode expres-
Alarms sion changes. The expression is polled at the rate set by the Citect.ini
parameter [Alarm]ScanTime and tests for a change in outcome. If one
occurs, an alarm state notification will occur.

Time-stamped Time-stamped digital alarms operate via a proc-

Digital Alarms
ess where the Alarm Server is notified of any
value changes to a specified variable using the
AlarmNotifyVarChange Cicode function.
The Alarm Server uses this information to
update alarms that monitor the variable. This
process allows an accurate timestamp to be
associated with an alarm condition.
This process updates the Var Tag A and Var
Tag B properties for time-stamped digital
alarms.
Events trends can be used in conjunction with
time-stamped digital alarms to provide mil-
lisecond accuracy for both trend and alarm
data. See TrnEventSetTable and TrnE-
ventSetTableMSCicode functions.

Time-stamped analog alarms operate via a proc-

ess where the Alarm Server is notified of any
value changes to a specified variable using the
Cicode function AlarmNotifyVarChange.
The Alarm Server will then use this information
Time-stamped
Analog Alarms
to update the alarms that monitor the variable.
This process allows for an accurate timestamp
to be associated with an alarm condition.
This process is used to update the Variable Tag
and Setpoint properties for time-stamped
analog alarms.

712
Chapter 23: Using Alarms in SCADA

Alarm Type Description

Events trends can be used in conjunction with

time-stamped analog alarms to provide mil-
lisecond accuracy for both trend and alarm
data. See TrnEventSetTable and TrnE-
ventSetTableMS.

To add a new alarm:

1. In the Project Editor go to->Alarms

2. Select the Type of Alarm you want to add and in the [Alarm type] Property Dialog
configure according to the required properties.
3. Click Add to append a new record, or Replace to modify an existing record.
See Also

Alarm Delay

Using alarm delay

The Alarm Delay property enables you to configure digital, analog, and advanced
alarms so that they will not activate unless their triggering conditions remain true for a
specified period.
For analog alarms, this means the analog variable needs to fall within a specified range
for the duration of the alarm delay period before an alarm will activate. In the case of
digital and advanced alarms, the triggering condition of the digital variable or Cicode
expression need to remain true for the delay period.
An example of where alarm delay could be useful is in monitoring temperature. By set-
ting a delay period, you can filter out momentary alarms caused by the temperature mov-
ing in and out of different ranges.

713
Chapter 23: Using Alarms in SCADA

For alarms with multiple variables configured, if you use the Alarm delay property the
delay period will start when the most recent IO update has occurred. This delay can run
concurrently with the internal Multivariable delay (MVD) which starts at the first IO
update. The alarm will not be added to the queue until the period of the longest delay set-
ting has elapsed. The alarm will then be triggered at the following 1/2 alarm scan time.

714
Chapter 23: Using Alarms in SCADA

See Also

Understanding how alarm information is retrieved

Using custom alarm filters
Alarm Categories

Digital Alarm Properties

Note: When modifying a Digital Alarm tag, be aware that if the tag was created
using the equipment editor - equipment type workspace, the fields configured will be
grayed out in the tag properties form.

Digital Alarms have the following properties:

Field Description

Equipment Name of the equipment associated with the Digital Alarm. Select or enter a
name of 254 characters or less. You can optionally prefix a cluster name to
the equipment name in order to restrict the reference to a piece of equipment
in only one cluster. The cluster should be configured otherwise the compile
will not be successful. Use this method as an alternative to referencing a
cluster in the equipment properties dialog if the equipment is defined for all
clusters.

Item Name Enter a meaningful name for Tag Item. Used as part of the equipment hier-
archy a meaningful name will help with future migration of your system and
the step towards an object orientated model.
If not configured, the last 63 characters of the “Alarm Tag” field will be used
for the Tag Item name. The Alarm Tag allows 79 characters, while Tag Item
has a maximum of 63 characters. This may result in compiler errors if the
'Equipment.TagItem' name is not unique.
There is a limit of 254 characters on the combination of Equipment and Tag
Items, plus the period '.', for example “Equipment.TagItem” should be 254
characters or less.
See also Scenarios of Tag Item for additional information regarding this field.

Cluster The name of the cluster that runs the alarm. If not set the alarm will run on all
Name clusters. E.g. Cluster1

Comment Any useful comment.

Alarm Tag The name of the alarm. Needs to be unique to the cluster and adhere to the
Tag name syntax.

If the name is not unique or is not syntactically correct it may not be rec-
ognized. If you have lots of tags, use a naming convention to easily find
and debug your tags (see Using structured tag names).

Note:Where Cluster Name is left blank, the name needs to be unique to

715
Chapter 23: Using Alarms in SCADA

Field Description

defined clusters.

Category Alarm category number or label. If not specified defaults to Category 0.

(Optional)

Alarm Name The name of the physical device associated with the alarm. Used when details
(Optional) of the alarm are displayed on the screen or logged to a device.

Alarm Desc Alarm description. May include variable data and used when details of the
(Optional) alarm are displayed on screen or logged to a device.

Variable Tag Configure digital alarms to activate based on the state of single or multiple
A/Variable digital variable tags. For a single variable tag use field Var Tag A. For multiple
Tag B variable tags use fields Var Tag A and Var Tag B.
(See How alarm information is retrieved for more information)
Example 1. State change for single variable tag

where Var Tag A = RFP3_TOL

When the state of the variable RFP3_TOL changes to ON (1), the alarm is
triggered.

Alternatively, you can define the alarm to trigger when the state of the var-
iable changes to OFF (0), by preceding the digital address with the logical
operator NOT, for example:

Where Var Tag A = NOT RFP3_TOL

In this case, the alarm is triggered when the state of the variable MCOL304
changes to OFF (0).

where Var Tag A = NOT MCOL304

Example 2: State change for multiple variable tags

You can also configure digital alarms to activate based on the state of two
digital variables, for example:

where Var Tag A = RFP3_TOL AND Var Tag B = NOT MCOL304

In this scenario, the alarm is triggered when the state of both variables
changes to the active state: when the state of the variable RFP3_TOL
changes to ON (1), and when the state of the variable MCOL304 changes
to OFF (0).

Note: If you leave Var Tag B blank, Var tag A will trigger the alarm

Delay Alarm delay period.

716
Chapter 23: Using Alarms in SCADA

Field Description

The delay period needs to be entered in the format HH:MM:SS (Hours:Mi-

nutes:Seconds). The value needs to be between 0 seconds (00:00:00) and
24 hours (24:00:00).

Help The name of the graphics page that displays when the AlarmHelp() function
(Optional) is called by a user-defined command. If not specified no action occurs when
the AlarmHelp() function is called.

Extended form fields The following fields are implemented with extended forms (press F2).
Note that some of the fields listed below may be displayed in the previous section of the form.

Area Area the alarm belongs to. If an operator does not have access to an area, the
alarm is not visible on the alarm display. For example, if you enter Area 1
here, operator need to have access to Area 1 (plus any necessary privileges)
to acknowledge or disable this alarm.
The area and privilege fields defined here needs to be designed to work in
conjunction. A privilege defined on a button (say) will ignore the alarm
defined area.

Privilege Privilege necessary by an operator to acknowledge or disable the alarm.

If you assign an acknowledgment privilege to an alarm, do not assign a priv-
ilege to the command(s) that acknowledge the alarm. If you assign a different
privilege to the commands, an operator needs to have both privileges to
acknowledge the command. More importantly, the area defined here may be
ignored.

Paging A read/write property that indicates whether the alarm will be paged. When
the value is 1 (TRUE) the alarm will be paged. The default value is 0 (FALSE).
See Alarm Paging Properties. This property can be read using alarm tag
browsing and read or modified when tag properties are enabled using the tag
name "myCluster.myAlarm.paging".

Paging A read only text string that indicates the paging group to which the alarm
Group belongs. Maximum length is 80 characters. See your third-party paging sys-
tem documentation for information on how to use this Paging Group string.
This property can be read using alarm tag browsing or when tag properties
are enabled read using the tagname "myCluster.myAlarm.paginggroup". For
example, assign the value of PagingGroup to a variable:
myString = myCluster.Alarm_1.paginggroup

Historize This field enables you to automatically historize and publish the specified dig-
ital alarm in Schneider Electric's Historian application.
If you set this field to "TRUE", the variable will be included in an automated
configuration process within the Historian environment. If you set the field to
"FALSE" (or leave it blank), the variable will not be included.
See Integration with Historian.

Custom 1 to A user-defined string for filtering active alarms (maximum 64 characters).

Custom 8
Used in a custom Cicode query function as search criteria, the custom
alarm filter enables operators to identify and display a subset of active
alarms.

717
Chapter 23: Using Alarms in SCADA

Field Description

Notes:

l Custom filters are visible only when the Digital Alarms form is open
in Extended mode.
l The fields are not case-sensitive and can contain 'A'..'Z', 'a'..'z',
'0'..'9', and the underscore '_'.
l A custom filter cannot start with a digit.

Note: Configure the [Alarm]UseConfigLimits parameter to force the CitectSCADA

Alarm Server to use digital alarm property values from the RDB, rather than using
the values which may be stored in the database file.

See Also
Using custom alarm filters

Time-stamped Alarm Properties

Note: When modifying a time-stamped alarm tag, be aware that if the tag was
created using the equipment editor - equipment type workspace, the fields configured
will be grayed out in the tag properties form.

Time-stamped Alarms have the following properties:

Field Description

Equipment Name of the equipment associated with the Time-stamped Alarm. Select or
enter a name of 254 characters or less.
You can optionally prefix a cluster name to the equipment name in order to
restrict the reference to a piece of equipment in only one cluster. The cluster
should be configured otherwise the compile will not be successful.
Use this method as an alternative to referencing a cluster in the equipment
properties dialog if the equipment is defined for all clusters.

Item Name Enter a meaningful name for Tag Item. Used as part of the equipment hier-
archy a meaningful name will help with future migration of your system and
the step towards an object oriented model.
If not configured, the last 63 characters of the “Alarm Tag” field will be used
for the Tag Item name. The Alarm Tag allows 79 characters, while Tag Item
has a maximum of 63 characters. This may result in compiler errors if the
'Equipment.TagItem' name is not unique.
There is a limit of 254 characters on the combination of Equipment and Tag
Items, plus the period '.', for example “Equipment.TagItem” should be 254
characters or less.
See also Scenarios of Tag Item for additional information regarding this field.

718
Chapter 23: Using Alarms in SCADA

Field Description

Cluster The name of the cluster that runs the alarm. If not set the alarm will run on all
Name clusters. E.g. Cluster1

Comment Any useful comment.

Alarm Tag The name of the alarm. Needs to be unique to the cluster and adhere to the
Tag name syntax.

Note:Where Cluster Name is left blank, the name needs to be unique to

defined clusters.

Category Alarm category number or label. If not specified defaults to Category 0.

(Optional)

Alarm Name The name of the physical device associated with the alarm. Used when details
(Optional) of the alarm are displayed on the screen or logged to a device.

Alarm Desc Alarm description. May include variable data and used when details of the
(Optional) alarm are displayed on screen or logged to a device.

Variable Tag The variable tag that triggers the alarm.

Timer Expr. The variable tag or Cicode expression that represents the counter (or mil-
lisecond timer) configured in the I/O Device. The counter needs to be con-
figured and maintained by the program in the I/O Device; it is read only when
the alarm is triggered.

You can use one of three types of counter or timer to record the triggering
of time-stamped alarms:

Continuous counter - A continuous counter is read in the unit to deter-

mine the sequence in which the alarms are triggered. The alarms are
sorted based on the value of the counter when the alarm was triggered
(the exact time is not recorded). Program the counter (in the unit) to count
continually to its limit, reset, and again count to its limit.

Millisecond counter - If your unit supports a millisecond counter, pro-

gram a counter (in the unit) to count (in milliseconds) for 24 hours, and
then reset (at midnight). The value of this timer variable (in the unit) is
read to determine the exact time when the alarm was triggered.

LONGBCB timer - Using a LONGBCD timer, you can log the exact time
when a Time-stamped alarm becomes active. This variable is read, along
with the alarm tag when the alarm activates. You need to program the
LONGBCD variable in the following format with the range specified as hex-
adecimal numbers, excluding numbers containing alphabetic characters:

719
Chapter 23: Using Alarms in SCADA

Field Description

BYTE Meaning Range

1st Hours 00-23 (most significant byte)

2nd Minutes 00-59

3rd Seconds 00-59

4th 100th /sec 00-99 (least significant byte)

Use 'Timer' to handshake with the PLC code: The PLC is informed that it
has read the timer register and now the PLC can overwrite the last value.
For example, with the following code saved in a Cicode file:

INT
FUNCTION
AlarmTimerReset(INT iTimer, STRING sTim-
erTrigger)
TagWrite(sTimerTrigger, 0); //Reset the
trigger
RETURN iTimer; //Return the timer value to the
alarm system
END

Example:

where Variable Tag is AlmTrigger1 AND Timer is AlarmTimerReset

(AlmTimer1, "AlmTrigger1")

In this example AlmTimer1 is the PLC register that stores the alarm time,
and AlmTrigger1 is the alarm trigger bit.

When AlmTrigger1 is set to 1, the alarm is triggered, and the Cicode func-
tion is called. On calling the function, the AlmTimer1 register is read. The
function resets the trigger bit (handshaking), and the value of AlmTimer1
is returned.

Note: AlarmTimerReset() is a user function that does not exist in Citect-

SCADA

Extended form fields The following fields are implemented with extended forms (press F2).
Note that some of the fields listed below may be displayed in the previous section of the form.

720
Chapter 23: Using Alarms in SCADA

Field Description

conjunction. A privilege defined on a button (say) will ignore the alarm

defined area.

Privilege Privilege necessary by an operator to acknowledge or disable the alarm.

Custom 1 to A user-defined string for filtering active alarms (maximum 64 characters).

Custom 8
Used in a custom Cicode query function as search criteria, the custom
alarm filter enables operators to identify and display a subset of active
alarms.

Notes:

l Custom filters are visible only when the MultiDigital Alarm form is
open in Extended mode.
l The fields are not case-sensitive and can contain 'A'..'Z', 'a'..'z',
'0'..'9', and the underscore '_'.
l A custom filter cannot start with a digit.

Note: Configure the [Alarm]UseConfigLimits parameter to force the CitectSCADA

Alarm Server to use time-stamped alarm property values from the RDB, rather than
using the values which may be stored in the database file.

See Also
Using custom alarm filters

721
Chapter 23: Using Alarms in SCADA

Multi-digital Alarm Properties

Note: When modifying a Multi- digital alarm tag, be aware that if the tag was
created using the equipment editor - equipment type workspace, the fields configured
will be grayed out in the tag properties form.

Multi-digital Alarms have the following properties.

UNINTENDED EQUIPMENT OPERATION

Do not put a blocking Cicode function in the ON Function field. A blocking function will
affect the polling of alarms, and may result in slow or delayed alarm processing.

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

Field Description

Equipment Name of the equipment associated with the Multi-digital Alarm. Select or
enter a name of 254 characters or less. You can optionally prefix a cluster
name to the equipment name in order to restrict the reference to a piece of
equipment in only one cluster. The cluster should be configured otherwise
the compile will not be successful. Use this method as an alternative to ref-
erencing a cluster in the equipment properties dialog if the equipment is
defined for all clusters.

Item Name Enter a meaningful name for Tag Item. Used as part of the equipment hier-
archy a meaningful name will help with future migration of your system and
the step towards an object oriented model.
If not configured, the last 63 characters of the “Alarm Tag” field will be used
for the Tag Item name. The Alarm Tag allows 79 characters, while Tag Item
has a maximum of 63 characters. This may result in compiler errors if the
'Equipment.TagItem' name is not unique.
There is a limit of 254 characters on the combination of Equipment and Tag
Items, plus the period '.', for example “Equipment.TagItem” should be 254
characters or less.
See also Scenarios of Tag Item for additional information regarding this field.

Cluster The name of the cluster that runs the alarm. If not set the alarm will run on all
Name clusters. E.g. Cluster1

Comment Any useful comment.

Alarm Tag The name of the alarm. Needs to be unique to the cluster and adhere to the
Tag name syntax.

722
Chapter 23: Using Alarms in SCADA

Field Description

Note:Where Cluster Name is left blank, the name needs to be unique to

defined clusters.

Category Alarm category number or label. If not specified defaults to Category 0.

(Optional)

Alarm Name The name of the physical device associated with the alarm. Used when details
(Optional) of the alarm are displayed on the screen or logged to a device.

Alarm Desc Alarm description. May include variable data and used when details of the
(Optional) alarm are displayed on screen or logged to a device.

Variable Tag The digital variables used to define eight states. Each state represents a dif-
A/Variable ferent combination of tag values. For example,
Tag B/Va-
the digital variables RFP3_TOL, BIT_1, and MCOL304 could be specified for
riable Tag C
Tags A, B, and C respectively

States and The following eight states represent any possible tag value combinations (8
Descriptions characters maximum for description and 1 character for state). The tags are
represented in the order Tag C, Tag B, Tag A.
l State 000 - All 3 tags are false.
l State 00A - Tags C and B are false and Tag A is true.
l State 0B0 - Tags C and A are false and Tag B is true.
l State 0BA - Tag C is false and Tags B and A are true.
l State C00 - Tag C is true and Tags B and A are false.
l State C0A - Tags C and A are true and Tag B is false.
l State CB0 - Tags C and B are true and Tag A is false.
l State CBA - All 3 tags are true.
For each state, there are two fields on the Multi-Digital Alarms dialog. In
the first field enter a description (for example Healthy or Stopped), with a
maximum of eight characters. In the second field, indicate whether the
state will trigger an alarm. A value of 1 indicates an alarm state, and a 0
indicates no alarm will be triggered.

Realarm(1 Indicates what happens when there is a transition from one alarm state to
char) another. A value of 1 in this field causes a new time and State Description
{State_Desc,n} to be recorded when the states change. With a value of 0,
only the time and State Description of the first alarm state is recorded in the
Alarm Summary.

Extended form fields The following fields are implemented with extended forms (press F2).
Note that some of the fields listed below may be displayed in the previous section of the form.

On function A Cicode function that is executed when the Multi-Digital Alarm becomes
(254 chars) active, for example

723
Chapter 23: Using Alarms in SCADA

Field Description

where ON Function is STOP_PROCESS = 1;

In this example the digital variable STOP_PROCESS is set to ON when the
alarm is triggered.
Note: Do not put a blocking Cicode function in this field. The alarm system
executes ON or OFF actions within the polling loop. A blocking function will
affect the polling of alarms, and may result in slow or delayed alarm proc-
essing.
A special case of this command occurs when the Alarm ON Function is self-
referring e.g.TAG1 = TAG1 + 1. This command will not work properly since
tags are not read again before processing the Alarm On function (for per-
formance reasons). Therefore this particular command will initially set the
value of TAG1 to 1 rather than incrementing it.
To correctly run a command of this type in the Alarm ON Function, use Task-
New() to run your own Cicode function to perform the tag command:
Where ON function is TaskNew("MyFunc","Data",5);

OFF func- A Cicode function that is executed when a Multi-Digital Alarm becomes inac-
tion (254 tive. For example,
chars)
where OFF Function is ENABLE_PROCESS = 1;
In this example the digital variable ENABLE_PROCESS is set to ON when an
alarm in this category is reset.
Note: Do not put a blocking Cicode function in this field. The alarm system
executes ON or OFF actions within the polling loop. A blocking function will
affect the polling of alarms, and may result in slow or delayed alarm proc-
essing.

Privilege Privilege necessary by an operator to acknowledge or disable the alarm.

Suppression The number of the Suppression Group to which the alarm belongs.
Integer value between 0–32767.
Alarms in the same group display the same value in this field. Use in con-
junction with Suppression Level.
Note: To assign a name to a Suppression Group, define the name as a label
with an integer value.

724
Chapter 23: Using Alarms in SCADA

Field Description

Level The level of an alarm within its Suppression Group (integer value). This is a
value between 0 and 255, where a lower level represents a higher priority.
This property enables an active alarm which is in an ON state (irrespective
of whether it is acknowledged or not) to suppress lower priority alarms
within the same Suppression Group. When this occurs, only the higher prior-
ity (lower level) alarms are displayed. Alarms with lower priorities (higher lev-
els) will only activate and display when the higher priority (lower level)
alarms become inactive.

A user-defined string for filtering active alarms (maximum 64 characters).

Used in a custom Cicode query function as search criteria, the custom

alarm filter enables operators to identify and display a subset of active
alarms.
Custom 1 to
Custom 8 Notes:

725
Chapter 23: Using Alarms in SCADA

UNINTENDED EQUIPMENT OPERATION

Do not put a blocking Cicode function in the OFF Function field. A blocking function will
affect the polling of alarms, and may result in slow or delayed alarm processing.

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

Note: Configure the [Alarm]UseConfigLimits parameter to force the CitectSCADA

Alarm Server to use multi-digital alarm property values from the RDB, rather than
using the values which may be stored in the database file.

See Also
Using custom alarm filters

Analog Alarm Properties

Note: When modifying an analog alarm tag, be aware that if the tag was created
using the equipment editor - equipment type workspace, the fields configured will be
grayed out in the tag properties form.

Analog Alarms have the following properties:

Field Description

Equipment Name of the equipment associated with the Analog Alarm. Select or enter a
name of 254 characters or less. You can optionally prefix a cluster name to the
equipment name in order to restrict the reference to a piece of equipment in
only one cluster. The cluster should be configured otherwise the compile will
not be successful. Use this method as an alternative to referencing a cluster in
the equipment properties dialog if the equipment is defined for all clusters.

Item Enter a meaningful name for Tag Item. Used as part of the equipment hier-
Name archy a meaningful name will help with future migration of your system and the
step towards an object oriented model.
If not configured, the last 63 characters of the “Alarm Tag” field will be used
for the Tag Item name. The Alarm Tag allows 79 characters, while Tag Item has
a maximum of 63 characters. This may result in compiler errors if the 'Equip-
ment.TagItem' name is not unique.
There is a limit of 254 characters on the combination of Equipment and Tag
Items, plus the period '.', for example “Equipment.TagItem” should be 254
characters or less.
See also Scenarios of Tag Item for additional information regarding this field.

726
Chapter 23: Using Alarms in SCADA

Field Description

Cluster The name of the cluster that runs the alarm. If not set the alarm will run on all
Name clusters. E.g. Cluster1

Comment Any useful comment.

Alarm Tag The name of the alarm. Needs to be unique to the cluster and adhere to the
Tag name syntax.

If the name is not unique or is not syntactically correct it may not be rec-
ognized. If you have lots of tags, use a naming convention to easily find and
debug your tags (see Using structured tag names).

Note:Where Cluster Name is left blank, the name needs to be unique to

defined clusters.

Category Alarm category number or label. If not specified defaults to Category 0.

(Optional)

Alarm The name of the physical device associated with the alarm. Used when details
Name of the alarm are displayed on the screen or logged to a device.
(Optional)

Variable The analog variable (tag) that triggers the alarm.

Tag

Setpoint An analog variable tag or base value that determines if a deviation alarm is to be
triggered. This property is optional. If you do not specify a setpoint, it will
default to 0 (zero).

High High Value used as the triggering condition for a high high alarm. If the value of the
variable tag exceeds this value for the duration of the high high delay period
the alarm will be triggered. The active alarm will have an ON time of when the
tag exceeded the high high value. Because a high alarm needs to precede a
high high alarm, when the high high alarm is triggered it replaces the high
alarm.
To display more than one state on the alarm page at the same time, configure a
separate alarm for each state. (Each alarm would monitor the same tag.)

High High Delay period for High High Alarms. Alarm will activate if its triggering condition
Delay is met for the duration of the delay period.
(Optional)
If you do not set a value, the high high alarm will be activated as soon as the
tag exceeds the high high value.
Note: The delay period needs to be entered in the format HH:MM:SS
(hours:minutes:seconds). The value needs to be between 0 seconds
(00:00:00) and 24 hours (24:00:00).

High The value used as the triggering condition for a high alarm. The high alarm
becomes active when the value of the variable tag exceeds this value for the
duration of the high delay period. The active alarm has an ON time of when the
tag exceeded the high value.

727
Chapter 23: Using Alarms in SCADA

Field Description

Note: The delay period needs to be entered in the format HH:MM:SS

(hours:minutes:seconds). The value needs to be between 0 seconds
(00:00:00) and 24 hours (24:00:00).
When a tag value increases from high to high high within the high delay
period, the delay timer is reset. The high high alarm is only activated if the
value remains in the high high range for the delay period.
When the value increases from high to high high after the high delay period
has expired, a high alarm is activated and then the delay period for the high
high alarm begins.
If the tag value exceeds the high high value and then falls below it before the
high high delay period expires, at the time it falls, the high alarm is triggered
immediately.
It has an ON time of when the tag value exceeded the high high value. These
points also apply to tag values traveling between Low and Low Low ranges.

Low The value used as the triggering condition for a Low Alarm. Alarm becomes
active when the value of the Variable Tag drops below this value and remains
there for the duration of the Low Delay period. The active alarm has an ON time
of when the tag fell below the Low value.

Low Delay The delay period for Low Alarms. The alarm will only activate if its triggering
(Optional) condition is met for the duration of this period. This property is optional. If you
do not set a value, the Low Alarm is activated as soon as the tag drops below
the Low value.
Note: The delay period needs to be entered in the format HH:MM:SS
(Hours:Minutes:Seconds). The value needs to be between 0 seconds
(00:00:00) and 24 hours (24:00:00).

Low Low The value used as the triggering condition for a Low Low Alarm. A Low Low
Alarm becomes active when the value of the Variable Tag drops below this
value and remains there for the duration of the Low Low Delay period. The
active alarm has an ON time of when the tag fell below the Low Low value.
Because a Low Alarm needs to precede a Low Low Alarm, when the Low Low
Alarm is triggered it replaces the Low Alarm. If you want an analog alarm to dis-
play more than one state on the alarm page at the same time, configure a sep-
arate alarm for each state. (Each alarm would monitor the same tag.)

Low Low The delay period for Low Low Alarms. The alarm will only activate if its trig-
Delay gering condition is met for the duration of this period. If you do not set a value,
(Optional) the Low Low Alarm is activated as soon as the tag drops below the Low Low
value.
Note: The delay period needs to be entered in the format HH:MM:SS
(Hours:Minutes:Seconds). The value needs to be between 0 seconds
(00:00:00) and 24 hours (24:00:00).

Deviation The value used as the triggering condition for a Deviation Alarm. A Deviation
(Optional) Alarm is activated when the value of the Variable Tag remains outside the devi-
ation range (determined by the Setpoint) for the duration of the Deviation Delay
period. This property is optional. If you do not specify a deviation, no Deviation
Alarm is activated.

728
Chapter 23: Using Alarms in SCADA

Field Description

Deviation The delay period for Deviation Alarms. The alarm will only activate if its trig-
Delay gering condition is met for the duration of this period. If you do not set a value,
(Optional) the Deviation Alarm is activated as soon as the Variable Tag falls outside the
deviation range.
Note: The delay period needs to be entered in the format HH:MM:SS
(Hours:Minutes:Seconds). The value needs to be between 0 seconds
(00:00:00) and 24 hours (24:00:00).

Rate By dividing this value by the alarm period, the "maximum rate" at which the
(Optional) value of the variable tag can change is determined. At each Scan Time, the
value of the tag is checked. If its rate of change is greater than the maximum
rate, a Rate of Change Alarm is triggered.
For example, to verify that a tank does not fill too quickly, you might configure a
rate of change alarm, using a Rate of 300 liters, an [Alarm]Period of 60 sec-
onds, and an [Alarm]ScanTime of 1 second. This means that the maximum
allowable rate of change for the tank level is 5 l/sec (300 liters / 60 seconds).
The actual rate of change at each ScanTime is calculated. That is, every sec-
ond, it checks the current level of the tank and compares it to the level
recorded a second earlier. If the actual rate of change is, say, 8 l/sec, a Rate of
Change Alarm is triggered immediately.
The variable tags deadband % needs to be less than the alarms rate divided by
the engineering scale of the variable tag. Otherwise, the rate of change alarm
will only go off when the change in the variable tag exceeds the deadband
value. If you do not specify a value, no Rate of Change Alarm is activated.

Deadband Value the Variable Tag needs to return to before the Alarm becomes inactive.

Format The display format of the value (of the variable) when it is displayed on a graph-
(Optional) ics page, written to a file or passed to a function (that expects a string). If you
do not specify a format, the format defaults to the format specified for Variable
tag.

Help The name of the graphics page that displays when the AlarmHelp() function is
(Optional) called by a user-defined command. If not specified no action occurs when the
AlarmHelp() function is called.

Extended form fields The following fields are implemented with extended forms (press
F2). Note that some of the fields listed below may be displayed in the previous section of the
form.

Area Area the alarm belongs to. If an operator does not have access to an area, the
alarm is not visible on the alarm display. For example, if you enter Area 1 here,
operator need to have access to Area 1 (plus any necessary privileges) to
acknowledge or disable this alarm.
The area and privilege fields defined here needs to be designed to work in con-
junction. A privilege defined on a button (say) will ignore the alarm defined
area.

Privilege Privilege necessary by an operator to acknowledge or disable the alarm.

729
Chapter 23: Using Alarms in SCADA

Field Description

ignored.

Paging A read/write property that indicates whether the alarm will be paged. When the
value is 1 (TRUE) the alarm will be paged. The default value is 0 (FALSE). See
Alarm Paging Properties. This property can be read using alarm tag browsing
and read or modified when tag properties are enabled using the tag name
"myCluster.myAlarm.paging".

Paging A read only text string that indicates the paging group to which the alarm
Group belongs. Maximum length is 80 characters. See your third-party paging sys-
tem documentation for information on how to use this Paging Group string.
This property can be read using alarm tag browsing or when tag properties are
enabled read using the tagname "myCluster.myAlarm.paginggroup". For exam-
ple, assign the value of PagingGroup to a variable:
myString = myCluster.Alarm_1.paginggroup

Historize This field enables you to automatically historize and publish the specified dig-
ital alarm in Schneider Electric's Historian application.
If you set this field to "TRUE", the variable will be included in an automated con-
figuration process within the Historian environment. If you set the field to
"FALSE" (or leave it blank), the variable will not be included.
See Integration with Historian.

Custom 1 A user-defined string for filtering active alarms (maximum 64 characters).

to Custom
8 Used in a custom Cicode query function as search criteria, the custom alarm
filter enables operators to identify and display a subset of active alarms.

Notes:

l Custom filters are visible only when the Digital Alarms form is open in
Extended mode.
l The fields are not case-sensitive and can contain 'A'..'Z', 'a'..'z',
'0'..'9', and the underscore '_'.
l A custom filter cannot start with a digit.

Note: Configure the [Alarm]UseConfigLimits parameter to force the CitectSCADA

Alarm Server to use analog alarm property values from the RDB, rather than using
the values which may be stored in the database file.

See Also
Using custom alarm filters

730
Chapter 23: Using Alarms in SCADA

Time-stamped Digital Alarm Properties

Note: For time-stamped digital alarms to function correctly, you need to configure the
Cicode function AlarmNotifyVarChange, as it notifies the alarm server of any value
changes for the associated variable. It also passes the timestamp with the notification
message. The AlarmServer maintains a queue for notification messages and runs a
separate task to check this queue.

Note: When modifying a time-stamped digital alarm tag, be aware that if the tag was
created using the equipment editor - equipment type workspace, the fields configured
will be grayed out in the tag properties form.

Time-stamped Digital Alarms have the following properties:

Field Description

Equipment Name of the equipment associated with the Time-stamped Digital Alarm.
Select or enter a name of 254 characters or less. You can optionally prefix a
cluster name to the equipment name in order to restrict the reference to a
piece of equipment in only one cluster. The cluster should be configured
otherwise the compile will not be successful. Use this method as an alter-
native to referencing a cluster in the equipment properties dialog if the equip-
ment is defined for all clusters.

Item Name Enter a meaningful name for Tag Item. Used as part of the equipment hier-
archy a meaningful name will help with future migration of your system and
the step towards an object oriented model.
If not configured, the last 63 characters of the “Alarm Tag” field will be used
for the Tag Item name. The Alarm Tag allows 79 characters, while Tag Item
has a maximum of 63 characters. This may result in compiler errors if the
'Equipment.TagItem' name is not unique.
There is a limit of 254 characters on the combination of Equipment and Tag
Items, plus the period '.', for example “Equipment.TagItem” should be 254
characters or less.
See also Scenarios of Tag Item for additional information regarding this field.

Cluster The name of the cluster that runs the alarm. If not set the alarm will run on all
Name clusters. E.g. Cluster1

Comment Any useful comment.

Alarm Tag The name of the alarm. Needs to be unique to the cluster and adhere to the
Tag name syntax.

731
Chapter 23: Using Alarms in SCADA

Field Description

Note:Where Cluster Name is left blank, the name needs to be unique to

defined clusters.

Category Alarm category number or label. If not specified defaults to Category 0.

(Optional)

Alarm Name The name of the physical device associated with the alarm. Used when details
(Optional) of the alarm are displayed on the screen or logged to a device.

Alarm Desc Alarm description. May include variable data and used when details of the
(Optional) alarm are displayed on screen or logged to a device.

where Var Tag A = RFP3_TOL

When the state of the variable RFP3_TOL changes to ON (1), the alarm is
triggered.

Alternatively, you can define the alarm to trigger when the state of the var-
iable changes to OFF (0), by preceding the digital address with the logical
operator NOT, for example:

Where Var Tag A = NOT RFP3_TOL

In this case, the alarm is triggered when the state of the variable MCOL304
changes to OFF (0).

where Var Tag A = NOT MCOL304

Example 2: State change for multiple variable tags

You can also configure digital alarms to activate based on the state of two
digital variables, for example:

where Var Tag A = RFP3_TOL AND Var Tag B = NOT MCOL304

Note: If you leave Var Tag B blank, Var tag A will trigger the alarm

Delay Alarm delay period.

732
Chapter 23: Using Alarms in SCADA

Field Description

soon as it is triggered by the digital tag(s).

The delay period needs to be entered in the format HH:MM:SS (Hours:Mi-
nutes:Seconds). The value needs to be between 0 seconds (00:00:00) and
24 hours (24:00:00).

Extended form fields The following fields are implemented with extended forms (press F2).
Note that some of the fields listed below may be displayed in the previous section of the form.

Privilege Privilege necessary by an operator to acknowledge or disable the alarm.

If you assign an acknowledgment privilege to an alarm, there is no need to
assign a privilege to the command(s) that acknowledge the alarm. If you
assign a different privilege to the commands, an operator needs to have both
privileges to acknowledge the command. More importantly, the area defined
here may be ignored.

Custom 1 to A user-defined string for filtering active alarms (maximum 64 characters).

Custom 8
Used in a custom Cicode query function as search criteria, the custom
alarm filter enables operators to identify and display a subset of active

733
Chapter 23: Using Alarms in SCADA

Field Description

alarms.

Notes:

l Custom filters are visible only when the Time-stamped Digital

Alarms form is open in Extended mode.
l The fields are not case-sensitive and can contain 'A'..'Z', 'a'..'z',
'0'..'9', and the underscore '_'.
l A custom filter cannot start with a digit.

Note: Configure the [Alarm]UseConfigLimits parameter to force the CitectSCADA

Alarm Server to use time-stamped digital alarm property values from the RDB,
rather than using the values which may be stored in the database file.

See Also
Using custom alarm filters

Advanced Alarm Properties

Note: When modifying an advanced alarm tag, be aware that if the tag was created
using the equipment editor - equipment type workspace, the fields configured will be
grayed out in the tag properties form.

Advanced Alarms have the following properties.

Field Description

Equipment Name of the equipment associated with the Advanced Alarm. Select or enter a
name of 254 characters or less. You can optionally prefix a cluster name to
the equipment name in order to restrict the reference to a piece of equipment
in only one cluster. The cluster should be configured otherwise the compile
will not be successful. Use this method as an alternative to referencing a
cluster in the equipment properties dialog if the equipment is defined for all
clusters.

Tag Item Enter a meaningful name for Tag Item. Used as part of the equipment hier-
archy a meaningful name will help with future migration of your system and
the step towards an object oriented Cicode blocking model.
If not configured, the last 63 characters of the “Alarm Tag” field will be used
for the Tag Item name. The Alarm Tag allows 79 characters, while Tag Item
has a maximum of 63 characters. This may result in compiler errors if the
'Equipment.TagItem' name is not unique.
There is a limit of 254 characters on the combination of Equipment and Tag
Items, plus the period '.', for example “Equipment.TagItem” should be 254
characters or less.
See also Scenarios of Tag Item for additional information regarding this field.

734
Chapter 23: Using Alarms in SCADA

Field Description

Cluster The name of the cluster that runs the alarm.E.g. Cluster1. If not set the alarm
Name will run on all clusters.

Comment Any useful comment.

Alarm Tag The name of the alarm. Needs to be unique to the cluster and adhere to the
Tag name syntax.

Note:Where Cluster Name is left blank, the name needs to be unique to

defined clusters.

Category Alarm category number or label. If not specified defaults to Category 0.

(Optional)

Alarm Name The name of the physical device associated with the alarm. Used when details
(Optional) of the alarm are displayed on the screen or logged to a device.

Alarm Desc Alarm description. May include variable data and used when details of the
(Optional) alarm are displayed on screen or logged to a device.

Expression The Cicode expression that triggers the alarm. Whenever the result of the
expression changes to TRUE, the alarm is triggered.

Delay Alarm delay period.

(Optional)
A digital alarm becomes active when the state of the triggering condition
remains true for the duration of the delay period. The active alarm has an ON
time of when the state became true. If not specified the alarm is active as
soon as it is triggered by the digital tag(s).
The delay period needs to be entered in the format HH:MM:SS (Hours:Mi-
nutes:Seconds). The value needs to be between 0 seconds (00:00:00) and
24 hours (24:00:00).

Extended form fields The following fields are implemented with extended forms (press F2).
Note that some of the fields listed below may be displayed in the previous section of the form.

Privilege Privilege necessary by an operator to acknowledge or disable the alarm.

If you assign an acknowledgment privilege to an alarm, do not assign a priv-

735
Chapter 23: Using Alarms in SCADA

Field Description

ilege to the command(s) that acknowledge the alarm. If you assign a different
privilege to the commands, an operator needs to have both privileges to
acknowledge the command. More importantly, the area defined here may be
ignored.

Custom 1 to A user-defined string for filtering active alarms (maximum 64 characters).

Custom 8
Used in a custom Cicode query function as search criteria, the custom
alarm filter enables operators to identify and display a subset of active
alarms.

Notes:

l Custom filters are visible only when the Advanced Alarms form is
open in Extended mode.
l The fields are not case-sensitive and can contain 'A'..'Z', 'a'..'z',
'0'..'9', and the underscore '_'.
l A custom filter cannot start with a digit.

Note: Configure the [Alarm]UseConfigLimits parameter to force the CitectSCADA

Alarm Server to use advanced alarm property values from the RDB, rather than
using the values which may be stored in the database file.

See Also
Using custom alarm filters

736
Chapter 23: Using Alarms in SCADA

Time-stamped Analog Alarm Properties

Note: For time-stamped analog alarms to function correctly, you need to configure
the Cicode function AlarmNotifyVarChange, as it notifies the alarm server of any
value changes for the associated variable. It also passes the timestamp with the noti-
fication message. The AlarmServer maintains a queue for notification messages and
runs a separate task to check this queue.

Note: When modifying a time-stamped analog alarm tag, be aware that if the tag
was created using the equipment editor - equipment type workspace, the fields con-
figured will be grayed out in the tag properties form.

Time-stamped Analog Alarms have the following properties:

Field Description

Equipment Name of the equipment associated with the Time-stamped Analog Alarm. Select
or enter a name of 254 characters or less. You can optionally prefix a cluster
name to the equipment name in order to restrict the reference to a piece of
equipment in only one cluster. The cluster should be configured otherwise the
compile will not be successful. Use this method as an alternative to referencing
a cluster in the equipment properties dialog if the equipment is defined for all
clusters.

Cluster The name of the cluster that runs the alarm. If not set the alarm will run on all
Name clusters. E.g. Cluster1

Comment Any useful comment.

Alarm Tag The name of the alarm. Needs to be unique to the cluster and adhere to the
Tag name syntax.

If the name is not unique or is not syntactically correct it may not be rec-
ognized. If you have lots of tags, use a naming convention to easily find and
debug your tags (see Using structured tag names).

737
Chapter 23: Using Alarms in SCADA

Field Description

Note:Where Cluster Name is left blank, the name needs to be unique to

defined clusters.

Category Alarm category number or label. If not specified defaults to Category 0.

(Optional)

Alarm The name of the physical device associated with the alarm. Used when details
Name of the alarm are displayed on the screen or logged to a device.
(Optional)

Variable The analog variable (tag) that triggers the alarm.

Tag

Setpoint An analog variable tag or base value that determines if a deviation alarm is to be
triggered. This property is optional. If you do not specify a setpoint, it will
default to 0 (zero).

High High The value used as the triggering condition for a high high alarm. The high
high alarm becomes active when the value of the variable tag exceeds this
value for the duration of the high high delay period. The active alarm has an
ON time of when the tag exceeded the high high value.

Because a high alarm needs to precede a high high alarm, when the high
high alarm is triggered it replaces the high alarm. If you want an analog
alarm to display more than one state on the alarm page at the same time,
configure a separate alarm for each state. (Each alarm would monitor the
same tag.)

High The delay period for high alarms. Alarm will activate if its triggering condition
Delay is met for the duration of this period. If you do not set a value, the high alarm
(Optional) will be activated as soon as the tag exceeds the high value.
Note: The delay period needs to be entered in the format HH:MM:SS
(hours:minutes:seconds). The value needs to be between 0 seconds
(00:00:00) and 24 hours (24:00:00).
When a tag value increases from high to high high within the high delay
period, the delay timer is reset. The high high alarm is only activated if the
value remains in the high high range for the delay period.
When the value increases from high to high high after the high delay period

738
Chapter 23: Using Alarms in SCADA

Field Description

has expired, a high alarm is activated and then the delay period for the high
high alarm begins.
If the tag value exceeds the high high value and then falls below it before the
high high delay period expires, at the time it falls, the high alarm is triggered
immediately.
It has an ON time of when the tag value exceeded the high high value. These
points also apply to tag values traveling between Low and Low Low ranges.

739
Chapter 23: Using Alarms in SCADA

Field Description

Deadband Value the Variable Tag needs to return to before the Alarm becomes inactive.

Extended form fields The following fields are implemented with extended forms (press F2).
Note that some of the fields listed below may be displayed in the previous section of the form.

Area Area the alarm belongs to. If an operator does not have access to an area, the
alarm is not visible on the alarm display. For example, if you enter Area 1 here,
operator need to have access to Area 1 (plus any necessary privileges) to
acknowledge or disable this alarm.
The area and privilege fields defined here needs to be designed to work in con-
junction. A privilege defined on a button (say) will ignore the alarm defined
area.

Privilege Privilege necessary by an operator to acknowledge or disable the alarm.

If you assign an acknowledgment privilege to an alarm, there is no need to
assign a privilege to the command(s) that acknowledge the alarm. If you assign
a different privilege to the commands, an operator needs to have both priv-
ileges to acknowledge the command. More importantly, the area defined here
may be ignored.

Paging A read/write property that indicates whether the alarm will be paged. When the
value is 1 (TRUE) the alarm will be paged. The default value is 0 (FALSE). See
Alarm Paging Properties. This property can be read using alarm tag browsing
and read or modified when tag properties are enabled using the tag name
"myCluster.myAlarm.paging".

Paging A read only text string that indicates the paging group to which the alarm

740
Chapter 23: Using Alarms in SCADA

Field Description

Group belongs. Maximum length is 80 characters. See your third-party paging sys-
tem documentation for information on how to use this Paging Group string.
This property can be read using alarm tag browsing or when tag properties are
enabled read using the tagname "myCluster.myAlarm.paginggroup". For exam-
ple, assign the value of PagingGroup to a variable:
myString = myCluster.Alarm_1.paginggroup

Historize This field enables you to automatically historize and publish the specified dig-
ital alarm in Schneider Electric's Historian application.
If you set this field to "TRUE", the variable will be included in an automated con-
figuration process within the Historian environment. If you set the field to
"FALSE" (or leave it blank), the variable will not be included.
See Integration with Historian.

Custom 1 A user-defined string for filtering active alarms (maximum 64 characters).

to Custom
8 Used in a custom Cicode query function as search criteria, the custom alarm
filter enables operators to identify and display a subset of active alarms.

Notes:

l Custom filters are visible only when the Digital Alarms form is open in
Extended mode.
l The fields are not case-sensitive and can contain 'A'..'Z', 'a'..'z',
'0'..'9', and the underscore '_'.
l A custom filter cannot start with a digit.

Note: Configure the [Alarm]UseConfigLimits parameter to force the CitectSCADA

Alarm Server to use time-stamped analog alarm property values from the RDB,
rather than using the values which may be stored in the database file.

See Also
Using custom alarm filters

Scenarios for the Item Name Field

Item name is an optional field on the Alarm, Tag, Trend, and SPC Properties form, and
is used as part of the equipment hierarchy.The following table outlines compiler sce-
narios if you have various combinations of Tag name, Equipment name, and Item Name
fields configured.

Sce-
Scenario
nario Scenario 3 Scenario 4 Scenario 5
2
1

Tag Tag1 Tag1 .../Area1/Pumps1- .../Area1/Pumps1- .../Area1/Pumps1-

(e.g. (String (String /Pump1/Alarm1/ /Pump1/Alarm1/ /Pump1/Alarm1/

741
Chapter 23: Using Alarms in SCADA

Sce-
Scenario
nario Scenario 3 Scenario 4 Scenario 5
2
1

Alarm less less than (String more than (String more than (String more than
Tag,) than 63 char- 63 characters) 63 characters) 63 characters)
63 acters)
Max
char-
lengt-
acters)
h-
79
char-
acter-
s

Equi- <blan- Equip- <blank> Equipment1 <blank>

pme- k> ment1
nt

Item <blan- <blank> <blank> Mytagitem

Nam- k>
e
Max
lengt-
h 63
char-
acter-
s

When When com- When compiling as When compiling as Compiler error -

compiling, no the tag name is the tag name is "Equipment not
piling, error is greater than 63 greater than 63 specified for tag
no generated. characters, the characters, the item". Please spec-
error is Configured name will be trun- name will be trun- ify equipment or
gen- Project cated from the cated from the remove tag item".
erated. directory right. For exam- right. For exam-
Con- would be ple: Item becomes ple: Item Name
figured as follows: 'Pumps1/Pump1/A- becomes
Project larm1'. If the 'Pumps1/Pump1/A-
direc- 'Equip.Item' name larm1'. If however
tory is not unique in the 'Equip.Item'
would the system then a name is not unique
be as compiler error will in the system then
fol- be generated. Con- a compiler error
lows: figured Project will be gen-
directory would be erated.Configured
as follows: Project directory
would be as fol-
lows:

742
Chapter 23: Using Alarms in SCADA

See Also
Configuring Equipment
Defining an Equipment Hierarchy
Equipment Properties
Associating Equipment

Using custom alarm filters

You can define keywords for your alarm tags that you can then use to perform cus-
tomized queries on your alarm data.
The Alarm Properties dialog allows you to define up to eight custom filters for each of
the alarms in your system, allowing you to generate queries that filter your alarm data
for specific information.
For example, you will want to prioritize any alarms that monitor equipment and con-
ditions with the potential to cause a fire. You could set Custom Filter 1 for each relevant
tag to "fire hazard". You could then call a Cicode function that requests alarms with a
"custom filter 1" field equal to "fire hazard". The end result would be a list of alarms noti-
fying an operator of any potentially flammable circumstances.
You could also set aside Custom Filter 2 to define the type of equipment the alarm is
associated with, and label each alarm accordingly (for example "pump", "conveyor",
etc.). Queries could then be created to list the alarms related to a particular type of
machinery; for example, alarms associated with pumps.

Converting AlarmSetQuery() functions to the Alarm filter functions

As part of v7.40the AlarmSetQuery() and Query() functions were replaced with a series
of alarm filter edit functions. Below are examples of v7.20 Cicode and what the v7.30
Cicode may look like with the new alarm filter edit functions.
Conversion examples from v7.20 to v7.30:
v7.20 code:

….
INT resultAlarmSetQuery=0;
// e.g. fieldName = Category, fieldValue = 10
// or fieldName = Tag, fieldValue = DigitalAlarm1
resultAlarmSetQuery =
AlarmSetQuery(21,"AlarmFilter","^""+fieldName+"^",^""+filterValue+"^"");//Obsolete
in v7.30
…….
PUBLIC

743
Chapter 23: Using Alarms in SCADA

INT
FUNCTION AlarmFilter
(INT iRecId,
INT iInst,
STRING fieldName,
STRING filterValue)

INT resultFilter=0;
STRING getValue="";

getValue = AlarmGetFieldRec(iRecId, fieldName, iInst);

IF filterValue = getValue THEN

resultFilter = TRUE;
ELSE
// when "*" entered -> all values are accepted
IF filterValue = "*" THEN
resultFilter = TRUE;
ELSE
resultFilter = FALSE;
END
END;

RETURN resultFilter;

END

v7.30 code:

….
INT resultAlarmSetQuery=0;

//AlarmSetQuery(21,"AlarmFilter30","^""+fieldName+"^",^""-
+filterValue+"^"");Obsolete in 7.30

//replace the above by direct call

resultAlarmSetQuery = AlarmFilter730(fieldName,filterValue);

....

PUBLIC
INT
FUNCTION AlarmFilter730

(STRING fieldName,
STRING filterValue)

744
Chapter 23: Using Alarms in SCADA

INT hndl=-1, resultFilter=-1;

TRING sFilter="";

sFilter = fieldName + "=" + filterValue;

hndl= AlarmFilterEditOpen(21);
IF hndl <> -1 THEN
resultFilter = AlarmFilterEditSet(hndl,sFilter)
IF resultFilter = 0 THEN
resultFilter = AlarmFilterEditCommit(hndl)
END
AlarmFilterEditClose(hndl)
END

RETURN resultFilter;

END

Another example of how this function could be returned:

PUBLIC
INT
FUNCTION AlarmFilter730
(STRING fieldName,
STRING filterValue)

INT hndl;
INT resultFilter=-1;

hndl = AlarmFilterEditOpen(21);
IF hndl <> -1 THEN
resultFilter = AlarmFilterEditSet(hndl, fieldName)
IF resultFilter = 0 THEN
resultFilter = AlarmFilterEditAppend(hndl, "=^"")
END
IF resultFilter = 0 THEN
resultFilter = AlarmFilterEditAppend(hndl, filterValue)
END
IF resultFilter = 0 THEN
resultFilter = AlarmFilterEditAppend(hndl, "^"")
END
IF resultFilter = 0 THEN
resultFilter = AlarmFilterEditCommit(hndl)
END
AlarmFilterEditClose(hndl)
END

745
Chapter 23: Using Alarms in SCADA

RETURN resultFilter;

END

Implementing queries that use custom alarm filters

Implementing a query based on the custom alarm filters you have defined requires two
steps:
1. Write the Cicode function that will be used as the query function. The recommended
format of the query function you need to create is:
INT FUNCTION Query (STRING sInfo)

where:

A user defined string to be used to control the logic in the Query function.
sIn-
fo

2. Specify the query function and its arguments in a call to AlarmSetQuery().The query
function should be constructed using the new v7.30 alarm filter functions.
The query function should use the new v7.30 Alarm Filter functions to select alarms
related to a particular type of information.
To filter alarms, call the AlarmFilterEditOpen, AlarmFilterEditSet and Alarm-
FilterEditAppend, AlarmFilterEditCommit, AlarmFilterEditClose functions from within
your query function.
The alarms within any query function can also be filtered via AlarmSetInfo type=12 func-
tion and an edited named filter.

Example

You want to create a query that calls current alarms for the conveyors in your plant.
This could be drawn from the alarm tags you have identified as being associated with a
conveyor, by applying the keyword "conveyor" to the field Custom Filter 1.
The AlarmFilterEditSet (hndl, "Custom1=conveyor") followed by the Alarm-
FilterEditCommit(hndl) function will filter your alarm data for "conveyor" information.
The query function you would create would be as follows:

! This query function called FilterCustom1()

746
Chapter 23: Using Alarms in SCADA

! filters alarms by the requested Custom filter 1.

! Only alarms with the requested Custom Filter 1 are displayed.

INT
FUNCTION
FilterCustom1(STRING sValue)
INT iResult=-1, INT iHndl=-1,
STRING sFilter="";
sFilter = "Custom1=" + "^"" + sValue + "^"";
iHndl= AlarmFilterEditOpen(21);
IF iHndl <> -1 THEN
iResult = AlarmFilterEditSet(iHndl,sFilter)
IF iResult = 0 THEN
iResult = AlarmFilterEditCommit(iHndl)
END
AlarmFilterEditClose(iHndl)
END

RETURN iResult;

END

Say you then want to create a button on a graphics page that lists current conveyor
alarms. You would implement this by applying the custom function to the button.

FilterCustom1(“converyor”);

You could also create a reset button that clears the current displayed list by canceling the
query:

hSession = AlarmFilterEditOpen(21);
AlarmFilterEditSet(hSession, “”);
AlarmFilterEditCommit(hSession);
AlarmFilterEditClose(hSession);

You have the choice of calling a specific Cicode function, for example, "Customfield1",
with the argument "pumpcontrol", or using a more generic approach with the function
"Checkfield" with argument "CUSTOM1= pumpcontrol". In this case, the Cicode function
filters the passed string and checks the field specified.

Understanding Named Filters

In v7.40 you can open, and create a named filter and use it across multiple alarm lists.

747
Chapter 23: Using Alarms in SCADA

A named filter can be used to filter an alarm list or an alarm count only if that alarm list
or alarm count is associated to the named filter. It is not used to directly filter alarms.
Instead it is used to update the active filter of multiple alarm lists or alarm counts. Once
you create the named filter you then edit it to add the filter criteria you want the named
filter to query.
To associate an alarm list to a named filter, you need to call AlarmSetInfo(AN, 12,
“Named Filter”), where AN is the animation number of the list being associated, 12 is
the mode for associating the named filter to the alarm list, and “NamedFilter” is the
name of the filter that was created by calling the function AlarmFilterOpen() .
To disassociate the named filter from an alarm list set “NamedFilter” to empty text e.g.
AlarmSetInfo(AN, 12, “”). This will remove the association from the named filter, but the
disassociated alarm list will not be refreshed, hence the filter query will still be in place
until a new filter is applied.
In order to associate an alarm count to a named filter, you need to call AlarmCount
(Type, “NamedFilter”, KeepAliveSeconds, CacheMode), where Type, KeepAliveSeconds
and CacheMode are documented in the AlarmCount function, and “NamedFilter” is the
named filter that was previously opened by calling AlarmFilterOpen.
In each of these cases, editing the filter criteria belonging to the named filter will update
all associated alarm lists or alarm counts.
Example
The following examples show how to open, edit (add filter criteria), associate, dis-
associate and close a named filter called “MyFilter”.

// The following examples show how to open, edit, associate, disassociate and close
// a named filter (e.g. "MyFilter").
// These are fictional examples for demonstration purposes only.
// The prompt message is dispplayed in prompt-line for increasing clarity.
// This function returns zero when all examples are successful,
// otherwise error is returned.
INT
FUNCTION
AlarmNamedFilterExamples()

INT iError, iHndl;

INT iAN=21; // Animation Number
INT iOpenModeNew = 1;
INT iCloseModeManual = 0;
INT iAlarmCounted=0, IAlarmDisplayed=0;
STRING sName, sEmptyString="", sNamedFilter, sLinkedFilter;

! Open the new filter named "MyFilter"

sNamedFilter = "MyFilter";
iError = AlarmFilterOpen(sNamedFilter, iOpenModeNew, iCloseModeManual);

748
Chapter 23: Using Alarms in SCADA

IF iError <> 0 THEN

Prompt ("MyFilter open error!");
RETURN iError;
END;

! Edit this filter by selecting alarms of Category 1 and Area 0

iHndl = AlarmFilterEditOpen(sNamedFilter);
IF iHndl <> -1 THEN;
iError = AlarmFilterEditSet(iHndl,"Category=1;Area=0;");
IF iError = 0 THEN
iError = AlarmFilterEditCommit(iHndl);
IF iError = 0 THEN
iError = AlarmFilterEditClose(iHndl);
END
END
IF iError <> 0 THEN
Prompt ("MyFilter edit error!");
RETURN iError;
END
ELSE
Prompt ("MyFilter hndl-edit error!");
RETURN iHndl;
END;

! Associate this filter to the specified AN of Alarm page.

! Other alarm pages can be linked in simmilar way.
PageDisplay("Alarm");
iError = AlarmSetInfo(iAN, 12, sNamedFilter);
IF iError <> 0 THEN
Prompt ("MyFilter link error!");
RETURN iError;
END

! Retrieve associated filter name. Verify associated filter.

sLinkedFilter = AlarmGetFilterName(iAN); // "MyFilter"
IF sLinkedFilter <> sNamedFilter THEN
Prompt ("MyFilter get-name error!");
RETURN iError;
END;

! Count active alarms of this filter and verify against displayed alarms
iAlarmCounted = AlarmCount(0, sNamedFilter, 1,0);
iAlarmDisplayed = AlarmCountList(iAN);
IF iAlarmCounted <> iAlarmDisplayed THEN
Prompt ("Count verification error!");
RETURN iError;
END;

! disassociate "MyFilter"
iError = AlarmSetInfo(iAN, 12, "");
IF iError <> 0 THEN
Prompt ("MyFilter unlink error!");
RETURN iError;
END;

749
Chapter 23: Using Alarms in SCADA

! Verify disassociate action.

sName = AlarmGetFilterName(iAN); // ""
IF sName <> sEmptyString THEN
Prompt ("MyFilter unlink error!");
RETURN iError;
END;

! Close this filter

iError = AlarmFilterClose(sNamedFilter);
IF iError <> 0 THEN
Prompt ("MyFilter Close error!");
END;

RETURN iError;

END

See Also
Implementing queries that use custom filters

Implementing alarm filters using Cicode

For historical event lists, you can define and apply a filter (the filter is not shared
between lists). The filter is a combination of conditions on the different fields which
define the set of rows to display. These conditions may become large, with Cicode only
permitting a string of 254 characters. The set / append functions allows you to separate
the filter into smaller pieces without verification of the syntax on the sub parts. The
whole filter (e.g. concatenation of the pieces) is validated and applied later by the com-
mit function.
Multiple Cicode tasks can access the same filter and modify it, with the filter browsing
and modification part of a session. This follows the principles used in tag browsing.
Filter syntax

The syntax of the filter will be verified against the following BNF grammar:
1. <filter> ::= <filter_expr> { " ;" <filter_expr> }
2. < filter_expr > ::= { ["("]<filter_expr>[")"] <logical_binary_op> ["("]<filter_expr>[")"]
| <comparison>
| "NOT" "(" <filter_expr>")"}
3. <comparison> ::= <field> <comparison_op> <value>
4. <comparison_op> ::= "="|">"|"<"|">="|"<="
5. <logical_binary_op> ::= "AND" | "OR"

750
Chapter 23: Using Alarms in SCADA

6. <value> ::= <string_value> | <boolean_value> | <DateTime_value> |<int_value>

7. <string_value> ::= <singleword> ["*"]
| " ’ " <singleword> { {" <space>"} <singleword>["*"] } " ’ "
8. <singleword> ::= {any character but space}
9. < boolean_value > ::= "0" | "1"
10. < int_value > ::= ["-"]{numeric char}["." numeric char]
11. < DateTime_value > ::= string of number of sec.
as returned by IntToStr( TimestampToTimeInt(..)) in UTC
12. <field>::= valid citect field name (case insensitive).

Note:
• (1) The ";" between <filter_expr> is interpreted as AND
• (2) The parenthesis are optional but recommended to obtain the right evaluation
order. If they are present they need to match.
• (7) The "*" is standard wild card. it can be use only once per <string_value>

Valid filters examples:

l Tag=A
l (Tag=A) OR (TAG=B)
l (Tag=A) OR (TAG=B) ; Name=C
l Time > IntToStr(TimestampToTimeInt(yesterday))
l Tag=Dig*
l Message="quoted sentence with blanks"
l (((Tag=A) OR (TAG=B)) AND (category=1))
When using the alarm filter Cicode functions first open a session (AlmFilterOpen) and
then use this session to browse the different parts (AlmFilterFirst/Next/Prev) of the filter
and to update (AlmFilterSet / Append / Commit) the filter. The browse session will be
available until closed (AlmFilterClose).
Multiple sessions can be used on the same list. For multiple sessions modify the same
filter then the current applied filter is the result of the last commit.

Efficiency considerations
Alarms within query functions can be filtered by using edited named filters and Alarm-
SetInfo type=12 function.

751
Chapter 23: Using Alarms in SCADA

For example the AlarmSetInfo(21,12, "MyFilter") will link AN=21 to the filter named
"MyFilter".
See Also
Alarm Categories

Alarm Categories
After adding alarms to your project, you can then create categories to group them, such
as creating a category number ‘23’ to group all your alarms that monitor pumps in your
system into.
For each category, you can set the following:
l alarm display details (fields, font and page type)
l logging details (printer or data file)
l action to be taken when an alarm in the category is triggered (for example, activating
an audible alarm).
l associated priority. The alarm priorities can be used to order alarm displays, pro-
viding useful filtering for the operator.
You can configure up to 16376 alarm categories. If you do not specify a category for an
alarm, the alarm has the same attributes as alarm category 0. If you do not define an
alarm category 0, a default is used for the category.
To define an alarm category:

1. Choose Alarms | Alarm Categories. The Alarm Categories dialog box is displayed.
2. Complete the alarm categories form.
3. Click Add to append a new record, or Replace to modify an existing record.
See Also
Alarm Category Properties

Alarm Category Properties

Alarm Categories have the following properties:

752
Chapter 23: Using Alarms in SCADA

UNINTENDED EQUIPMENT OPERATION

Do not put a blocking Cicode function in the ON Action field. A blocking function will affect
the polling of alarms, and may result in slow or delayed alarm processing.

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

UNINTENDED EQUIPMENT OPERATION

Do not put a blocking Cicode function in the OFF Action field. A blocking function will affect
the polling of alarms, and may result in slow or delayed alarm processing.

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

UNINTENDED EQUIPMENT OPERATION

Do not put a blocking Cicode function in the ACK Action field. A blocking function will affect
the polling of alarms, and may result in slow or delayed alarm processing.

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

Field Description

Category Number The alarm category (0-16375). Enter a category of 16 char-

acters or less.

The following category numbers are reserved:

l Category 0 is reserved for selecting all the alarms with

all categories.
l Category 254 is reserved for user-created alarm sum-
mary entries.
l Category 255 is reserved for hardware alarms.

Priority Priority applied to alarms assigned to this alarm category (0-

255). Alarm priority governs the order in which alarms are
displayed, acknowledged, enabled and so on. Enter a priority
of 16 characters or less.

753
Chapter 23: Using Alarms in SCADA

Field Description

Priority 1 is the highest priority, and priority 255 is the low-

est. For example, if alarms with priorities 1 to 8 were dis-
played, priority 1 alarms would be displayed first in their
time/date order, then priority 2 alarms, then priority 3, and so
on up to priority 8.

Priority 0 is the default priority and is reserved for selecting

all alarms with all priorities. Priority 0 is used to reference
priorities. For example, to change the display parameters of
an alarm list, so that alarms of priorities are displayed, Alarm-
SetInfo would be used with Type = 7, Value = 0.

Note: When priority 0 is used to display alarms of priorities,

priority 0 only alarms will display first, followed by priority 1
alarms, then priority 2 etc. You can also customize the order
in which alarms will be displayed on the alarm summary page
using the SummarySort and SummarySortMode parameters.
(This order will override the alarm category priority order.)

Display on Alarm Page Category displayed on alarm page. True/False drop-down, with
True being the default. Enter a value of 6 characters or less.

Display on Summary Category displayed on Summary Page. True/False drop down,

Page with True being the default. Enter a value of 6 characters or less.

Unacknowledged:Alarm The font to display alarms that are no longer active (but have not
Off Font been acknowledged). This property is optional. If you do not
specify a font, the font defaults to 10 pt. BROWN. Enter a value
of 16 characters or less.

Acknowledged: Alarm The font used to display alarms that are no longer active and
Off Font have been acknowledged. This property is optional. If you do not
specify a font, the font defaults to 10 pt. WHITE. Enter a value of
16 characters or less.

Unacknowledged: The font used to display an expression that has not been
Alarm On Font acknowledged. This property is optional. If you do not specify a
font, the font defaults to 10 pt. YELLOW. Enter a value of 16 char-
acters or less.

Acknowledged: Alarm The font used to display an active alarm that has been acknowl-
On Font edged. This property is optional. If you do not specify a font, the
font defaults to 10 pt. CYAN. Enter a value of 16 characters or
less.

Disabled Font The font used to display disabled alarms. This property is
optional. If you do not specify a font, the font defaults to 10 pt.
WHITE. Enter a value of 16 characters or less.

ON Action A Cicode command that is executed when an alarm of this Cat-

egory is triggered.
Example 1:
Where Alarm ON Action is STOP_PROCESS = 1;

754
Chapter 23: Using Alarms in SCADA

Field Description

In this example the digital variable STOP_PROCESS is set to ON

when an alarm in this category is triggered.
Note: Do not put a Cicode blocking function in this field. The
alarm system executes ON, OFF, or ACK actions within the polling
loop. A blocking function will affect the polling of alarms, and
may result in slow or delayed alarm processing.
A special case of this command occurs when the Alarm ON Action
is self-referring, with a form such as TAG1 = TAG1 + 1. This
command will not work properly since tags are not reread before
processing the Alarm On action (for performance reasons). This
particular command will therefore initially set the value of TAG1
to 1 rather than incrementing it.
To correctly run a command of this type in the Alarm ON Action,
use TaskNew() to run your own Cicode function to perform the
tag command:
Example 2: Where Alarm ON Action is TaskNew("MyFunc",
"Data",5);

OFF Action A Cicode command that is executed when an alarm of this Cat-
egory is reset.
Example:
where Alarm OFF Actionis ENABLE_PROCESS = 1;
In this example the digital variable ENABLE_PROCESS is set to
ON when an alarm in this category is reset.
Note: Do not put a Cicode blocking function in this field. The
alarm system executes ON, OFF, or ACK actions within the polling
loop. A blocking function will affect the polling of alarms, and
may result in slow or delayed alarm processing.

ACK Action A Cicode command that is executed when an alarm of this Cat-
egory is acknowledged .
Note: Do not put a blocking Cicode function in this field. The
alarm system executes ON, OFF, or ACK actions within the polling
loop. A blocking function will affect the polling of alarms, and
may result in slow or delayed alarm processing.

Alarm Format The screen display format for alarms in this category. The
(Optional) Alarm Display format specifies how the data (for alarms in the
category) are displayed on the alarms page (on the screen
only). Each alarm displays on the alarms page in a single line,
for example:

12:32:21RFP3 Raw Feed pump 3 Overload

If you do not specify a Alarm Display format, the format

defaults to:

{Time,12} {Tag,10} {Name,20} {Desc,32}

755
Chapter 23: Using Alarms in SCADA

Field Description

See Alarm display fields for the formatting details for each
field type.

When alarms are displayed using variable width fonts (such

as Arial or Helvetica), the alarm fields may not align properly
across different rows. This can be avoided by using a field
separator in the alarm format configuration instead of just a
space. Tab characters, denoted by either "^t" (horizontal tab)
or "^v" (vertical tab), between the alarm fields will act as
alignment points in your alarm display.

Change the default Alarm Display Format for alarms by setting

the [Alarm]DefDspFmt parameter.

Note: If an alarm value is longer than the field it is to be dis-

played in, it will be truncated or replaced with the #OVR
("overflow of format width") alert message. When the alarm is
logged to a device (i.e. printed or written to a file or data-
base), the format specified for the logging device overrides
the display format.

NoteAlarm pages based on the new tab-style templates do

not consider individual formats for each category. The screen
display format for the Alarm page is set by the first available
of the below definitions, according to the order listed below:

l [Format]Alarm parameter
l the Alarm format specified for category 0
l [Alarm]DefDspFmt parameter
l Default Alarm display format if none of the above is spec-
ified

Summary Format The summary display format for alarms in this category. The
(Optional) Summary Display format specifies how the alarm summary
displays on the alarms summary page (on the screen only).

The display format is defined exactly as the Alarms Display

Format. However, you can also use additional data fields.

If you do not specify a Summary Display format, the format

defaults to:

{Name,20} {OnTime,8} {OffTime,8} {DeltaTime,8}

{Comment,22}

See Alarm summary fields for formatting details for each field
type.

When alarms are displayed using variable width fonts (such

as Arial or Helvetica), the alarm fields may not align properly
across different rows. This can be avoided by using a field
separator in the alarm format configuration instead of just a

756
Chapter 23: Using Alarms in SCADA

Field Description

space. Tab characters, denoted by either "^t" (horizontal tab)

or "^v" (vertical tab), between the alarm fields will act as
alignment points in your alarm display.

Change the default Summary Display Format for alarms by set-

ting the [Alarm]DefSumFmt parameter.

Note: When the alarm is logged to a summary device (i.e.

printed or written to a file or database), the format specified
for the logging device overrides the display format.

Note: Summary pages based on the new tab-style templates

do not consider individual formats for each category. The
screen display format for the Summary page is set by the first
available of the below definitions, according to the order listed
below:

l [Format]Summary parameter,
l the Summary format specified for category 0
l {Alarm]DefSumFmt parameter
l Default Summary display format if none of the above is
specified

SOE Format(Optional) The SOE display format for alarms in this category. The SOE dis-
play format specifies how the Sequence of Events view will dis-
play on the alarms SOE page (on the screen only).
The display format is defined exactly as the Alarms Display For-
mat. However, you can also use additional data fields. If you do
not specify an SOE Display format, the format defaults to:
{DATE,16} {TIME,16} {TAG,10} {NAME,15} {MES-
SAGE,64} {STATE,16} {CLASSIFICATION,13} {USER-
NAME,16} {USERLOCATION,16}

See Alarm summary fields and Alarm display fields for for-
matting details for each field type.

When alarms are displayed using variable width fonts (such

Change the default SOE Display Format for alarms by setting

the [Alarm]DefSOEFmt parameter.

Note: SOE pages based on the new tab-style templates do not

consider individual formats for each category. The screen dis-
play format for the SOE page is set by the first available of the
below definitions, according to the order listed below:

l [Format]SOE parameter

757
Chapter 23: Using Alarms in SCADA

Field Description

l the SOE format specified for category 0

l {Alarm]DefSOEFmt parameter
l Default SOE display format if none of the above is spec-
ified

Alarm Acquisition Error Acquisition error is an error related to acquiring data from I/O
sub-system for the underlying tag and/or expression, for exam-
ple, Device Offline, Tag Unknown, etc. (Integer length 6).
All acquisition errors are stored for each alarm record separately
within the alarm server as a new AcqError field. They are not
logged and no hardware alarm is raised from them.
The AcqError field stores the error as the Citect error code (for
example, NO ERROR). This field is made accessible through the
alarm browse functionality. If there are multiple acquisition
errors for a single alarm record, then the first of these is stored
within the system.

Summary Device The device where the alarm summary is sent. An alarm is logged
(Optional) to the summary device when it has gone off, and has been dis-
played for a longer period than the time specified in the [Alarm]
SummaryTimeout parameter.
When the alarm is logged to the device, it is removed from the
alarm summary page. When the alarm is printed, or written to a
file or device, the format specified in the device overrides the dis-
play format. If not specified, alarm summaries are not logged.

Log Device The device where the alarm state changes are sent. An alarm
entry is made in the log device each time an alarm changes state
(for example, on, off, acknowledged, enabled, and disabled).
When the alarm is printed, or written to a file or device, the for-
mat specified in the device overrides the display format.
If not specified, alarm state changes are not logged.

Log Alarm Transitions Logs the alarm details when the alarm becomes active. The
ON default for this field is TRUE.

Log Alarm Tran- Logs the alarm details when the alarm becomes inactive. The
sitions:OFF default for this field is TRUE.

Log Alarm Transitions: Logs the alarm details when the alarm is acknowledged. The
ACK default for this field is TRUE.

Comment Any useful comment.

Formatting the Alarm Display

The display format specifies how alarms are displayed on screen for the alarms and
alarm summary pages.
For details on the default sort order of the alarm display list see Alarm List Default Sort
Order.
For details on how to change the order of alarms listed on the alarm summary page, see
Changing the Order of the Alarm Summary Display.
See Also
Including data
Including fixed text
Displaying lists and tables
Variable data in alarm messages
Alarm display fields
Alarm summary fields
Alarm List Default Sort Order

Alarm List Default Sort Order

The default sort order varies according to the type of alarm page and the [Alarm]Sort-
Mode parameter. For the Alarm summary page the parameter is [Alarm]Sum-
marySortMode.

[Alarm]Sum-
Type of view Default sorting order
marySortMode

Sequence of 0 {TIME,Descending}
events

Sequence of 1 {TIME,Ascending}
events

Alarm Sum- 0 {Ack,Ascending}{Active,Descending}{TIME,

mary Descending}

Alarm Sum- 1 {Ack,Ascending}{Active,Descending}{TIME,

mary Ascending}

Whatever sort order you specify the system will append the following default set of
order by fields:

Alarm list display Appended default sort order

Sequence of events RecordTime (ASC or DESC, depending on [Alarm]Sort-

Mode) SeqNo (DESC) Cluster (ASC) CommentNo (ASC)

759
Chapter 23: Using Alarms in SCADA

Alarm list display Appended default sort order

Alarm Summary As per [Alarm]SummarySort and [Alarm]Sum-

marySortMode

Active, Disabled, Acknowl- (ASC) Active (DESC) As per [Alarm]Sort and [Alarm]Sort-
edged, Off, On, Unac- Mode
knowledged

Configuration (non-hardware
Tag (ASC)
alarms in system)

For example:
According to the order you specified, if two records result in being equal, the records will
adhere to the default sort orders above. In the example where tags have no equipment
specified (and therefore are ordered equally) the alarms will be ordered according to Ack,
Active,Time.
If you specify Active (ASC), then the resultant order on the active page will be:
Active (ASC), Acknowledged (ASC), [Alarm]Sort / [Alarm]SortMode.

Including CitectSCADA data

Include data in an alarm display by specifying the field name and width for each field
to display. You need to enclose each field in braces {} and use the following syntax:

{<field name>, [width[, justification]]}

For example:

Format {Tag,8} {Name,32}

In this case, data displays in two fields: Tag, with 8 characters; and Name, with 32 char-
acters. The width specifier is optional; if you do not use it, the width of the field is deter-
mined by the number of characters between the braces.

Format Name of Alarm:{Name }

In this case, Name is followed by four spaces; the data {Name} displays with 8 char-
acters.

Note: The screen resolution of your computer determines the total number of char-
acters (and therefore the number of fields) that can be displayed on the alarms page.

760
Chapter 23: Using Alarms in SCADA

Including fixed text

You can include fixed text by specifying the text exactly as it will display; for example:

Format Name of Alarm:

Any spaces that you use in a text string are also included in the display.
See Also
Displaying lists and tables

Displaying lists and tables

To set the justification of the text in each field, use a justification specifier. You can use
three justification characters, L (Left), R (Right), and N (None); for example:

Format Name of Alarm:{Name,32,R} {Tag,8,L}

The justification specifier is optional; if it is omitted, the field is left justified. If you use a
justification specifier, you need to also use the width specifier.
To display field text in columns, use the tab character (^t); for example:

Format {Tag,8}^t{Name,32}^t{Desc,8}

This format aligns the tag, name and description fields of the alarm when using a pro-
portional font to display the alarms.
See Also
Variable data in alarm messages

Variable data in alarm messages

The Alarm Desc field of digital, advanced and time-stamped alarms can be used to dis-
play variable data. An expression (variable tag, function etc.) can be embedded into the
text of the Alarm Desc field. This expression is evaluated when the alarm is tripped,
returning the value of any variable tags at the point in time when the alarm was gen-
erated.
Enclosing the expression in braces separates the variable data from the static text. For
example:

761
Chapter 23: Using Alarms in SCADA

Alarm Desc Line Broken Alarm at Line Speed {LineSpeed1}

When LineSpeed1 is a variable tag, this expression will produce the following output on
the alarm display or alarm log:
Line Broken Alarm at Line Speed 1234
The following alarm entry uses an expression instead of a tag:

Alarm Desc High Level at Total Capacity {Tank1+Tank2+Offset()}

When Tank1 and Tank2 are variable tags, and Offset is a Cicode function, this expression
produces the following output:
High Level at Total Capacity 4985 liters

Note: The result is formatted according to the formatting specified for the first var-
iable tag in the expression. Standard variable formatting specifiers can be used to
define the format for the numeric variable, over-riding the default format specified in
Variable Tags.

Alarm display fields

You can use any of the fields listed below, or the Alarm Summary Fields, to format an
alarm display (see Alarm Categories) and an alarm log device (see Formatting an Alarm
Display).

Field Name Description

{AcqDesc,n} Textual representation of Alarm Acquisition Error.

{AcqError, n} Numeric representation of Alarm Acquisition Error.

{AlarmType,n} Alarm type (string), not localized. Values are: Digital, Analog,
Advanced, Multi-Digital, Time Stamped, Time Stamped Digital,
Time Stamped Analog.

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

{Area,n} Area

762
Chapter 23: Using Alarms in SCADA

Field Name Description

Note:Set the value of this field between 0 and 255

{Category,n} Alarm Category

{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}

{Date,n} The date on which the alarm changed state (dd:mm:yyyy). Be

aware that you can change the format used via the parameter
[ALARM]ExtendedDate.

{DateExt,n} The date on which the alarm changed state in extended format.

{Deadband,n} Deadband

{Desc,n} Alarm Description

{Deviation,n} Deviation Alarm trigger value

{ErrDesc,n} Text string associated with a protocol (communication) error.

This field is only associated with hardware errors and contains
extra information associated with whatever error is detected (for
example if the error is associated with a device, the device name
is returned; if the error is associated with a Cicode function, the
function name is returned; if the error is associated with an I/O
Device, the I/O Device's alert message is returned).

{ErrPage,n} The page, device, etc. associated with the alarm.

{Format,n} Display format of the Variable Tag

{Help,n} Help Page

{High,n} High Alarm trigger value

{HighHigh,n} High High Alarm trigger value

763
Chapter 23: Using Alarms in SCADA

Field Name Description

{LocalTimeDate,n} Alarm date and time in the form: "yyyy-mm-dd hh:mm:ss[.ttt]"

{LogState,n} The last state that the alarm passed through. (This is useful
when logging alarms to a device.)

{Low,n} Low Alarm trigger value

{LowLow,n} Low Low Alarm trigger value

{Name,n} Alarm Name

Note: If the Name field is configured to support long names (up

to 79 characters), it might cause overlap in an alarm display.
Use a smaller display font if long names are expected.

{Native_Desc,n} Alarm Description in the native language

{Native_Name,n} Alarm Name in the expression

Note: If the Native_Name field is configured to support long

names (up to 79 characters), it might cause overlap in an alarm
display. Use a smaller display font if long names are expected.

{Paging,n} Indicates whether the alarm has to be paged. When the value is
TRUE the alarm will be paged. The default value is FALSE. See
Alarm Paging Properties.

{PagingGroup, n} Indicates the paging group to which the alarm belongs. Max-
imum length is 80 characters.

{Priority,n} Alarm category's priority

{Priv,n} Privilege

{Rate,n} Rate of change trigger value

{State,n} The current state of the alarm. This field may be used for
Alarm Display Only. It is not applicable to Alarm Summary.
ON
OFF
DEVIATION
RATE
LOW
LOWLOW
HIGH
HIGHHIGH

764
Chapter 23: Using Alarms in SCADA

Field Name Description

ON State 2
ON State 3
ON State 4
ON State 5
ON State 6
ON State 7
CLEARED

{State_desc, n} The configured description (for example healthy or stopped) of a

particular state. This description is entered when configuring
the Multi-Digital Alarm Properties

{Tag,n} Alarm Tag

Note: If the Tag field is configured to support long names (up to

79 characters), it might cause overlap in an alarm display. Use a
smaller display font if long names are expected.

{TagEx,n} Alarm Tag with Cluster Name prefix

Note: If the TagEx field is configured to support long names (up

to 79 characters), it might cause overlap in an alarm display.
Use a smaller display font if long names are expected.

{Time,n} The time at which the alarm changed state (hh:mm:ss). (Set the
[Alarm]SetTimeOnAck parameter to use this field for the time the
alarm is acknowledged.)

{Type,n} The type of alarm or condition:

ACKNOWLEDGED
CLEARED
DISABLED
UNACKNOWLEDGED

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

-1 Invalid
0 Digital
1 Analog
2 Advanced
3 Multi-Digital
4 ArgAna
5 User Event
6 timestamped
7 hardware
8 timestamped digital
9 timestamped analog

765
Chapter 23: Using Alarms in SCADA

Field Name Description

{Value,n} The current value of the analog variable

{Classification,n} The class of the event. E.g:

-“Action”
- “Comment”
- “Configuration”
- “System”
- “<alarm type>”

{Equipment,n} The name of the equipment the alarm is associated with.

{Message,n} The event message.

{Millisec,n} Adds milliseconds to the {Time,n} field

{RecordId,n} String that uniquely identifies SOE records within the cluster. On
the Alarm Summary table, this field references the associated SOE
record.

{State,n} State of the event. The value of this field indicates the action that
triggers the event, similar to the value returned by the existing Log-
State field.

{UserLocation,n} The IP address or machine name where the event was triggered.

Where n specifies the display field size.

Notes:
• Any of the above fields can be displayed for any type of alarm. Where not appli-
cable for a particular alarm type, zero or an empty string will be displayed.
• If an alarm value is longer than the field it is to be displayed in (n ), it will be trun-
cated or replaced with the #OVR ("overflow of format width") alert message.
• For summary pages use {SumState}. To log the state to a device, use {LogState}.
State is the current state of the alarm, SumState is the state of the alarm when it
occurred, and Log State is the state of the alarm at the transition.

Alarm SOE fields

You can use any fields listed below (or a combination) to format an alarm soe display.
Those fields specific to the event journal can be archived.
Format the alarm SOE for an entire category of alarms by specifying field names in the
SOE Format field of the Alarm Category Properties dialog box.

766
Chapter 23: Using Alarms in SCADA

You can also use the [Alarm]DefSOEFmt parameter to format the alarm SOE, particularly if
your alarm SOE formats are to be the same.

Field Name Description Archived

{AcqDesc,n} Textual representation of Alarm Acquisition Error. No

{AcqError,n} Acquisition error. Separate event (error code) in SOE. No

{AlarmType, Alarm type (text). "Digital", "Analog", "Advanced", "Multi- No

n} Digital", "Time Stamped", "Time Stamped Digital", "Time
Stamped Analog"

{Alm- Alarm comment No

Comment,n}

{Area,n} Alarm area. Numeric value (integer) No

{Category,n} Alarm category. Numeric value (integer) No

{Clas- The class of the event. E.g: Yes

sification,n} -“Action”
- “Comment”
- “Configuration”
- “System”
- “<alarm type>”

{Cluster,n} The cluster the tag belongs to. No

{Comment, A comment the operator adds to an event entry during Yes

n} runtime. The comment is specified using the Alarm-
Comment() function.

{CUSTOM1, Alarm custom fields from 1 to 8 No

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

{Date,n} Part of event record time in event journal. Yes

{DateExt,n} Part of event record time in event journal. Yes

{DeadBand, Alarm deadband. For Analog, and Timestamped Analog No

n} alarms: Numeric value (real)

767
Chapter 23: Using Alarms in SCADA

Field Name Description Archived

{Deviation,n} Alarm deviation. For Analog, and Timestamped Analog No

alarms: Numeric value (real)

{Desc,n} Alarm Description Yes

{Equipment, The name of the equipment the alarm is associated with. No

{FullName, The full name of the user (Full Name) who was logged on No
n} and performed some action on the alarm (for example
acknowledging the alarm or disabling the alarm, etc.).
When the alarm is first activated, the full name is set to
"system" (because the operator did not trip the alarm).
This field is not localized.

{Group,n} Alarm group. For Argyle Digital (Multi-digital) alarms: No

Numeric value

{Help,n} Alarm help. The name of the help page. No

{High,n} High Alarm trigger value No

{HighHigh,n} High High Alarm trigger value No

{Local- Alarm date and time in the form: "yyyy-mm-dd Yes

TimeDate,n} hh:mm:ss[.ttt]"

{LogState,n} The last state that the alarm passed through. (This is Yes
useful when logging alarms to a device.)

{Low,n} Low Alarm trigger value No

{LowLow,n} Low Low Alarm trigger value No

{Message,n} The event message. Yes

{MilliSec,n} Alarm milliseconds. Numeric value (integer) Yes

{Name,n} Alarm Name No

{Native_ Native language comments the operator adds to an event No

Comment, entry during runtime.
n}

{Native_ A description of the alarm summary, in the native lan- No

SumDesc, guage.
n}

{Paging,n} Alarm paged flag. A flag to indicate that the alarm is going No
to be paged. Values are 1 (TRUE) or 0 (FALSE).

768
Chapter 23: Using Alarms in SCADA

Field Name Description Archived

{Pag- Paging group for alarm. A free form text field indicating the No
ingGroup,n} sequence of people to notify in the event the alarm
occurred.

{Priority,n} Alarm category priority. Numeric value (integer) No

{Priv,n} Alarm privilege. Numeric value (integer) No

{Quality, n} The IO server will pass the quality of the tag to the Alarm No
server when a tag's value is changed. If the changed tag
value causes a state transition the alarm server will pass
the quality to the database. This field displays the raw
value (2 bytes numeric). The field TSQuality relates to this
field and displays high byte of the 2 byte value in a string.

{Rate,n} Alarm rate. For Analog, and Timestamped Analog alarms: No

Numeric value (real)

{ReceiptDate, Date the master station received the event.For example,

n} Date the RTU received the event.

{Receipt- This field displays the alarm’s occurrence time (if known),
Local- otherwise it displays the receipt time of the alarm.
DateTime,n}

{ReceiptTime, Time the event was logged into the database. No

{SetPoint,n} Alarm setpoint value No

{State,n} Current state of alarm. Yes

{State_Desc, The configured description (for example healthy or No

n} stopped) of a particular state. This description is entered
when configuring the Multi-Digital Alarm Properties

{State_ Argyle state 0-7. For Argyle Digital (Multi-digital) alarms: No

Desc0,n} "OFF". For others: "INVALID"
{State_
Desc1,n}
{State_
Desc2,n}
{State_
Desc3,n}
{State_
Desc4,n}
{State_
Desc5,n}
{State_
Desc6,n}
{State_
Desc7,n}

{SumDesc,n} Alarm description text. Analog alarm - Alarm state text. No

Otherwise - Configured event [or alarm in case event not
defined] description

769
Chapter 23: Using Alarms in SCADA

Field Name Description Archived

{Sum- Describes the state of the alarm when it occurred. No

State,n}

{Tag,n} Alarm Tag Yes

Note: If the Tag field is configured to support long names
(up to 79 characters), it might cause overlap in an alarm
display. Use a smaller display font if long names are
expected.

{TagItem,n} Alarm Tag with Cluster Name prefix No

Note: If the TagEx field is configured to support long

names (up to 79 characters), it might cause overlap in
an alarm display. Use a smaller display font if long
names are expected.

{TagEx,n} Alarm source Yes

{Time,n} Alarm Time 12 hh:mm:ss [am|pm]. Yes

Note: works between: UTC time 1/1/1980 - UTC time
31/12/2037, otherwise ""

{TimeDate,n} Special SQL formatted time. HH:MM:SS. Yes

Note: The format can be configured in the citect.ini file by
specifying TimeDate under the section [Alarm].

{TSQuality,n} The IO server will pass the quality of the tag to the Alarm Yes
server when a tag's value is changed. If the changed tag
value causes a state transition the alarm server will pass
the quality to the database. The field displays high byte of
the 2 byte value (available under the Quality field) in a
string . Expected Timestamp Quality strings are: Time
Good, Time Uncertain, Clock Not Synchronized, or empty
string if no match is found.

{Type,n} The type of alarm or condition: ACKNOWLEDGED, DIS- Yes

ABLED, UNACKNOWLEDGED

{TypeNum,n} Alarm type number (use AlarmType to get string value No

instead). Values are: -1 Invalid, 0 Digital 1, Analog 2,
Advanced 3, Multi-Digital 4, ArgAna 5, User Event 6, times-
tamped 7, hardware 8, timestamped digital 9, timestamped
analog

{User- The IP address or machine name where the event was trig- Yes
Location,n} gered.

{User- The name of the user (User Name) who was logged on Yes
Name,n} and performed some action on the alarm (for example
acknowledging the alarm or disabling the alarm, etc.).
When the alarm is first activated, the user name is set to
"system" (because the operator did not trip the alarm).

Where n specifies the display field size.

770
Chapter 23: Using Alarms in SCADA

See Also
Changing the Order of the Alarm Summary Display

Alarm summary fields

You can use any fields listed below (or a combination) to format an alarm summary dis-
play and an alarm summary device.
Format the alarm summary for an entire category of alarms by specifying field names in
the Summary Format field of the Alarm Category Properties dialog box.
You can also use the [Alarm]DefSumFmt parameter to format the alarm summary, par-
ticularly if your alarm summary formats are to be the same.

Field Name Description

{AckDate,n} The date when the alarm was acknowledged

{AckDateExt,n} The date (in extended format) when the alarm was
acknowledged (dd/mm/yyyy)

{AckTime,n} The time when the alarm was acknowledged

{Comment,n} A comment the operator adds to an Alarm Summary

entry during runtime. The comment is specified using
the AlarmComment() function.

{DeltaTime,n} The time difference between OnDate/OnTime and Off-

Date/OffTime, in seconds

{FullName,n} The full name of the user (Full Name) who was logged on
and performed some action on the alarm (for example
acknowledging the alarm or disabling the alarm, etc.).
When the alarm is first activated, the full name is set to
"system" (because the operator did not trip the alarm).

{Native_Comment,n} Native language comments the operator adds to an

Alarm Summary entry during runtime.

{Native_SumDesc,n} A description of the alarm summary, in the native lan-

guage

{OffDate,n} The date when the alarm returned to its normal state

{OffDateExt,n} The date (in extended format) when the alarm returned
to its normal state (dd/mm/yyyy)

771
Chapter 23: Using Alarms in SCADA

Field Name Description

{OffMilli,n} Adds milliseconds to the time the alarm returned to its

normal state.

{OffTime,n} The time when the alarm returned to its normal state

{OnDate,n} The date when alarm was activated

{OnDateExt,n} The date (in extended format) when the alarm was acti-
vated (dd/mm/yyyy)

{OnMilli,n} Adds milliseconds to the time the alarm was activated.

{OnTime,n} The time when the alarm was activated

{SumDesc,n} A description of the alarm summary

{SumState,n} Describes the state of the alarm when it occurred

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

are ACKNOWLEDGED, DISABLED, UNACKNOWLEDGED

{UserName,n} The name of the user (User Name) who was logged on
and performed some action on the alarm (for example
acknowledging the alarm or disabling the alarm, etc.).
When the alarm is first activated, the user name is set to
"system" (because the operator did not trip the alarm).

Where n specifies the display field size.

Note: You can also include in your Alarm Summary any alarm display field other
than State.

See Also
Changing the Order of the Alarm Summary Display

Changing the Order of the Alarm Summary Display

You can customize the order in which alarms are displayed on the alarm summary
page by using the SummarySort and SummarySortMode parameters. The SummarySort param-
eter allows you to display alarms according to OnTime, OffTime, and AckTime. Sum-
marySortMode determines if the alarms will be arranged in ascending or descending order.
(The order set using these parameters will override the alarm category priority order.)

772
Chapter 23: Using Alarms in SCADA

Using System Fonts

Alarm categories and Cicode functions allow you to use predefined fonts, known as sys-
tem fonts, to display text. You can also configure your own fonts; for details see Con-
figuring Custom Color Fonts.

Note: If an animation is associated with an I/O Device that does not initialize prop-
erly at startup or goes offline while the system is running, the associated animation
is grayed on the relevant graphics pages (because the values are invalid). You can
disable this feature with the [Page]ComBreak parameter. See Handling Communication
Errors in Reports.

To define a system font:

1. In the Project Editor or the Graphics Builder, choose System|Fonts. The Fonts dialog
box appears.
2. Enter your font properties.
3. Click Add to append a new record, or Replace to modify an existing record.
See Also
Fonts properties

Fonts properties
Use the Fonts dialog box to define your font properties. Fonts have the following prop-
erties:
Font Name
The name of the font. Unlike background text, strings, and numbers (which can use any
standard Windows font), you need to define a font for animated text.
Font Type
Any text font supported by Windows (31 characters maximum). Choose a font type from
the menu.
You can also specify bold, italic, and underlined text. To specify any of these options,
append the appropriate specifier to the Font Type, for example:

Font Type Courier,B

773
Chapter 23: Using Alarms in SCADA

Specifies bold characters.

Font Type Helv,I

Specifies italic characters.

Font Type TmsRmn,U

Specifies underlined text.

You can also specify multiple options, for example:

Font Type Courier,B,I,U

Specifies bold, italic, and underlined characters.

Note: To use a font that is not displayed in the menu, you need to install the font on
your computer before you can use it in your system. To view, install, or remove Win-
dows fonts, use the Windows Control Panel (Fonts Option). Refer to your Windows
documentation for details. (If your system uses a network, every computer needs to
have the font installed.)

Pixel Size
The size of the displayed text. You can specify text fonts in pixels or points.
To specify a point size, enter a negative number in the Pixel Size field; for example:

Font Size -10

specifies a ten-point font size. Be aware that you can only specify a point size as a whole
number (integer).
If you have not installed the Font Type (or Pixel Size) on your system, a default font
and/or size is used that most closely resembles the font and/or size you have specified.
If you use a point size, the size remains constant across screen resolutions. On low-res-
olution screens, the font appears larger than on high-resolution screens, which might
cause misalignment of animation. Only use a point size to display text on computer
screens of the same resolution.
Foreground Color

774
Chapter 23: Using Alarms in SCADA

The foreground color of the displayed text (i.e., the color of the text characters). You can
use a predefined color label (accessible via the menu), a user-defined custom label, or the
RGB encoded number generated by the function MakeCitectColour (see the Cicode Reference
Guide).

Note: Do not confuse predefined labels with the color Name feature associated with
the Color Picker. You cannot use color names with this dialog; doing so generates a
compile error.

Foreground Flash
The secondary color applied to the font if using flashing color for your text characters.
You can use a predefined color label (accessible via the menu), a user-defined custom
label, or the RGB encoded number generated by the function MakeCitectColour (see the
Cicode Reference Guide).
If you do not specify a color, the text remains solid.
Background Color
The background color of the displayed text. You can use a predefined color label (acces-
sible via the menu), a user-defined custom label, or the RGB encoded number generated
by the function MakeCitectColour (see the Cicode Reference Guide).
This property is optional. If you do not specify a background color, it defaults to trans-
parent.
Background Flash
The secondary color applied to the background if using flashing color. You can use a
predefined color label (accessible via the menu), a user-defined custom label, or the RGB
encoded number generated by the function MakeCitectColour (see the Cicode Reference
Guide).
If you do not specify a color, the text remains solid.
Comment
Any useful comment (48 characters maximum).

Configuring Custom Color Fonts

From CitectSCADA version 6.0 onwards, colors are referenced by using hex codes for
red, green and blue (RGB) values. You can view RGB values (in decimal) of a selected
color by choosing Tools|Edit Favorite Colors in Graphics Builder.
If, for example, the color you want to use has the values R = 128, G = 170, B = 213, you
can convert these to their hex equivalents (R = 0x80, G = 0xAA, B = 0xD5).
If you define a label for your color, you can use decimal or hex values. For example:

775
Chapter 23: Using Alarms in SCADA

l Label Name: Plate_Blue

l Expression: 0x80AAD5 (or 8432341)
Once you have defined your label, you can create fonts to use in your project for alarm
categories, Cicode functions, and button objects. For example, use the Fonts dialog box to
define a font with the following properties:
l Font Name: Plate_Font
l Font Type: Arial
l Pixel Size: 12
l Foreground Color: Plate_Blue
For more information, refer to Knowledge base article Q4024.
See Also
Using System Fonts

Using Alarm Properties as Tags

Alarm properties can be used wherever variable tags can be used (except in alarm
descriptions). For instance, you can provide the operator with a visual indication when
the alarm CV110_ERROR is active. When it is active, CV110_ERROR.On will be
TRUE; when it is inactive, CV110_ERROR.On will be FALSE. For example, CV110_
ERROR.On could be entered as the fill color expression in a graphics object. When the
conveyor becomes inoperative, the graphics object will change color.
To use an alarm property as a tag, it needs to be formatted as follows: Alarm tag (for
example CV100_STOP) followed by a full stop (.) then the property (for example Cat-
egory). The completed alarm property would then be CV100_STOP.Category.

Note: If you intend to use time-stamped digital or time-stamped analog alarm prop-
erties as variable tags, you will want to verify that they are configured correctly with
the necessary data being pushed to the relevant variables via the Cicode function
AlarmNotifyVarChange.

See Time-stamped Digital Alarms and Time-stamped Analog Alarms for more details on
how these alarms operate.
Changes in Alarm Reference Syntax

In versions prior to 7.10 you could refer to an alarm's properties by dot notation ex.
“Alarm1.On”. Such references could appear in both Cicode and on graphic pages and
enabled you to see and control alarm states.

776
Chapter 23: Using Alarms in SCADA

In CitectSCADA 7.20 an alarm’s properties carries not only value, as in 7.10, but also
items similar to Tag Extensions items for example. “Alarm1.On.T”. The alarm reference
syntax is now:
[Cluster.]Alarm.AlarmProperty[.Item]where

Cluster The optional cluster name.

Alarm The alarm name.

AlarmProperty The alarm property name. This part of the reference is not optional as it is
for tags. There are different available properties for different categories of
alarms as in 7.10.

Item The optional Item name. If the item name is not specified, the value of the
alarm property is referenced. Available items are the same as for tags:
Value referenced by “V”, Value Timestamp “VT”, Quality “Q”, Quality Times-
tamp “QT” and overall Timestamp “T”.

See Also
Supported alarm properties
Writing to alarm properties
Setting up alarms
Tag Extensions

Supported alarm properties

The following properties can be used for every alarm type. Remember, the return value
relates to the description. For example, for a digital, if 1 is returned, that means the
description is TRUE, whereas 0 (zero) means it is FALSE.

Property Description Ret-

urn
Typ-
e

.On* Alarm active Dig-

ital

.Ack Alarm acknowledged Dig-

ital

.Category Alarm category Integer

.ComBreak For Multi-Digital alarms, the property is set to 1 if the device cannot Digital
read data from the underlying tag at start-up for a time greater
than [Alarm]ArgyleTagValueTimeout value. The property is set to 0
and re-alarms the corresponding alarm, when the alarm server
receives valid data from the device.

777
Chapter 23: Using Alarms in SCADA

For every Disabled and Display Disabled alarms (except Time

Stamped Digital and Time Stamped Analog alarms) the property is
set to 1, when they are being Enabled. The property is set to 0 and
re-alarms the corresponding alarm, when the alarm server
receives valid data from the device.

.Custom1 Custom Field. Stri-

.Custom2 ng
.Custom3 (64
.Custom4 byte-
.Custom5 s)
.Custom6
.Custom7
.Custom8

.Disabled Alarm disabled (see note below) Dig-

ital

.Millisec The milliseconds part of the time the alarm was triggered Long

.Name Alarm name

Stri-
ng
(80
byte-
s)

.Paging Alarm paged Bool-

ean

.Pa- Paging group alarm belongs to. Stri-

gingGroup ng
(80
byte-
s)

.Priority Alarm priority

Inte-
ger

.State Alarm's state value. An alarm state value is a combination of Short

state enumeration and action bit masks described below:

State enumerations

Alarm OFF state or state 000 for

0
Multi-Digital alarm

Alarm ON state or state 00A for

1
Multi-Digital alarm

778
Chapter 23: Using Alarms in SCADA

state 0B0 for Multi-Digital alarm 2

State 0BA for Multi-Digital alarm 3

State C00 for Multi-Digital alarm 4

State C0A for Multi-Digital alarm 5

State CB0 for Multi-Digital alarm 6

State CBA for Multi-Digital alarm 7

Analogue deviation from set point

8
High

Analogue deviation from set point

9
low

Analogue rate of change alarm

10
state

Analogue low limit alarm state 11

Analogue high limit alarm state 12

Analogue low low limit alarm state 13

Analogue High High limit alarm

14
state

Alarm action masks

Unable to get the status of

32
underlying tag at start-up

Alarm cleared bit mask 64

Alarm acknowledged but held 128

Alarm unacknowledged bit

256
mask

Alarm disabled bit mask 512

Argyle type alarm bit mask 1024

Argyle type alarm ON bit mask 2048

Analogue alarm threshold

4096
value changed

User generated event 8192

779
Chapter 23: Using Alarms in SCADA

Event already logged 16384

Disable the alarm display 32768

For Example: A digital alarm called "AlmDigital1" that is ON and

unacknowledged, the value of the state property will be: Alm-
Digital1.State = 1 (ON state) + 256 (Unacknowledged alarm) =
257

.Tag Alarm tag String

(80
bytes)

.Time 32-bit value of the time the alarm was triggered Long

* The .On property for Analog alarms is true if any alarms associated with the alarm tag
are active.

Note: Once an alarm is disabled, it cannot be re-enabled unless you use the function
AlarmEnable() or AlarmEnableRec()

For digital alarms, time-stamped digital alarms, and advanced alarms, the following
properties can also be used:

Property Description Return Type

.Desc Alarm description String (128 bytes)

.Delay Alarm delay Long

Note: Desc exists for every alarm type but will not return meaningful data for analog
or time-stamped analog alarms. Desc returns an empty string that indicates whether
the read succeeded; the write indicates that the tag was resolved and that the write
request was sent.

For analog alarms and time-stamped analog alarms, the following properties can also be
used:

Property Description Return Type

.DevDelay Deviation delay Long

.DeadBand Deadband Real

780
Chapter 23: Using Alarms in SCADA

.Deviation Deviation Real

.HighHigh High High Real

.High High Real

.LowLow Low Low Real

.Low Low Real

.HHDelay High High delay Long

.HDelay High delay Long

.LDelay Low delay Long

.LLDelay Low Low delay Long

.Rate Rate Real

.Setpoint Setpoint Real

.Value Alarm tag Value Real

For the digital properties below, only one can be true at any point in time for each alarm.
They are arranged in order of priority, from lowest to highest.

.DVL Deviation alarm triggered (Low) Digital

.DVH Deviation alarm triggered (High) Digital

.R Rate of Change alarm triggered Digital

.L Low alarm triggered Digital

.H High alarm triggered Digital

.LL Low Low alarm triggered Digital

.HH High High alarm triggered Digital

Note: DVL and DVH are only evaluated if Deviation > 0. R is only evaluated if Rate

781
Chapter 23: Using Alarms in SCADA

> 0.

Some alarm properties return configuration data. If the user has not defined this infor-
mation, the following defaults are provided:

Property Default

.Setpoint 0

.HighHigh 3.4e+38

.High 3.4e+38

.LowLow -3.4e+38

.Low -3.4e+38

.Rate 0

.Deviation 0

.Deadband 0

.Category 0

.Priority 0

See Also
Writing to alarm properties
Setting up alarms

Writing to alarm properties

If you have the necessary access rights, you can write to the following alarm properties.
(Remember, the value you write to the property relates to the description. For example, if
you set a digital alarm property to 1, you are making the description TRUE. If you set it
to 0 (zero), you are making it FALSE.)

Property Description Input

Type

.Ack Alarm acknowledged (once acknowledged cannot be "unac- Digital

782
Chapter 23: Using Alarms in SCADA

knowledged")

.Deadband Alarm Deadband Real

.Deviation Deviation from setpoint Real

.Disabled Alarm disabled Digital

.HighHigh High High Real

.High High Real

.LowLow Low Low Real

.Low Low Real

.HHDelay High High delay Long

.HDelay High delay Long

.LDelay Low delay Long

.LLDelay Low Low delay Long

.DevDelay Deviation delay Long

.Custom1 Custom field String

.Custom2
.Custom3
.Custom4
.Custom5
.Custom6
.Custom7
.Custom8

.Paging Alarm paged Boolean

.Pa- Paging group alarm belongs to. String

gingGroup

Analog alarm thresholds can also be changed using the AlarmSetThreshold() function.
Note the following:
l The alarm tag needs to be unique.
l The alarms databases in included projects on the alarms server and the Control
Client computer needs to be identical.

783
Chapter 23: Using Alarms in SCADA

See Also
Supported alarm properties
Setting up alarms

Setting up alarm properties

To use alarm properties, you need to enable them on the Alarm Server.
1. In the Project Editor, choose Servers | Alarm Servers.
2. Press F2 to display the extended form.
3. Specify the port that the Alarm Server will listen on.

Note: You are not required to specify the port if using the default settings for ports.

See Also
Alarm Server Definitions
Supported alarm properties
Writing to alarm properties

Handling Alarms at Runtime

Once you have configured your alarms you then need to create alarm pages so operators
can view and acknowledge alarms within your system. Using a tab style template or con-
figuring a standard graphics page you can create the following alarm pages:

Alarm-
Description
Page

Active When an alarm is triggered, it becomes active and is displayed on the Active
Alarm page. The active state of a digital alarm is ON, while the active state of
an analog alarm varies, depending on the type of alarm (for instance HIGH,
LOW , RATE, and so on).

To acknowledge an alarm, an operator either selects the alarm with the mouse
and clicks the left mouse button, or moves the cursor onto the alarm and
presses the Enter key. Alternatively, the operator can acknowledge every alarm
on page by clicking Alarm Ack.
When an alarm is acknowledged, its display color changes, and its state
changes to ACKNOWLEDGED. When the alarm is reset (when the conditions
that caused the alarm have been rectified), its state changes to OFF. When the
state changes to OFF the Alarm is no longer displayed and is available from the
Disabled Alarm page. You can then view state changes (events) for that alarm
using either the Alarm SOE page.

Disabled If an alarm does not appear to be operating as designed, or is deemed unnec-

essary, an operator can disable it. Disabled alarms are ignored until they are

784
Chapter 23: Using Alarms in SCADA

Alarm-
Description
Page

re-enabled.
(You need to define a command that uses the AlarmDisable() function to dis-
able alarms.)

SOE To maintain a history of alarm activity, an event log is kept. This log stores the
time when each alarm was activated, acknowledged, and reset. You can display
alarms from the event log (including disabled alarms) on the sequence of
events and alarm summary page. The soe page displays actions taken on an
alarm, and user events such as login. You can also add comments to existing
events, and insert new events into the event journal. Manually refresh the page
to view the latest events.
Note:In v7.40 CitectSCADA alarm login system requires two levels of login:
- Login to the Client system supported by the “Login successful” prompt-mes-
sage
- Login to the Alarm DB Server visible via SOE events.
Successful Alarm DB login events are viewable via the SOE page. The login
events can be filtered and sorted by date-time and other filter criteria, with the
specific login event identified by the “Logged on” entry in the Message column
and the corresponding login name in the “User Name” column.
Unsuccessful DB login/connection events though not triggering new SOE
entries, may generate “DB not connected” Hardware alarms.

Summary The Alarm Summary page displays ON/OFF Alarms, acknowledged and unac-
knowledged states. Manually refresh the summary page to view the latest
events before analyzing the data.

Hardware Displays details of any system errors that are unacknowledged, or acknowl-
edged and still in alarm state.

To display an alarm page at runtime:

1. Create an alarm (or hardware alarm) page in your project if you have not already
done so. Call the page Alarm for a configurable alarm page, and Hardware for a
hardware alarm page.
2. Create a new keyboard command or a button, to call the page at runtime. You can
also add a touch command to an existing screen object.
3. In the command field, enter PageAlarm() to display the configurable alarms page, or
PageHardware() to display the hardware alarms page.
4. Configure other properties as necessary.
5. Click Add to append a new record, or Replace to modify an existing record.

Note: If using the standard page templates, you don't usually need to create a com-
mand to display the page: the commands are already built in.

785
Chapter 23: Using Alarms in SCADA

To display a customized alarm page (with a non-standard name), use the PageDisplay()
function to display the page, followed by the AlarmSetInfo() function as necessary.
See Also
Adding a comment to the Alarm SOE page
Adding events into the event journal

Working in the Alarm Display List

As an operator you can interact with the Alarm display list. You can change the sort
order, add and hide columns, comment on alarms and events, acknowledge alarms, and
Disable, or enable alarms. Options may vary according to the template used to create the
page (if the template includes the Equipment tree-view) and the type of alarm page the
operator is viewing.
Operators can do the following:
l Sort alarms
l Filter the alarm display using the equipment tree-view or alarm filter form
l Add and hide columns
Refer to the topics Interactive Alarm List (equipment tree-view), Interactive Alarm List
(no tree-view), and the help belonging to the Example project for more information.
As an operator you can also comment on events.

Adding a comment to the Alarm SOE page

In v7.40 you can add a comment on an event listed on the Sequence of events page.

Note: You cannot modify or delete an existing comment for an event. You can only
add a comment.

To add a comment to the SOE page:

1. Right-click on the relevant event and select comment
2. Enter your message in the comment field
3. Click OK
Manually refresh the Alarm display list to view the message. The message is displayed
using the Ack/Off font under the event in ascending order.
When you add a message to a ‘raised’ event for an alarm on the SOE page the message
will be displayed in the comment field on the alarm summary page for the alarm. Only
those messages added to ‘raised ‘events will be displayed on the alarm summary page.
Cleared, Acknowledged or any other event comments will not be displayed.

786
Chapter 23: Using Alarms in SCADA

You can also add comments to an event on the SOE page using the AlarmComment ()
Cicode function. To add a message to the relevant event you can include the ‘AN’ as an
additional parameter in the function. For example:

AlarmComment (“Temperature discrepancies”, 21)

To successfully add a comment to an event on the SOE page the following rules need to
be met:
1. The event is not of "Comment" classification.
2. A user should be logged on the client process.
3. If the event is associated with an alarm tag, the logged on user needs to have suf-
ficient privilege to that alarm configured in the database.
4. If the event is not automatically generated by the system (i.e. reflected by its user
name of "System"), the logged on user needs to match to the user name of the event.
5. If the event is automatically generated by the system, the logged on user needs to
have full privilege (i.e. privilege from 1 to 8).

Adding a new event to the Alarm SOE page

In v7.40 you can add a new event to the event journal via the SOE page. If the new
event is not associated with an alarm tag it will be classified as a user event.
To add a new event the current logged on user needs to have complete privilege (i.e.
privilege from 1 to 8).

Note:To view all columns on the page go to the Action Tab and click on the Auto
Size icon.

To add a new event to the event journal via the SOE page:
1. Select the relevant event from the display list. Right-click and select the option Add
event.
2. Enter your message in the message field. The associated alarm tag (if relevant to the
selected event) should be displayed in the message dialog title bar e.g. Message
[Alarm_6]. If no associated alarm tag then the title bar will display the following:
Message[].
3. Click OK.
Manually refresh the SOE page to view the new event. The event is displayed with the
timestamp, cluster, associated tag (if relevant) and type of 'Action'.

787
Chapter 23: Using Alarms in SCADA

You can also add events to the event journal page using the SOEEventAdd () Cicode
function.

Troubleshooting Alarms

l Firewall settings and CitectSCADA

SOE page displays old events with recent events not shown
If only old events are listed on your SOE page possible causes may include the fol-
lowing:
l The SOE page is not automatically refreshed. Manually refresh the page to update the
list. If this is not the case then potentially the system have trouble to manage the
request.
Possible solutions include:
l Check there is no filter applied to the current SOE display which results in only old
records being displayed
l Using the Alarm filter form decrease the requested LocalTimeDate range.
l Increase system capabilities to treat large number of events
l Increase the alarm server cache size. Refer to the param-
eterAlarm.<ClusterName>.<ServerName>CacheSize for more information
l Increase the maximum number of records returned by a single request. Refer to
the parameter Alarm.<ClusterName>.<ServerName>QueryRowLimit for more
information.
l Increase the request time-outs. Refer to the parameter Alarm.<Cl-
usterName>.<ServerName>ClientRequestTimeout for more information
INI file example:

[alarm]
CacheSize = 80
QueryRowLimit = 1000000
ClientRequestTimeout = 300000

SOE page is empty

If no events are listed on your SOE page possible causes may include the following:

788
Chapter 23: Using Alarms in SCADA

l The system is not able to get events or there is no event in the system.
l The issue can occur for example when (not exhaustive)
l The alarm server is busy and can't answer the request in the given time
l The client display is not connected to the alarm server
l The client user do not have the privileges to see the existing events
Possible solutions include:
l Checking the hardware alarms so that your client is connected to the alarm server (if
not an error message will be displayed)
l Check you did not deactivate the cluster for this client: see [Client]Cluster parameter
for more information).
l Check you are logged in with the right level of privileges
l Check there is no filter applied to the current SOE display which results in an empty
recordset
l Increase the request time-out for all alarm servers (see [Alarm]ClientRequestTimeout
for more information)
l Decrease the requested range by using the filter capability. (Request events for the last
hour for example, or for a particular tag etc)

Archiving the Event Journal

In CitectSCADA v7.40 you can now archive event journal data on a variety of devices,
including:

789
Chapter 23: Using Alarms in SCADA

l Removable hard disks

l Removable flash technology, e.g. Compact Flash
l CD-R and CD-RW devices
l DVD devices such as DVD-R, DVD-RAM etc.
You can access the event journal via the Alarm SOE page.
To archive the event journal you need to configure the following parameters, Archi-
veAfter, KeepOnlineFor, and ArchivePath. The ArchivePrefix parameter is optional.
Once configured you can manually trigger archiving to occur using Cicode or set up a
repeated archiving task using the Alarm Server Properties form.
Archiving will run on the server which has write access to the database. If a redundant
server is configured, archiving should be enabled on both servers.

Note: For archiving to a volume to take place, the volume should be in the defined
path and accessible (CitectSCADA should be able to write to the volume). When the
volume is in place, CitectSCADA will mount the volume automatically (if required),
prior to writing the data.

See Also
Understanding the archiving parameters

Understanding the archiving parameters

In CitectSCADA v7.40 you can now archive event journal data using the following
parameters:

Parameter Description

ArchiveAfter Works in conjunction with the parameter KeepOnlineFor. Defined in number

of weeks, the default value is 4 weeks. All data that is older than the period
set is marked for archiving. The value should be smaller than the number of
weeks defined for KeepOnlineFor. If not smaller an “Out of Range” hardware
alarm will be raised. Once the data is eligible for archiving, (by default after
4 weeks), and until KeepOnlineFor is active the data will remain in the data-
base but is read only. Set this parameter using the Citect.ini file.

KeepOnlineFor For archiving defines how long the data is viewable on the SOE Page. Default
value is 6 weeks. After this time the data will be deleted. To view the archive
data it will need to be ‘mounted’.Set this parameter using the Citect.ini file.

ArchivePath Where the archive data will be stored. Should be accessible from the alarm
server which executes the archiving operation. For example C:\Data.
Note:The media where the archived file is to be saved should be labeled. If
not labeled archiving will be unsuccessful and a message will display on the
SOE page.

790
Chapter 23: Using Alarms in SCADA

Parameter Description

Set this parameter in the Alarm Server Definitions form.

ArchivePrefix Optional prefix to the archive folder. Combined with the ArchivePath and
timestamp (YYYYMMDD) when archiving was triggered. The archiving action
creates sub folders under archive volume’s folder. For example, if Archive-
Path=C:\Data and ArchivePrefix=Archive and an archiving happened on 21
January 2012, archive volume path is C:\Data\Archive20120121. If there is
any data which is eligible for archiving, “EventJournal” folder will be created
under archive volume’s directory and the archived data will be flushed to
that folder.The folder name would then be C:\Data-
\Archive20120121\EventJournal\ <H*.mwj>
Set this parameter in the Alarm Server Definitions form.

Modify the default settings for ArchiveAfter and KeepOnlineFor, and set the ‘Archive-
Path’ and ‘ArchivePrefix’ before scheduling or manually triggering archiving to occur.
To archive Event Journal data you can:
1. Manually trigger archiving using SOE Cicode functions
2. Set automatic archiving using the Alarm Server Definitions form
3. Use Scheduler to trigger archiving

Manually archiving using SOE Cicode functions

Using Cicode you can trigger archiving to occur, and mount (to view archived data) or
dismount the archive volume.

Note: You need to be logged in as a user, to trigger archiving, and to mount or dis-
mount an archive volume using cicode.

To trigger archiving:
Set function SOEArchive(). Archiving will start, using the values defined in the Archi-
veAfter and KeepOnlineFor parameters.

Note: To avoid data from becoming inaccessible, run the operation every ”Kee-
pOnlineFor” weeks or within the ArchiveAfter and KeepOnlineFor period. For exam-
ple, if ArchiveAfter is 1 week and KeepOnlineFor is 2 weeks manually trigger
archiving after 8 days, so that all data is archived.

791
Chapter 23: Using Alarms in SCADA

Once executed check the location set in the ArchivePath/ArchivePrefix to see files. The
directory may hold multiple files.

Note: Archived data cannot be archived again.

To view archived data:

Archived data that is no longer available online for viewing can be viewed by setting
the SOEMount(STRING Path) function.
In mounting the volume, you are directing the server to where the archived data is
stored. You are not restoring the data, merely making the data available for viewing via
the SOE page. To view the data on the mounted volume you need to query the data
using the filter options available on the SOE page. To view data, including data on the
mounted volume, use 'page down' to query the data and bring it into the SOE page.
For mounting a volume, you should pass the volume path, which is “C:\Data-
\Archive20120121” rather than “C:\Data\Archive20120121\EventJournal”, when call-
ing SOEMount() cicode function. If you need to copy or move archived data to another
directory, for example, from “C:\Data\Archive20120121” to “D:\Data”, you will need to
copy or move the entire “EventJournal” folder to the new directory. You can then invoke
SOEMount(“D:\Data”) to restore the data from the new location.
If you no longer need to view the data on the mounted volume, SOEDismount() should
be called.

792
Chapter 23: Using Alarms in SCADA

Note: To call SOEMount() or SOEDismount(), user has to log in as a role who has
full privilege (privilege 1..8).

See Also

Automatic archiving using the Alarm Server Definitions Form

Automatic archiving can be scheduled on every alarm server using the Alarm Server
Definitions form.
Complete the field “Archive every” (available on extended form only) to schedule archiv-
ing every certain number of days.For example, every 8 days.
Complete the fields Archive Path and Archive Prefix so the data can be stored.

Note: In order to archiving succeed, at least “KeepOnlineFor”, “ArchiveAfter” param-

eters need to be set.

Automatic archiving occurs immediately after the alarm server has started and then
ever number of days specified in the Archive every field.

Using Scheduler to trigger archiving

Using Scheduler you can trigger archiving to occur. However the steps needed to com-
plete this task vary whether the system you are running is in single process or multi-
process mode.
When in multi-process mode, for archiving to be triggered successfully, scheduler needs
to invoke a custom Cicode function that includes the following:
Login (Username, Password);
SOEArchive()

Following the instructions outlined in "Configuring Equipment for Inclusion in Sched-

uler" define new Equipment. The Equipment name can be any name specified by the
user. E.g. Archive
Following the instructions outlined in Equipment State Properties define the 'Trigger'
and 'OFF' states for the newly added equipment.
To trigger archiving in Single Process Mode:

Note: For archiving to succeed in single process mode you need to login to the
SCADA client in Runtime.

793
Chapter 23: Using Alarms in SCADA

1. Open the 'Trigger' Equipment State form.

2. In the Entry Action field enter the function SOEArchive(). Click OK to save.
3. At runtime Login to the client.
4. Open Scheduler. The Archive Equipment branch should be displayed in the equip-
ment hierarchy.
5. Following the instructions outlined in Adding a new Schedule entry schedule the
state 'trigger' to occur.
When the time transitions for this scheduled task, SOEArchive() will be called and
archiving will be triggered.
To trigger archiving in Multi Process Mode:
1. In the Cicode Editor create a custom Cicode function and save it. This Cicode func-
tion needs to include Login information. For example:

FUNCTION
ArchiveMyData()
Login("Engineer","citect");
SOEArchive();
END

2. Open the 'Trigger' Equipment State form.

3. In the Entry Action field enter the name of the custom Cicode function. e.g.-
ArchiveMyData(). Click OK to save.
4. Open Scheduler. The Archive Equipment branch should be displayed in the equip-
ment hierarchy.
5. Following the instructions outlined in Adding a new Schedule entry schedule the
state 'trigger' to occur.
See Also
Manually trigger archiving using SOE Cicode functions
Set automatic archiving using the Alarm Server Definitions form

794
Chapter 24: Using an OPC AE Server

OPC (OLE for Process Control) communicates information from a data source such as a
server to any client third party application in a standard way without requiring the
application to have specific knowledge about the data source. The OPC Alarms and
Events specification is similar to the original OPC Data Access specification, only the
Alarms and Events specification addresses real-time alarm and event data instead of
real-time process control data.
The third party client application that is interested in an alarm subscription to the server
needs to link to the server. When the client registers a link to the server, the server loads
into memory and starts executing on the PC.
See the topic Using a Third Party OPC Client to access Alarm Server Data for con-
figuration details.
See also
Computer Setup Wizard - General Options Setup

Using a Third Party OPC Client to access Alarm Server Data

You can use a third party OPC client application, such as Matrikon, to access your sys-
tem and view alarm server data. To register your alarm server (in your OS) you need to
have administrative privileges.
To allow the third party application access:
1. Select the project and run the Computer Setup Wizard.
2. On the General Options setup dialog select 'Register' . The Alarm server for that
project is then registered and available for access via the third party application.
3. Run the third party application. From the list of available servers select
Serck.ScxV6OPCAE.<AlarmServerName>.<IP address from network address form>
4. Connect to the Server and depending on your third party application Create Event
Subscription
All events will be listed.

Note: The field names returned will vary to those field names available on the
sequence of events page.

795
Chapter 24: Using an OPC AE Server

See Also
Computer Setup Wizard - General Options Setup

796
Chapter 25: Configuring Events
You can use an event to trigger an action, such as a command or set of commands. For
example, an operator can be notified when a process is complete, or a series of instruc-
tions can be executed when a process reaches a certain stage.
Events needs to be enabled for events to run. Use the Computer Setup Wizard (Custom
setup) to enable Events. If using a network, you can process events on any computer (or
every computer).

Note: The Events system is not redundant. That is, it is not possible to assign pri-
mary and standby Events Servers. If you require a redundant event reporting system,
use reports instead. See Reporting Information.

To define an event:

1. Choose System | Events. The Events dialog box appears.

2. Enter the event properties.
3. Click Add to append a new record, or Replace to modify an existing record

Note: The Events Server needs to be enabled for events to work.

See Also
Events Properties
Running Events

Events Properties
Events have the following properties:
Name
For a single computer system, specify GLOBAL for the event name:

Name GLOBAL

797
Chapter 25: Configuring Events

If you are using a network and want to run an event on every computer, specify
GLOBAL for the event name. If you want to run an event only on specific computers,
specify an event name and use the Computer Setup Wizard (Custom setup) to specify
which computer(s) will run the event. The event name does not have to be unique: you
can specify many events with the same name.
Enter a value of 16 characters max.

Note: Make event names agree with the Tag name syntax. The use of any other char-
acters such as spaces will result in a compiler error. Instead of a space, use an under-
score character (_).

Cluster Name
The default cluster to be used when the event action and event trigger Cicode is run.
Any tags in these Cicode expressions will resolve to this default cluster if they don't
have their cluster specified inside the expression. This field can be left blank in single
cluster systems or if every tag inside the expressions are declared in the
<ClusterName>.<TagName> format.
Time
The time of day to synchronize the Period in hh:mm:ss (hours:minutes:seconds). If you
do not specify a time, Period is synchronized at 00:00:00 (that is, midnight). Enter a
value of 32 characters maximum.
Period
The period to check for the event, in hh:mm:ss (hours:minutes:seconds). Enter a value of
32 characters maximum. Alternatively you can specify:
l A weekly period by entering the day of the week to check for the event, for example,
Monday, Tuesday, Wednesday, etc.
l A monthly period by entering the day of the month to check for the event, for exam-
ple, 1st, 2nd, 3rd, 4th, 5th, etc.
l A yearly period by entering the day and the month to check for the event, for exam-
ple, 1st January, 25th February, and so on. The day and month needs to be separated
by a space.
If you do not specify a period or time, the period defaults to one second. If you do not
specify a period, but do specify the time, the period defaults to one day.
Trigger
The Cicode expression (or Variable tag) which is used to determine whether the event
Action is executed. This expression is checked every one second. Enter a value of 254
characters maximum.
Action

798
Chapter 25: Configuring Events

The commands to execute. Enter a value of 64 characters maximum.These commands

will execute in the following circumstances:
l When the specified Time and Period occurs, and the Trigger condition is TRUE or
blank.
l When the Trigger becomes TRUE, and the Time and Period field are blank. The
Trigger needs to become FALSE and TRUE again for the action to re-execute.
Comment
Any useful comment. Enter a value of 48 characters maximum.

Running Events
The Event Server needs to be enabled for events to work. You can run an event auto-
matically:
l At a specified time and period.
l When a trigger condition becomes TRUE.
l When a trigger condition is TRUE at a specified time and period.
See Also
Specifying times and periods
Using triggers

Specifying times and periods

The Period determines when the event is run. You can specify the period in hh:mm:ss
(hours:minutes:seconds), for example:

Period Comment

1:00:00 Run the event every hour

6:00:00 Run the event every six hours

72:00:00 Run the event every three days

Monday Run the event each Monday

15th Run the event on the 15th of each month

25th June Run the event on the 25th of June

You can also specify the time of day to synchronize the event, for example:

799
Chapter 25: Configuring Events

Period Comment

6:00:00 Synchronize the event at 6:00 am

12:00:00 Synchronize the event at 12:00 midday

The Time synchronizes the time of day to run the event and, with the Period, determines
when the event is run; for example:

Time 6:00:00

Period 1:00:00

In this example, the event is run every hour, on the hour. If you start your runtime sys-
tem at 7:25am, your event is run at 8:00am, and then every hour after that.
See Also
Using triggers

Using triggers
You can use any Cicode expression (or variable tag) as a trigger for an event. If the result
of the expression (in the Trigger field) becomes TRUE, and if the Time and Period fields
are blank, the event is run. For example:

Time

Period

Trigger RCC1_SPEED<10 AND RCC1_MC

This event is only run when the expression (Trigger) becomes TRUE, that is, when the
digital tag RCC1_MC is ON and the analog tag RCC1_SPEED is less than 10. The expres-
sion needs to become FALSE and then TRUE again before the event is run again.
If you use the Time and/or Period fields, the Trigger is checked at the Time and/or Period
specified, for example:

Time 6:00:00

Period 1:00:00

Trigger RCC1_SPEED<10 AND RCC1_MC

800
Chapter 25: Configuring Events

This event is run each hour, but only if the expression (Trigger) is TRUE (that is, if the
digital tag RCC1_MC is ON and the analog tag RCC1_SPEED is less than 10).
See Also
Running Events

801
Chapter 25: Configuring Events

802
Chapter 26: Using Accumulators
Accumulators track incremental runtime data, such as motor run hours, power con-
sumption, and downtime. You set a trigger (for example, motor on) to increment three
counters:
l The number of times the accumulator is triggered (for example the number of starts
for the motor).
l The run time, in steps of 1 second.
l A totalized value, by an increment you define (for example the current).
The accumulated data is stored as variable tags in an I/O Device. Variable tags are read
at startup and updated regularly while the trigger is active. You can monitor and dis-
play accumulated data by animating, trending, or logging the variable tags.

Note: You can control (re-read or reset) any accumulator at runtime by using the
AccControl() Cicode function.

To configure an accumulator:

1. Choose System | Accumulators. The Accumulators dialog box appears.

2. Enter the accumulator properties.
3. Click Add to append a new record, or Replace to modify an existing record.
You use the Accumulator Properties dialog box to configure your accumulators.
See Also
Accumulator Properties

Accumulator Properties
Accumulators have the following properties:
Name
The name of the accumulator. Enter a value of 79 characters or less.
Cluster Name
The name of the cluster that this accumulator runs on. If the Cluster Name is not set,
then this accumulator will run on each defined cluster.
Trigger

803
Chapter 26: Using Accumulators

The Cicode expression (or variable tag) to trigger the accumulator. If the result of the
expression (in this field) is TRUE, accumulation starts. If the result of the expression (in
this field) becomes FALSE, accumulation stops. Enter a value of 254 characters or less.
The frequency with which the trigger is checked is controlled by the [Accumulator]Watch-
Time parameter.
Run Time
The variable (tag) that contains the run time (in seconds). Enter a value of 254 characters
or less. On startup, this value is read. Then the local copy of this variable is incremented
(while Trigger is TRUE) and the variable is written back to the I/O Device at a frequency
determined by the [Accumulator]UpdateTime parameter.
No. of Starts
The variable (tag) that contains the number of starts (that is, the number of times the
trigger changes from FALSE to TRUE). Enter a value of 254 characters or less. On
startup, this value is read. Then the local copy of this variable is incremented and the
variable is written back to the I/O Device at a frequency determined by the [Accumu-
lator]UpdateTime parameter.
Totalizer Inc
Any Cicode expression (or variable tag) to add to (increment) the Totalizer variable
while the Trigger condition is TRUE. Enter a value of 254 characters or less.
Totalizer
The variable (tag) that contains the totalized value. Enter a value of 254 characters or
less.
On startup, this value is read. Each time the trigger is checked and while the trigger is
TRUE, the value in the Totalizer Inc field is added to the local copy of this Totalizer var-
iable. The new Totalizer variable is written back to the I/O Device at a frequency deter-
mined by the [Accumulator]UpdateTime parameter.
For example, if you configure an accumulator for a motor, and Totalizer Inc is the cur-
rent (amperage) used by the motor, then Run Time will contain the time (in seconds)
that the motor has run, No. of Starts will contain the number of times the motor was
started, and Totalizer will contain the total current used by the motor. The average cur-
rent used by the motor is Totalizer/Run Time.
Comment
Any useful comment. Enter a value of 48 characters or less.
Equipment

804
Chapter 26: Using Accumulators

Name of the equipment associated with the Accumulator. Select or enter a name of 254
characters or less. You can optionally prefix a cluster name to the equipment name in
order to restrict the reference to a piece of equipment in only one cluster. The cluster
should be configured otherwise the compile will not be successful. Use this method as
an alternative to referencing a cluster in the equipment properties dialog if the equip-
ment is defined for all clusters.

Extended forms fields

The following fields are implemented with extended forms (press F2).
Privilege
The privilege needed by an operator to perform operations on the accumulator (by using
accumulator functions). Enter a value of 16 characters or less.
Area
The area to which the accumulator belongs. Only users with access to this area (and any
required privileges) will be able to perform operations on the accumulator. For example,
if you enter Area 1 here, operators need to have access to Area 1 (plus any required priv-
ileges) to perform operations on the accumulator. Enter a value of 16 characters or less.
Notes:
l The run time, number of starts, and totalized value are stored in variables in your I/O
Device. This allows easy access to these variables and, because they are saved in the
I/O Device, their values are saved if the project is shutdown. You can increase system
performance by storing these variables in a Disk I/O Device. (If you store these var-
iables in your external I/O Devices, communications bandwidth will be consumed
updating the variables.
l If using a network, you can use a redundant Disk I/O Device to secure these var-
iables.
l The accumulator server runs as part of the Reports Server. If you have a redundant
Reports Server, you need to use a primary/standby configuration to stop the accumu-
lators running on both Reports Servers. Use the Computer Setup Wizard to define the
Reports Servers.
l You can control (re-read or reset) any accumulator at runtime by using the AccControl
() Cicode function.

805
Chapter 26: Using Accumulators

806
Chapter 27: Logging and Trending Data
Since CitectSCADA version 6.0, the Process Analyst (an built-in trend visualization tool)
has superseded the functionality of trend graphs. However, trend graphs are still sup-
ported. Be aware that to use SPC trends, use trend graphs, since SPC is not supported by
the Process Analyst.
For details, see the Process Analyst Help.
See Also
Trending Data
Trend Graphs
Printing Trend Data
Exporting Trend Data
Using Trend History Files
Using Path Substitution
Debugging Trending

Trending Data
The trend system can help you better understand your plant and equipment's per-
formance. Trending can be used for dynamic visual analysis (trend and SPC graphs),
production records, or for regularly recording the status of equipment for efficiency and
preventive maintenance.
Using trend tags, you can specify the data you want to collect from your I/O Device var-
iables. This information can be logged at regular intervals (periodic trend), or only when
an event occurs (event trend). Event trends are used for trending data that is not time-
based, for example, for a product as it comes off an assembly line. Trend data is usually
saved on disk for analysis or displayed on a trend graph.
The trend system is based on real-time samples. The trend system expects a return of
one data point each time it samples the data. Although gaps in the data can be filled,
you will want to verify that your field device can return data values at the rate you spec-
ify (especially if you are using sample periods of less than 100 ms).
Any amount of data can be collected and stored. The only restriction on the amount of
data that you can store is the size of the hard disk on your computer (an efficient data
storage method is used to optimize the use of storage space on your computer's hard
disk). For long term storage, you can archive the data to disk or tape (without disrupting
your runtime system).

807
Chapter 27: Logging and Trending Data

Note: If you are trending data across a network (distributed processing), it is rec-
ommended that you enable time synchronization using the Time Synchronization
configuration application. This verifies that every trend is synchronized to the same
time.

You might also consider staggering your trend sample requests using the [Trend]Stag-
gerRequestSubgroups parameter.
See Also
Configuring trend tags

Configuring trend tags

You use the Trend Tags dialog box to configure your trend tags.
To configure a trend tag:

1. Choose Tags | Trend Tags. The Trend Tags dialog box appears. (Press F2 to view the
extended Trend Tag form.)
2. Enter your trend tag properties.
3. Click Add to append a new record, or Replace to modify an existing record.
See Also
Trend Tag Properties

Trend Tag Properties

Note: When modifying a trend tag, be aware that if the tag was created using the
equipment editor - equipment type workspace, the fields configured will be grayed
out in the tag properties form.

Equipment
The name of the equipment associated with the Trend Tag. Select or enter a name of 254
characters or less. You can optionally prefix a cluster name to the equipment name in
order to restrict the reference to a piece of equipment in only one cluster. The cluster
should be configured otherwise the compile will not be successful. Use this method as
an alternative to referencing a cluster in the equipment properties dialog if the equip-
ment is defined for all clusters.
Item Name

808
Chapter 27: Logging and Trending Data

Enter a meaningful name for Tag Item. Used as part of the equipment hierarchy a mean-
ingful name will help with future migration of your system and the step towards an
object oriented model.
This field is optional. If not configured, the last 63 characters of the “Trend Tag” field
will be used for the Tag Item name. The Trend Tag allows 79 characters, while Tag Item
has a maximum of 63 characters. A compiler alert message may be generated if the
'Equipment.TagItem' name is not unique.
There is a limit of 254 characters on the combination of Equipment and Tag Items, plus
the period '.', for example “Equipment.TagItem” should be 254 characters or less.
See also Scenarios of Tag Item for additional information regarding this field.
Cluster Name
The name of the cluster that runs this trend. If the Cluster Name is not set, then this
trend will run on every defined cluster.
Comment
Any useful comment (254 characters maximum).
Tag Name
The name assigned to the trend data (79 characters maximum). If the trend tag is log-
ging a particular variable, use a 16-character name that resembles the 32-character name
of the related variable tag. This will mean an association between the two is easily rec-
ognizable. The name needs to be unique to the cluster. Trend Tag names need to adhere
to the Tag name syntax. If the name is not unique or is not syntactically correct it may
not be recognized. If you have many tags, use a naming convention (see Using struc-
tured tag names). This makes it easier to find and debug your tags.

Note: Where Cluster Name is left blank, the name needs to be unique to every
defined cluster.

Note: Trend tag names have to be unique and not identical to any SPC tag names
within the cluster(s) that run this trend. Two tags accessing the same file can result
in system errors which may include lost or corrupted trend/SPC data.

809
Chapter 27: Logging and Trending Data

UNINTENDED EQUIPMENT OPERATION

If using the File Name property, ensure that the trend tag uses a unique name. Two tags
accessing the same file can result in system errors which may include lost or corrupted
trend/SPC data.

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

Type
The type of trend (32 characters maximum):
l TRN_PERIODIC - A trend that is sampled continuously at a specified period. You
can also define a trigger to stop and start the trend (when a specified condition
occurs in the plant).

l TRN_EVENT - A trend that is sampled once each time the value of the trigger
changes from FALSE to TRUE. Interpolation occurs between each data point to create
a continuous graph.

810
Chapter 27: Logging and Trending Data

l TRN_PERIODIC_EVENT - A trend that is sampled once each time the value of the
trigger changes from FALSE to TRUE. No interpolation occurs between these points,
thus providing a graph which spikes at each data point.

Expression
The logged value of the trend tag (254 characters maximum). You can log individual var-
iables by using a variable tag. For example:

Expression LT131

Comment Logs the Variable Tag LT131

The value of the process variable LT131 is logged.

811
Chapter 27: Logging and Trending Data

You can also log any Cicode expression or function, for example:

Expression LT131/COUNTER

Comment Logs Variable Tag LT131 divided by the Variable Tag COUNTER

Note: When a variable tag is used in the expression field of a trend tag property, the
Eng Zero Scale and Eng Full Scale fields of that variable tag needs to be set appro-
priately, or data may be lost because the trend logs negative values are invalid.

Storage Method
Select Scaled or Floating Point (64 characters). Scaled is a 2-byte data storage method;
floating point uses 8 bytes.
Floating point storage has a dramatically expanded data range in comparison to scaled
storage, allowing values to have far greater resolution. However, you need to consider
that it also uses a lot more disk space. Use scaled where compatibility with pre-V5.31
trend history files is necessary.
This field cannot be left blank. If you do not specify a storage method, the compiler will
generate an error message.

Note:
• Trend records need to explicitly define their trend storage method. The compiler
will raise an error if not defined. In previous versions, the default when not defined
was “Scaled (2 byte)”8 byte . When upgrading, customers should set the trend stor-
age method for blank entries to match the default from the previous version.
• If you edit this property in an existing project, you need to delete the associated
trend files - before you run the new runtime system. (For location of the trend files,
see the File Name.)

Sample Period
The sampling period of the data. You can either enter a period of your own, or choose
one from the menu.
Enter sampling periods of greater than one second in hh:mm:ss (hours:minutes:seconds)
format. If you enter a single digit, without the colon (:), it will be considered a second.
For example, if you enter 2, it will be interpreted as 2 seconds.
Sampling periods of less than one second needs to be entered as decimals. For example,
to enter a period of 200 milliseconds, you would enter 0.2.

812
Chapter 27: Logging and Trending Data

If the sample period is less than one second, then one second needs to be divisible by the
period (to give an integer). For example, a sample period of 0.05 is valid, because 1/0.05
= 20, whereas a sample period of 0.3 is not valid because 1/0.3 = 3.333... .

Note:
• Your I/O Device needs to be capable of providing data at the specified rate, other-
wise gaps will appear in the trend data and/or the hardware alarm Trend has
missed samples will be evoked. You can fill gaps in the file and graph using the
[Trend]GapFillTime parameter. Gaps in the graph only can be filled using the TrnSet-
DisplayMode() function.
• If trends with a sample period of less than a second are shared by several clients
across a network (distributed processing), enable time synchronization using the
Time Synchronization configuration application This verifies that trends are syn-
chronized with each other.

The Trigger is checked each sample period. If the Trigger is TRUE (or has just changed
from FALSE to TRUE, in the case of event trends), the value of the Expression is logged.
Examples

Sample Period Comment

30 Logs data every 30 seconds

10:00 Logs data every 10 minutes

10:00:00 Logs data every 10 hours

2:30:00 Logs data every 2 and a half hours

The sampling period of the fastest trend on the page is taken as the default value for the
display period of the page.
This property is optional. If you do not specify a sample period, the sampling period
defaults to 10 seconds.

Note: If you edit this property in an existing project, delete the associated trend files
before running the new runtime system (For location of the trend files, see File
Name).

No. Files

813
Chapter 27: Logging and Trending Data

The number of history files stored on your hard disk (for this tag) (4 characters max-
imum). The maximum number of files you can specify per trend tag is 999. Performance
and storage will be severely impacted by having a large number of history files per
trend.
By default, 2 history files are stored on your hard disk.
Period
The period of the history file, in hh:mm:ss (32 characters maximum). Alternatively, you
can:
l Specify a weekly period by entering the day of the week on which to start the history
file, for example Monday, Tuesday, Wednesday, etc.
l Specify a monthly period by entering the day of the month on which to start the his-
tory file, for example 1st, 2nd, 3rd, 4th, 5th, etc.
l Specify a yearly period by entering the day and the month on which to start the his-
tory file, for example 1st January, 25th February, etc. The day and month needs to be
separated by a space.
If you do not specify a period, the period defaults to Sunday (weekly).
When deciding on a period setting, be aware that the performance of a trend
viewer (be it the existing CitectSCADA or Process Analyst) may be impacted by
the size of a trend file. This is particularly true when displaying event-based trend
data.

Note: If you edit this property in an existing project, delete or move the associated
trend files before you run the new runtime system. (For location of the trend files, see
File Name.)

No. Files
The number of history files stored on your hard disk (for this tag) (4 characters max-
imum). The maximum number of files you can specify per trend tag is 999. Performance
and storage will be severely impacted by having a large number of history files per
trend.
If you do not specify the number of files, 2 history files are stored on your hard disk.

Note: If you edit this property in an existing project, delete or move the associated
trend files - before you run the new runtime system. (For location of the trend files,
see the File Name.)

Time

814
Chapter 27: Logging and Trending Data

The time of day to synchronize the beginning of the history file, in hh:mm:ss (32 char-
acters maximum). If you do not specify a time, the file is synchronized at 0:00:00 (i.e.
midnight). The time needs to be specified in Greenwich Mean Time, not the local time
zone.

Note: If you edit this property in an existing project, delete the associated trend files -
before you run the new runtime system. (For location of the trend files, see the File
Name.)

Extended forms fields

The following fields are implemented with extended forms (press F2). Note that some of
the fields listed below may be displayed in the previous section of the form.
Trigger
The Cicode expression (or variable tag) that triggers data logging (254 characters max-
imum). For example:

Trigger LT131<50

In this example, logging occurs when the value of the variable tag (LT131) falls below
50.
For a periodic trend, data is logged only while the value of the trigger is TRUE. (The
trend graph will still scroll, but will display <GATED> where the trigger is FALSE.) In
the above example, data is logged continuously while the value of LT131 remains less
than 50. Logging ceases when the value rises to (or above) 50. Logging does not occur
again until the value of LT131 falls below 50.
You do not have to specify a trigger for a periodic trend. If you do not specify a trigger
for a periodic trend, logging occurs continuously.
For an event trend, data is logged once when the value of the trigger changes from
FALSE to TRUE. In the above example, one sample is logged when the value of LT131
first becomes less than 50. Another sample is not logged until the value of LT131 rises to
(or above 50) and again falls below 50.
File Name
The file where the data is to be stored (253 characters maximum). Specify the complete
path or use path substitution.
When data is collected from your plant floor, it is stored in a file on the hard disk of
your computer which is then used to display a trend or SPC graph (a separate file is
used for each trend tag).

815
Chapter 27: Logging and Trending Data

By default, CitectSCADA stores the file in the [DATA] directory on the hard disk where
you installed CitectSCADA. The default name of the file is the trend tag name. However,
you can specify an alternate file name like this:

File Name [DATA]:TANK131

where [DATA] specifies the disk and path for the data. Use path substitution to make
your project more 'portable'.
Notes:
l You can no longer store trend files in the bin, runtime, backup or user directories or any
subdirectories of these. If you have existing Version 3.xx or 4.xx projects that use
these directories to store trend files, the path for these will have to be changed to the
Data directory.
l The trend system will buffer the acquired data before saving it to a file. The [Trend]
CacheSize parameters determine the buffer sizes for returned data.
l The File Name property is optional. If you do not specify a file name, the file name
defaults to [DATA]:<Name> on the hard disk where you installed CitectSCADA.
Where <Name> is the trend Tag Name.
If you use the File Name property, confirm that no other SPC tags or trend tags use
the same filename. Two tags accessing the same file can result in system errors
which may include lost or corrupted trend/SPC data.

UNINTENDED EQUIPMENT OPERATION

If using the File Name property, ensure that the trend tag uses a unique file name. Two
tags accessing the same file can result in system errors which may include lost or cor-
rupted trend/SPC data.

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

l A file extension should not be used when specifying a file name. If you edit this prop-
erty (change the file name or path) in an existing project, existing trend data is
ignored.
Area
The area to which the trend data belongs.
Privilege
The privilege necessary by an operator to display the trend data on a trend.
Eng Units

816
Chapter 27: Logging and Trending Data

The engineering units of the variable/expression being logged (8 characters maximum).

The engineering units are used by the trend scales and trend cursor displays.
Format
The format of the variable/expression being logged (11 characters maximum). The format
is used by the trend scales and trend cursor displays.
This property is optional. If you do not specify a format, the format defaults to ####.#.
Deadband
A deadband allows the value of a variable tag to fluctuate within a defined threshold
without updates being sent through to the trend tag. This may be useful if a tag
produces many small, insignificant value changes. The threshold is represented as a per-
centage of the tag's engineering range. The default value is 0 (zero), which captures
every value change.
For example, if a tag has an engineering range of zero to 10000, a deadband of 1 would
mean a change in value would have to be greater than 100 (or 1 percent of the range) to
be recognized. If the current value was 5600, the tag in the PLC would have to change to
a value greater than 5700 or less than 5500 before an update would be sent to the trend
tag.
If an associated variable tag has a deadband setting, it will not automatically apply to a
related trend tag. The trend tag deadband should be configured independently.
Historize
This field enables you to automatically historize and publish the specified trend tag in
Schneider Electric's Historian application.
If you set this field to "TRUE", the variable will be included in an automated con-
figuration process within the Historian environment. If you set the field to "FALSE" (or
leave it blank), the variable will not be included.
See Integration with Historian.

Trend Graphs
Trend graphs visually represent past and current activity of plant-floor data, building a
picture over time of how a variable (such as product output, level, temperature, and so
on) changes or how a device or process is performing. You can monitor current activity
as it happens and scroll back through time to view trend history.
As the values of variables change over time or as events happen, the graph moves
across the page. The latest values are displayed by default. You can scroll back through
historical data to display past values of the variable (or process).

817
Chapter 27: Logging and Trending Data

You can trend any single variable or Cicode expression. You can display any number of
trends on the screen simultaneously, even if they have different sample periods. You can
also display up to eight trend tags (pens) in any trend window.
A trend graph can only communicate with one cluster, therefore you cannot mix trends
from multiple clusters on a single trend graph. To graph trends from multiple clusters
you will need to use multiple trend graphs, or, use the Process Analyst which has no
such restrictions.
Historical data collection continues even when the display is not active. You can switch
between pages without affecting trend graphs. Trend data acquisition and storage of
data (in trend history files) continues even when the display is not active.
You can use the following standard trends:
l A single full page trend, where one trend window displays on a graphics page.
l A double full page trend, where two trend windows display on a graphics page.
l A zoom trend with two trend windows and added functionality for zooming.
l A pop-up trend that you can 'pop up' anywhere (in a separate window) on your com-
puter screen.
l User-defined trends that you can position anywhere on any graphics page.

Note: Variable tags can also be visually trended using an SPC Control Chart. Sta-
tistical Process Control (SPC) is a facility that enables you to control the quality of
materials, manufactured products, services, etc. This quality control is achieved by
collecting, arranging, analyzing, and testing sampled data in a manner that detects
lack of uniformity or quality.

Creating trend pages

You can use any of the predefined trend templates for your trend pages, or use a prede-
fined template to produce your own trend templates. You can draw a trend background
(such as gridlines) on your trends.
To configure a trend page:

1. Click New Page, or choose File | New.

2. Select Type: Page.
3. Choose the Resolution (size) of the trend page.
4. Choose a trend Template for the trend page:

818
Chapter 27: Logging and Trending Data

l Singletrend - One trend on the page

l Doubletrend - Two trends on the page
l Eventtrend - One event trend on the page
l Zoomtrend - Two trends on the page (one window for zooming)
l Poptrend - A single trend on the page (for display in a pop-up window)
5. Click OK.
To create multiple trend pages, you can:
l Create a trend page for each set of trends to display in the runtime system.
l Create a single trend page and use the PageTrend() function to display trends as nec-
essary. With this function, you can display the trends in the system with a single
trend page
l Create the trend page with the Graphics Builder, and set the pen names to blank. You
then display that page by calling this function and passing the necessary trend tags
(up to 8). Call the PageTrend() function from a menu of trend pages.
See Also
Trend interpolation

Trend interpolation
Trend interpolation is used to define the appearance of a trend graph when the incom-
ing samples fall out of synchronization with the display period or when samples are
missed.
For example, a particular trend might be sampled five times between each update of the
trend graph. As only one value can be displayed for each update, a single value needs to
be used that appropriately represents the five samples; and that could be the highest
value, the lowest value, or an average.
To define how CitectSCADA calculates the value to use, you set a particular trend inter-
polator display method.
The following table shows the available interpolator display methods, grouped into con-
dense methods (where the display period is longer than the sample period) and stretch
methods (where the display period is less than or equal to the sample period).

Condense methods Stretch methods

Average (default) - this dis- Step (default) - This method simply displays the
plays the average of the samples value of the most recent sample.
within the previous display
period

819
Chapter 27: Logging and Trending Data

Minimum- This displays the Ratio - This method uses the ratio of sample times
lowest value that occurred dur- and values immediately before and after the
ing the previous display period. requested time to interpolate a "straight line" value.

Maximum - This displays the Raw Data - This method displays the actual raw
highest value that occurred dur- values.
ing the previous display period.

The interpolation display method is set via TrnSetDisplayMode() function. You can also
use the [Trend]GapFillMode parameter, but it will interpolate values within the actual
trend file as well as on the trend graph.

Printing Trend Data

You can print trend data using the following functions:

Function Purpose

TrnPrint Prints a trend that is displayed on the screen.

TrnPlot Prints a plot of one or more trend tags.

TrnCom- Prints two trends (one overlaid on the other), each of up to four trend
parePlot tags.

WinPrint Prints the active window

The standard trend templates have buttons that call these functions to print data.
When you print using the TrnPrint function, the Plot Setup dialog box appears. Use this
dialog box to:
l Specify the title of the trend.
l Add a comment which is displayed beneath the title.
l Specify whether the trend is going to print in black and white, or in color. The selec-
tion that you make here will become the setting for the [General]PrinterColorMode
parameter.
l Define your printer setup. The printer that you select here will be set as the default
printer at the [General]TrnPrinter parameter.
l Specify whether or not the form displays the next time the function is used. This
check box sets the [General]DisablePlotSetupForm parameter.

820
Chapter 27: Logging and Trending Data

Exporting Trend Data

You can export trend data to reports and databases with the following functions:

Function Purpose

TrnGetTable Retrieves trend information and stores it in a Cicode array

TrnExportClip Copies trend data to the clipboard

TrnExportCSV Copies trend data to a CSV file

TrnExportDBF Copies trend data to a DBF file

The standard trend templates have buttons that call these functions to export data.

Note: You can also select part of your trend graph (click and drag) and copy the
underlying values to the Windows clipboard. You can then paste them into an Excel
spreadsheet. (If you are pasting millisecond values, you will need to create a custom
format for the TIME column to display these values correctly. To do this, select the
column and select Format | Cells. In the Number tab, select Custom for Category,
and type h:mm:ss.000 AM/PM.)

Using Trend History Files

When CitectSCADA starts up for the first time, it creates the trend files necessary by each
trend tag in the runtime system. (You can change this default using the [Trend}AllFiles
parameter.)
A system of rotational history files is used to store the trend data. Data is stored in sev-
eral files rather than in a single large file.
By default, there are 2 files (for each trend tag). You can change the default by specifying
the number of files to use, for example:

821
Chapter 27: Logging and Trending Data

No. Files Comment

10 Use ten files for the data, as in the diagram below.

1. When Citect begins logging, data is written to the first file.

2. At midnight the following Sunday, Citect writes to the second file.
3. At midnight the following Sunday, Citect writes to the third file, and so on.
4. After week 10, the first file is overwritten with new data.
The maximum number of files you can specify per trend tag is 270.
You can also specify the period between files, i.e., when a new history file is used, for
example:

Period Comment

1:00:00 Use a new file each hour

6:00:00 Use a new file every six hours

72:00:00 Use a new file every three days

Monday Use a new file each week beginning on Monday

15th Use a new file every month beginning on the 15th of each month

25th June Use a new file every year beginning on the 25th of June

You can also specify the time of day to synchronize the start of the history file; for exam-
ple:

822
Chapter 27: Logging and Trending Data

Time Comment

6:00:00 Synchronize the file at 6:00 am

12:00:00 Synchronize the file at 12:00 midday

18:30:00 Synchronize the file at 6:30 pm

Calculating disk storage

Equations allow you to calculate the total disk space necessary to store a trend across a
specified period of time.

Note: The storage method used for a trend (Scaled or Floating Point ) affects the
number of bytes necessary for each sample, so in order to calculate the disk space
necessary correctly it is important to base your calculations on the appropriate for-
mula.

To find out which storage method a particular trend is using, refer to the extended Trend
Tag Properties dialog. (By default, the Scaled storage method is used.)
See Also
Scaled
Floating Point
Reconfiguring history files

823
Chapter 27: Logging and Trending Data

Scaled
Each data sample requires two bytes of storage. You can therefore calculate the total disk
storage necessary for each trend by using the following formula:

Bytes necessary for each = 464 x No. Files + File Period (secs) x (No.
trend 176 + Files) x 2

Sample Period (secs)

For example, if a trend record produces one sample every ten seconds for one week, and
you are using five data files (five weeks), the number of bytes necessary is:

Bytes necessary = 464 x 5 + 176 + (7 x 24 x 60 x 60) x 5 x 2

Bytes necessary = 607,296 bytes

See Also
Floating Point
Reconfiguring history files
Calculating disk storage

Floating point
Each data sample requires eight bytes of storage. This alters the equation to:

Bytes nec- = 704 x No. Files + 160 + File Period (secs) x (No. Files) x 8
essary for
each trend
Sample Period (secs)

The number of bytes necessary then becomes:

Bytes necessary = 704 x 5 + 160 + (7 x 24 x 60 x 60) x 5 x 8

Bytes necessary = 2,422,976 bytes

Note: The calculations above do not take into account the space necessary to store
the history file for each trend. This is because these files remain at a set size and
therefore do not significantly impact the amount of disk space necessary.

Note: For efficient trends storage, use Windows file compression. By using this

824
Chapter 27: Logging and Trending Data

method you often can reduce your files to 10% of their original size; the actual
amount of compression varies depending on the rate of change of the data.

See Also
Calculating disk storage
Reconfiguring history files

Reconfiguring history files

If you change the configuration of your trend history files (in an existing project), or you
change the configuration of a trend tag that affects the number, time, or period of the
trend files, you need to delete the existing trend files - before you run the new system.
If you change the path of your trend history files (in an existing project), existing trend
data is ignored.

Note: You need to not delete history files (that CitectSCADA creates) from your hard
disk while your system is running, as the trend server will attempt to recreate the
files and this may cause system performance issues.

Using Path Substitution

Instead of specifying the full path to data files in your system, you can use path sub-
stitution.
With path substitution, you define a name that is a substitution for the full directory
path. You can then use the substitution name in the following format:

File Name [SUBSTITUTION]:<filename>

For example, if you decide to store a trend data file called MYFILE in a directory called
C:\CITECT\DATA\MYTRENDS, you can specify the full path to the file, for example:

File C:\Documents and Settings/All Users/Application Data/Schneider Elec-

Nam- tric/CitectSCADA v7.40/Data
e (Vista and later C:\ProgramData/Schneider Electric/CitectSCADA v7.40/Data).

or define a path substitution (for example MYDATA) and specify the path as:

File Name [MYDATA]:MYFILE

825
Chapter 27: Logging and Trending Data

Path substitution provides greater control of data storage. You can change the location of
data files by changing the definition of the data path - instead of locating and changing
each occurrence of the data path.
See Also
Default path definitions

Default path definitions

CitectSCADA has the following predefined path substitutions:

Pat- Plat- Default Directory

h form
Na-
me

[Bi- Pre- C:/Program Files/Citect/CitectSCADA 7.30/BinC:/Program

n] Vista Files/Schneider Electric/PowerSCADA Expert 7.30/Bin
and
Vista

[Us- Pre- Documents and Settings/All Users/Application Data/Ci-

er] Vista tect/CitectSCADA 7.30/UserDocuments and Settings/All Users/Ap-
plication Data/Schneider Electric/PowerSCADA Expert 7.30/User

Vista ProgramData/Citect/CitectSCADA 7.30/UserProgramData/Schneider

Electric/PowerSCADA Expert 7.30/User

[Da- Pre- Documents and Settings/All Users/Application Data/Ci-

ta] Vista tect/CitectSCADA 7.30/DataDocuments and Settings/All Users/Ap-
plication Data/Schneider Electric/PowerSCADA Expert 7.30/Data

Vista ProgramData/Citect/CitectSCADA 7.30/DataProgramData/Schneider

Electric/PowerSCADA Expert 7.30/Data

Pre-Vista The current project directory

[Ru- and Vista
n]

Pre-Vista The current copy project directory

[Co- and Vista
py]

Pre-Vista The current backup project directory

[Ba- and Vista
ck]

826
Chapter 27: Logging and Trending Data

Debugging Trending
The TrendDebug Citect.ini parameter is provided to help you while logging and trend-
ing data.
Example:
[Trend]
TrendDebug=n

where n can be the combination of the following debug options:

l 1 - Logs the client, server, and redundancy message types and also the samples being
written in the Trends Server from normal acquisition.
l 2 - Logs detailed information about the currently active backfill process, including the
redundant samples written to the archive.
l 4 - Logs detailed information for the TrendSetTable functions.
l 7 - Logs trend activities.
l 8 - Logs the summary information only for the currently active backfill process.
l 16 - Logs to syslog.dat the client trend data.
These settings can be added together to have combinations of logging levels. For exam-
ple
[Trend]
TrendDebug=6

logs the detailed backfill process and TrendSetTable functions.

These settings are read dynamically, meaning that you can change these settings while
CitectSCADA is running and the changes will take effect from that point onwards.

827
Chapter 27: Logging and Trending Data

828
Chapter 28: Understanding Statistical Process Con-
trol
Statistical quality control (SQC) helps track and improve product or service quality. Sta-
tistical process control (SPC) is the primary tool of SQC and encompasses the collection,
arrangement, and interpretation of process variables associated with a product, in regard
to uniformity of quality.
Every process is subject to variation and therefore there is always room to improve proc-
ess consistency and quality. To respond to this, adopt a continuous improvement
strategy. By repeating the following cycle, a strategy of prevention can be implemented.
This is the key to using SPC effectively. Consider the following steps:
l Analyze the process
l What do we know about the variability of this process?
l Is this process statistically controllable (predictable)?
l Is the process capable of meeting the set requirements?
l What considerations are most important to meeting process quality criteria?
l Maintain (control) the process
l Improve the process
SPC encompasses the concepts of variation, statistical control, and process capability,
and typically uses the tools XRS control chart, capability chart, and the Pareto chart.
See Also
Process Variation
Statistical Control
Process Capability
XRS Control Charts
Capability Charts
Configuring capability charts
Pareto Charts
Using Statistical Process Control (SPC) with CitectSCADA

829
Chapter 28: Understanding Statistical Process Control

Process Variation
To use SPC effectively, understand the concept of variation. When a product char-
acteristic is measured repeatedly, each measurement is likely to differ from the last. This
is because the process contains sources of variability.
When the data is grouped into a frequency histogram, it will tend to form a pattern. The
pattern is referred to as a probability distribution and is characterized in three ways:

Note: Most SPC techniques assume that the collected data has a normal distribution.

Variation is generally categorized into one of two types:

l Common: refers to variation that is predictable and repeatable over time. The dis-
tribution characteristics will be stable. Common variation could be due to consistent
process inaccuracy or similar.
Statistics indicate that common variations account for about 85% of departures from
process quality requirements. Usually these departures require solution at the man-
agement level.
l Special: refers to variation that is not consistently present. When special variation
occurs it will tend to change the distribution characteristics. The distribution is not
stable over time.
Statistics indicate that special variations account for about 15% of departures from proc-
ess quality requirements. Typically these departures require local action (equipment
repair and so on) for solution.
See Also
Process Variation

830
Chapter 28: Understanding Statistical Process Control

Statistical Control
A process is said to be in statistical control when the only sources of variation are from
common causes. A statistically controllable process is desirable because it is predictable,
while a statistically uncontrollable process will yield unpredictable distributions.

Even though a process might not be statistically controllable, it might still meet require-
ments. Conversely, a process which is controllable might not meet requirements. This
issue is clarified by considering Process Capability.
See Also
Process Variation

Process Capability
A process is said to be capable when the percentage of samples outside the specification
limits is less than a predefined value. The following assumptions need to also be true:
l The process is statistically stable (only common causes of variation exist)
l The individual measurements conform to a normal distribution
l Measurement variation (due to the measuring instrument) is small
The specification limits are a reflection of the customers requirements and are selectable.
The percentage of samples that need to lie within the specification limits is calculated
from the standard deviation (sigma)"3-sigmas" on either side of the mean.

Note: The "3-sigma" term refers to the boundaries which are located 3 standard devi-
ations on either side of the center. For a normal distribution 99.74% of the samples
are expected to fall within this boundary.

831
Chapter 28: Understanding Statistical Process Control

Ultimately capability determines whether the process is statistically able to meet the spec-
ification or not. Reducing the effects of common variation will make your process more
capable, as shown here:

XRS Control Charts

XRS charts are the primary tool of SPC and convey information about variation and con-
trollability. The charts are trend graphs that individually show mean (X bar), range (R),
and standard deviation (s or sigma). Each point on the graph represents sub-grouped
data, not individual samples.

CL, UCL and LCL

Each graph has center, upper control limit (UCL), and lower control limit (LCL) lines
drawn. The control limits are estimates of where the "3-sigma" limits would lie for an
approximately normal distribution. In practice the limits are calculated from the meas-
ured X double bar, R bar, and s bar, and table values which are based on the size of the
subgroup used.

832
Chapter 28: Understanding Statistical Process Control

These lines are used as a guide for analysis as they are based on the natural variability
of the process. These limits are not specification limits.

Interpreting the chart

Control charts can provide valuable information about process variation. By watching
for particular patterns and events, conclusions can be drawn as to how the process is
controlling.
A (normal) process that is statistically under control will tend to distribute data accord-
ing to a normal distribution. The data will appear randomly, but centered around the
center line. Data that appears near the control limits may be infrequent but expected.
Presence of data that appears outside of the control limits indicates the process is sta-
tistically uncontrolled and action should be taken to address the cause. Similarly, runs of
constant data or patterns indicate instability.
The following list of patterns and events are considered to be cause for alarm:
l Points beyond the control limits
l Several consecutive points on only one side of the average
l Several consecutive points that are consistently increasing or decreasing
l Substantially more than 2/3 of plotted points lie close the average
l Substantially less than 2/3 of plotted points lie close to the average
The presence of these types of patterns and events has different meanings, depending on
which type of chart is being analyzed. By using each of the three control charts together
(X bar, R and s) together, a better understanding of readings is gained.
See Also
Capability Charts

Capability Charts
The process capability chart is the frequency histogram and distribution of the process
mean data and is used to analyze process capability. This chart is drawn with center
line, lower specification limit and upper specification limit indicators in place. Inter-
preting capability charts is typically made with the Cp, Cpk, kurtosis and skewness
indices.

833
Chapter 28: Understanding Statistical Process Control

USL and LSL

Upper specification limit (USL) and lower specification limit (LSL) specify the require-
ments of the product, and so are customer driven. Make the target value the midpoint
between USL and LSL.

Cp index
The inherent process capability (Cp) is the ratio of tolerance to 6-sigma. Essentially this
index indicates whether the distribution would fit inside the USL and LSL limits. Its
meaning is defined as follows:
l Cp > 1.0 - Indicates the process variation will fit within the specified limits (USL and
LSL) and therefore, is capable.
l Cp < 1.0 - Indicates the process is not capable.

Cpk Index
The process capability based on the worst case (Cpk) is similar Cp. This index, however,
indicates where the mean lies in relation to the USL and LSL limits. It is used to math-
ematically clarify Cp. Its meaning is defined as follows:
l Cpk < 0 - Indicates the process mean is outside the specified limits (USL and LSL)
l Cpk = 0 - Indicates the process mean is equal to one of the specified limits.
l Cpk > 0 - Indicates the process mean is within the specified limits.
l Cpk = 1.0 - Indicates that one side of the 6-sigma limits falls on a specification limit.
l Cpk > 1.0 - Indicates that the 6-sigma limits fall completely within the specified lim-
its.
See Also
Pareto Charts

Pareto Charts
A Pareto chart is a tool which is used to analyze the relative frequency of deviations
from specifications or success criteria. The Pareto chart is a frequency histogram which
is ordered from highest to lowest. Unlike control and capability charts, this chart uses no
statistical guides.

834
Chapter 28: Understanding Statistical Process Control

Pareto charts emphasize Pareto's empirical law that any assortment of events consists of
a few major and many minor elements. In the context of SQC, it is important to select the
few vital major opportunities for improvement from the many trivial minor ones. The
Pareto chart is particularly useful for Cost-to-fix versus Deviation-frequency analysis.
In addition to the histogram, typically a cumulative percentage is also given. From top
to bottom, the percentage represents the ratio of the sum of evry value to this point, to
the sum of every value in the chart.

Using Statistical Process Control (SPC)

CitectSCADA displays Statistical Process Control information on three types of chart;
XRS Control Chart, Process Capability Chart, and Pareto Chart.
To configure an SPC chart:

1. Click New Page or choose File | New.

2. Select Type: Page.
3. Choose the Resolution (size) of the SPC page.
4. Choose an SPC Template for the SPC page:
l SPCXRSChart - An XRS control chart
l SPCCpk - A capability (Cpk) chart combined with an Mean chart

Note: Pareto charts are configured slightly differently and hence, are not included
here.

5. Click OK.
6. Double-click the graph display.
7. Enter the variable tag in the Genie pop-up.
8. Click OK.
9. Save the page.
See Also
SPC Tags
SPC Control Charts

SPC Tags
SPC tags specify data that is to be collected for use in SPC operations. Once data is
defined it can be dynamically analyzed (as SPC graphs and alarms) at run-time. SPC
tags are similar to trend tags.

835
Chapter 28: Understanding Statistical Process Control

Like trends, CitectSCADA can collect and store any amount of SPC data. The only restric-
tion on the amount of data that you can store is the size of the hard disk on your com-
puter. (CitectSCADA uses an efficient data storage method to optimize the use of storage
space on your computer's hard disk.) For long-term storage, you can archive the data to
disk or tape (without disrupting your runtime system). You can also log data at regular
intervals (periodic trend), or only when an event occurs (event trend), in the same
manner as Trend Tags.

Note: SPC does not support Periodic-Event trends, which is a combination of the
properties of Periodic and Event trends. In addition, if you use event-based SPC tags,
your display screen refresh rate may be slower than desired or practical for your
application.

When you define an SPC tag you will want to be sure to fill in the upper specification
limit (USL) and lower specification limit (LSL) if you intend to perform a capability anal-
ysis. These values have to accurately represent the users requirements, and the target
value lie midway between the two. If these fields are left blank the capability analysis
will be meaningless.
To configure an SPC tag:

1. Choose Tags | SPC Tags. The SPC Tags dialog box appears.
2. Enter the SPC tags properties.
3. Click Add to append a new record, or Replace to modify an existing record.
See Also
SPC tag properties

SPC tag properties

Note: When modifying an SPC tag, be aware that if the tag was created using the
equipment editor - equipment type workspace, the fields configured will be grayed
out in the tag properties form.

Use the SPC Tags dialog box to configure the SPC tag properties. Statistical Process Con-
trol (SPC) Tags have the following properties:
Equipment
The name of the equipment associated with the SPC Tag. Select or enter a name of 254
characters or less. You can optionally prefix a cluster name to the equipment name in
order to restrict the reference to a piece of equipment in only one cluster. The cluster
needs to be configured otherwise the compile will not be successful. Use this method as

836
Chapter 28: Understanding Statistical Process Control

an alternative to referencing a cluster in the equipment properties dialog if the equip-

ment is defined for all clusters.
Item Name
Enter a meaningful name for Tag Item. Used as part of the equipment hierarchy a mean-
ingful name will help with future migration of your system and the step towards an
object oriented model.
This field is optional. If not configured, the last 63 characters of the “SPC Tag” field will
be used for the Tag Item name. The SPC Tag allows 79 characters, while Tag Item has a
maximum of 63 characters. This may result in compiler error messages if the 'Equip-
ment.TagItem' name is not unique.
There is a limit of 254 characters on the combination of Equipment and Tag Items, plus
the period '.', for example “Equipment.TagItem” should be 254 characters or less.
See also Scenarios of Tag Item for additional information regarding this field.
Cluster Name
The name of the cluster the SPC tag runs in.
If the Cluster Name is not set, then CitectSCADA considers this SPC tag to run on every
defined cluster.
Comment
Any useful comment (254 characters).
SPC Tag Name
The name assigned to the SPC data. If you are logging a variable, use the same name for
the SPC tag that you used for the variable tag.

UNINTENDED EQUIPMENT OPERATION

If using the File Name property, ensure that the SPC tag uses a unique name. Two tags
accessing the same file can result in system errors which may include lost or corrupted
trend/SPC data.

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

Type
The type of SPC trend:
1. TRN_PERIODIC
2. TRN_EVENT

837
Chapter 28: Understanding Statistical Process Control

Expression
The logged value of the SPC tag. Enter a value of 254 characters or less. You can log
individual variables by using a Variable Tag, for example:

Expression PT104

Comment Logs the Variable Tag PT104

The value of the process variable PT104 is logged. Variable PT104 has to be defined as a
variable tag. You can also log any Cicode expression or function, for example:

Expression PT104/COUNTER

Comment Logs Variable Tag PT104 divided by the Variable Tag COUNTER

Subgroup Size
The size of each subgroup. The default value for this value is 5. Valid values are 1 - 25
inclusive.
Storage Method

UNINTENDED EQUIPMENT OPERATION

If you edit this property in an existing project, delete associated SPC trend files before plac-
ing the system back in service.

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

Select either Scaled or Floating Point as the storage method for the SPC data (64 char-
acters). The key difference between these two options is that Scaled is a two-byte data
storage method, whereas Floating Point uses eight bytes.
Floating Point storage has a dramatically expanded data range in comparison to Scaled
storage, allowing values to have far greater resolution. However, you need to consider
that it also uses a lot more disk space. Scaled should be used where compatibility with
pre-V5.31 trend history files is necessary.

838
Chapter 28: Understanding Statistical Process Control

If you do not specify a storage method, it is set to Scaled by default.

Sample Period
The sampling period of the data, in hh:mm:ss (hours:minutes:seconds). CitectSCADA
checks the Trigger each sample period. If the Trigger is TRUE (or has just changed from
FALSE to TRUE, in the case of event SPC trends), CitectSCADA will log the value of the
Expression.
Examples

Sample Period Comment

30 Logs data every 30 seconds

10:00 Logs data every 10 minutes

10:00:00 Logs data every 10 hours

2:30:00 Logs data every 2 and a half hours

This property is optional. If you do not specify a sample period, the sampling period
will default to 10 seconds.

Note: If you edit this property in an existing project, delete or move or move the asso-
ciated trend files before you run the new runtime system.

Lower Spec Limit

The Lower Specification Limit (LSL). This value is used as the lower limit to determine
process capability. When used in conjunction with the USL it provides a tolerance for
your process.
If you are unfamiliar with process capability and capability indices, ask for expert opin-
ion. Rather than leave this blank (at least) attempt an estimate. Enter a value that you
think is the lowest acceptable value of this tag. If you leave this field blank only your
capability analysis will be affected.
X double bar
The calculation override for process mean (X double bar). If a value is specified here it
will be used in every SPC calculation, instead of the value calculated by CitectSCADA.
This will affect the calculation of control limits which are normally a function of the col-
lected samples of data.
You should not use this field unless you are experienced in SPC.
Upper Spec Limit
The Upper Specification Limit (USL). This value is used as the upper limit to determine
process capability. When used in conjunction with the LSL it provides a tolerance for
your process.

839
Chapter 28: Understanding Statistical Process Control

If you are unfamiliar with Process Capability and capability indices, ask for expert opin-
ion. Rather than leave this blank (at least) attempt an estimate - Enter a value that you
think is the highest acceptable value of this tag. If you do leave this field blank only your
capability analysis will be affected.
Range
The calculation override for process range (R bar). If a value is specified here it will be
used in every SPC calculation, instead of the value calculated by CitectSCADA. This will
affect the calculation of control limits which are normally a function of the collected sam-
ples of data.
You should not use this field unless you are experienced in SPC.
St. Deviation
The calculation override for process standard deviation (s bar). If a value is specified
here it will be used in every SPC calculation, instead of the value calculated by Citect-
SCADA. This will affect the calculation of control limits which are normally a function
of the collected samples of data.
Do not use this field unless you are experienced in SPC.
No. Files

UNINTENDED EQUIPMENT OPERATION

If you edit this property in an existing project, delete associated SPC trend files before plac-
ing the system back in service.

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

The number of history files stored on your hard disk (for this tag).
By default, two history 2 history files are stored on your hard disk. The maximum
number of files you can specify is 270.
Period

UNINTENDED EQUIPMENT OPERATION

If you edit this property in an existing project, delete associated SPC trend files before plac-
ing the system back in service.

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

840
Chapter 28: Understanding Statistical Process Control

The period of the history file, in hh:mm:ss (hours:minutes:seconds). Alternatively, you

can:
l Specify a weekly period by entering the day of the week on which to start the history
file, for example Monday, Tuesday, Wednesday, etc.
l Specify a monthly period by entering the day of the month on which to start the his-
tory file, for example 1st, 2nd, 3rd, 4th, 5th, etc.
l Specify a yearly period by entering the day and the month on which to start the his-
tory file, for example 1st January, 25th February, etc. The day and month needs to be
separated by a space.
If you do not specify a period, the period defaults to Sunday (weekly).
Time

UNINTENDED EQUIPMENT OPERATION

If you edit this property in an existing project, delete associated SPC trend files before plac-
ing the system back in service.

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

The time of day to synchronize the beginning of the history file, in hh:mm:ss (hours:mi-
nutes:seconds). If you do not specify a time, the file is synchronized at 0:00:00 (i.e. mid-
night).

Extended forms fields

Trigger PT104<500

In this example, logging occurs when the value of the variable tag (PT104) falls below
500.
For a periodic SPC trend, data is logged only while the value of the trigger is TRUE. In
the above example, data is logged continuously while the value of PT104 remains less
than 500. Logging ceases when the value rises to (or above) 500. Logging does not occur
again until the value of PT104 falls below 500.

841
Chapter 28: Understanding Statistical Process Control

You do not have to specify a trigger for a periodic SPC trend. If you do not specify a
trigger for a periodic SPC trend, then logging will occur continuously.
For an event SPC trend,data is logged once when the value of the trigger changes from
FALSE to TRUE. In the above example, one sample is logged when the value of PT104
first becomes less than 500. Another sample is not logged until the value of PT104 rises
to (or above 500) and again falls below 500.
File Name
The file where the data is to be stored. You need to specify the complete path or use path
substitution.
When CitectSCADA collects data from your plant floor, it stores the data in a file on the
hard disk of your computer. When it subsequently uses the data to display an SPC trend,
it reads the data from this file. (CitectSCADA uses a separate file for each SPC tag.)
By default, CitectSCADA stores the file in the [DATA] directory on the hard disk where
you installed CitectSCADA. The default name of the file is the SPC tag name. However,
you can specify an alternate file name like this:

File Name [DATA]:TANK131

where [DATA] specifies the disk and path for the data. Use path substitution to make
your project more 'portable'.
The File Name property is optional. If you do not specify a file name, the file name
defaults to [DATA]:<Name> on the hard disk where you installed CitectSCADA. Where
<Name> is the SPC Tag Name.

Note: If you use the File Name property, confirm that no other SPC tags or trend tags
use the same filename. Two tags accessing the same file can result in system errors
which may include lost or corrupted trend/SPC data.

UNINTENDED EQUIPMENT OPERATION

If using the File Name property, ensure that the SPC tag uses a unique name. Two tags
accessing the same file can result in system errors which may include lost or corrupted
trend/SPC data.

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

Note: Avoid using a file extension when specifying a file name. If you edit this

842
Chapter 28: Understanding Statistical Process Control

property (change the file name or path) in an existing project, existing SPC data is
ignored.

Area
The area to which the SPC data belongs. Only users with access to this area (and any
necessary privileges) will be able to display the SPC data on an SPC page. For example,
if you enter Area 1 here, operators need to have access to Area 1 (plus any necessary
privileges) to display the SPC data.
Privilege
The privilege necessary by an operator to display the SPC data on an SPC page.
Eng Units
The engineering units of the variable/expression being logged. The engineering units are
used by the SPC trend scales and SPC trend cursor displays.
Format
The format of the variable/expression being logged. The format is used by the SPC trend
scales and SPC trend cursor displays.
This property is optional. If you do not specify a format, the format defaults to ####.#.
Deadband
The value that SPC Tag needs to return to before the SPC data becomes inactive.
Historize
This field enables you to automatically historize and publish the specified variable tag
in Schneider Electric's Historian application.
If you set this field to "TRUE", the variable will be included in an automated con-
figuration process within the Historian environment. If you set the field to "FALSE" (or
leave it blank), the variable will not be included.

SPC Control Charts

CitectSCADA uses the following types of control charts:
l XRS control chart
l Capability charts
l Pareto Charts
See Also
Control Chart Line Constants

843
Chapter 28: Understanding Statistical Process Control

XRS control chart

The XRS charts display trends of subgroup means (X bar), ranges (R) and standard devi-
ations (s). The XRS chart operates similarly to a standard trend, but with additional SPC
extra features. Each subgroup displays as a single node on the graph and consecutive
nodes are linked by a line.
Each control chart has a central line and two control limits-upper and lower (UCL and
LCL). CitectSCADA automatically calculates these SPC values at run-time. If you want to
override the UCL and LCL you can do so by entering the Process Mean, Range, and
Standard Deviation fields in SPC Tags.
See Also
Configuring XRS charts

Configuring XRS charts

Genies simplify the task of adding a new SPC page. To create a new chart:
l Define the SPC Tags.
l Create the page using an XRS template.

Note: If you want to develop your own XRS template, the method is to copy and
modify and existing template.

Capability charts
The process capability chart is a frequency histogram and distribution of the sample
data currently displayed (on the Mean chart). CitectSCADA automatically takes the data
being trended, builds a distribution, adds the LSL and USL. It also calculates the Cp,
Cpk, kurtosis, and skewness indices.
The process capability is defined in relation to the upper and lower specification limits
(USL and LSL) for a given SPC Tag. These values are defined in SPC Tags and accu-
rately represent the users requirements.
See Also
Configuring capability charts

Configuring capability charts

Genies simplify the task of adding a new SPC page. To create a new chart:

844
Chapter 28: Understanding Statistical Process Control

1. Define the SPC Tags and specify the LSL and USL.
2. Create the page using a Capability (Cpk) template.

Pareto Charts
Pareto analysis is a technique used to identify the relative importance of problems and
conditions. The Pareto chart is a frequency histogram ordered from highest to lowest-
CitectSCADA automatically orders the bars at run-time. The data for each bar in the his-
togram represents one CitectSCADA variable - as defined in Variable Tags. Do not use
SPC tags.

Note: Typically the frequency in a histogram is of integer type, though you can use
floating point types if you want. Negative values are not valid.

Configuring Pareto charts

Genies simplify the task of adding a new Pareto chart.
To create a new chart:

1. Define the Variable Tags (Pareto charts do not use SPC Tags).
2. Create the page using a Pareto template.
To configure a Pareto chart:

1. Click New Page, or choose File | New.

2. Select Type: Page.
3. Choose the Resolution (size) of the SPC page.
4. Choose the SPCParetoTemplate for the SPC chart.
5. Click OK.
6. Double-click the display (where prompted by the template).
7. Enter the variable tags in the Tag Name fields. (Use Variable tags here, not nec-
essarily SPC tags.)
8. Enter the variable descriptions in the Tag Description boxes.
9. Click OK.
10. Save the page.

845
Chapter 28: Understanding Statistical Process Control

SPC Alarms
CitectSCADAautomatically monitors several special kinds of conditions that are specific
to SPC data. When specific patterns or events occur to an SPC tag, it will set the appro-
priate alarm. Typically these alarms are related to, and used in conjunction with, the
XRS control charts.
SPC alarms are configured differently to standard digital alarms to provide for this extra
functionality. SPC alarms needs to be configured using the Advanced Alarms form. You
use the SPCAlarms Cicode function to check for the condition of the alarms:

Note: An SPC alarm can only be defined on an Alarm Server in the same cluster as
the Trends Server that contains the SPC tag (though the variable tag referenced in the
SPC tag can be on a different IOServer cluster).

Complete the Advanced Alarm form as shown here:

Advanced Alarms

Alarm Tag Feed_Above_UCL

Alarm Desc Un-controlled variation

Expression SPCAlarms("Feed_SPC", XAboveUCL)

Comment Several samples are above UCL

The SPC (Trends) Server checks for any specified alarm conditions. When one is
detected, it informs the Alarm Server that an alarm has occurred. Be aware of the
number of subgroups displayed on your SPC charts, and the number used in SPC alarm
calculations (as set by the [SPC]AlarmBufferSize parameter). If these two values differ,
SPC alarms might not correlate with your SPC charts.
The following list shows the alarms types that are valid:

Name Description

XFreak Single point greatly differs (2 sigma) from the center line.

XOutsideCL Process mean outside either of the control limits (UCL or LCL).

846
Chapter 28: Understanding Statistical Process Control

XAboveUCL Process mean above the upper control limit (UCL).

XBelowLCL Process mean below the lower control limit (LCL).

XOut- Process mean outside the alert limits which are 67% of the UCL and LCL.
sideWL

XGradualUp Process mean is gradually drifting up to a new level indicated by several

consecutive points above the mean.

XGrad- Process mean is gradually drifting down to a new level indicated by sev-
ualDown eral consecutive points below the mean.

XUpTrend Several points continuously increasing in value.

XDown- Several points continuously decreasing in value.

Trend

XErratic Large fluctuations that are greater than the control limits.

XStrat- Artificial constancy. Several consecutive points are close to (within 1

ification sigma of) the center line.

XMixture Several consecutive points are far from (outside 1 sigma of) the center
line.

ROutsideCL Process range outside either of the control limits (UCL or LCL).

RAboveUCL Process range above the upper control limit (UCL).

RBelowLCL Process range below the lower control limit (LCL).

Note: The above alarms rely on n number of consecutive points to generate the
alarm. The value of n can be set for each type of alarm through SPC parameters.

SPC Formulas and Constants

The SPC calculations are based on the samples collected in subgroups. Each subgroup
will have the same number of samples, typically 4. The subgroup size for each SPC tag
is set at the SPC Tags properties form.

847
Chapter 28: Understanding Statistical Process Control

The number of samples in each subgroup can range from 1 to 25 inclusive.

When the number of samples in each subgroup is 1

Subgroup Mean ( ):
is the value of the single sample in the group, and is defined by:

Where is the single sample value in the subgroup.

Moving Range (MR):
is the difference between successive sample values, and is defined by:

Where is the current sample value and is the previous sample value. The
number of moving ranges in the process is always one less than the number of sub-
groups.
Subgroup Standard Deviation (s):
is a measure of absolute variation or dispersion. It describes how much the sample
values differ from their mean, and is estimated by:

The number of subgroup standard deviations in the process is always one less than the
number of subgroups.

Process Average ( ):

Where , , and are the subgroup means, and m is the total number of subgroups
in the process.

Process Range ( ):

Where MR , MR , and MR are the subgroup moving ranges, and m is the total
2 3 m
number of subgroups in the process.
Process Standard Deviation ( ):

848
Chapter 28: Understanding Statistical Process Control

When the number of samples in each subgroup is greater than 1

Subgroup Mean ( ):
is the average (not median or center) of the samples in the group, and is defined by:

Where X , X , and X are the sample values in the subgroup, and n is the total number
1 2 n
of samples in the subgroup.
Subgroup Range (R):
is the difference between the highest and lowest samples in the group, and is defined by:

Where X is the maximum sample value and X is the minimum sample value in
max min
the group.
Subgroup Standard Deviation (s):
is a measure of absolute variation or dispersion. It describes how much the sample
values differ from their mean, and is defined by:

Where X's are the sample values in the group, is the group average, and n is the
number of samples in the group.

Process Average ( ):

Where , , and are the subgroup averages, and m is the total number of sub-
groups in the process.

Process Range ( ):

849
Chapter 28: Understanding Statistical Process Control

Where R , R , and R are the subgroup ranges, and m is the total number of subgroups
1 2 m
in the process.
Process Standard Deviation ( ):

Where s , s and s are the group standard deviations, and m is the total number of
1 2 m
groups in the process.
Average Control Limits (UCL and LCL ):
x x
Specify the approximated 3-sigma boundaries. For a normal distribution 99.74% of the
samples will fall within this boundary.

Where is the Process Range and A is a constant (given in the Control Chart Line Con-
2
stants table).
Range Control Limits (UCL and LCL ):
R R
Specify the approximated 3-sigma boundaries. For a normal distribution 99.74% of the
samples will fall within this boundary.

Where is the Process Range and D and D are constants (given in the Control Chart
3 4
Line Constants table).
Standard Deviation Control Limits (UCL and LCL ):
s s
Specify the approximated 3-sigma boundaries. For a normal distribution 99.74% of the
samples will fall within this boundary.

850
Chapter 28: Understanding Statistical Process Control

Where is the Process Standard Deviation and B and B are constants given in the
3 4
Control Chart Line Constants table).
Process Capability (Cp):
Is the capability of a process to meet a specific tolerance. A process is considered capable
when the percentage of samples of a variable for that process that fall within the upper
and lower specification limits is greater than a specified value.
The inherent process capability is defined as:

l Cp > 1.0 - Indicates the process variation is within the specified limits (USL and LSL)
and therefore, is capable.
l Cp < 1.0 - Indicates the process is not capable.
The process capability based on worst case data is defined as:

l Cpk < 0 - Indicates the process mean is outside the specified limits (USL and LSL)
l Cpk = 0 - Indicates the process mean is equal to one of the specified limits.
l Cpk > 0 - Indicates the process mean is within the specified limits.
l Cpk = 1.0 - Indicates that one side of the 6-sigma limits falls on a specification limit.
l Cpk > 1.0 - Indicates that the 6-sigma limits fall completely within the specified lim-
its.
Skewness (Sk):
Is the degree of asymmetry of a frequency distribution (usually in relation to a normal
distribution).

where N is the number of samples for the entire process (i.e. Subgroup Size * number of
Subgroups).
l Skewness > 0 - Indicates that the histogram's mean (and tail) is pushed to the right.
l Skewness < 0 - Indicates that the histogram's mean (and tail) is pushed to the left.
Kurtosis (Ku):
Is the degree of peakedness of a frequency distribution (usually in relation to a normal
distribution).

851
Chapter 28: Understanding Statistical Process Control

where N is the number of samples for the entire process (i.e. Subgroup Size * number of
Subgroups).
l Kurtosis < 3 - Indicates a thin distribution with a relatively high peak.
l Kurtosis > 3 - Indicates a distribution that is wide and flat topped.

Control Chart Line Constants

The table below shows the control chart line constants:

Samples in Averages Ranges Standard Deviations

Group A2 D2* D3 D4 B3 B4

1 2.660 0 0 3.267
1.12- 3.26-
8 7

2 1.880 0 0 3.267
3.26-
7

3 1.023 0 0 2.568
2.57-
4

4 0.729 0 0 2.266
2.28-
2

5 0.577 0 0 2.089
2.11-
4

6 0.483 0 0.030 1.970

2.00-
4

7 0.419 0.118 1.882

0.07- 1.92-
6 4

8 0.373 0.185 1.815

852
Chapter 28: Understanding Statistical Process Control

0.13- 1.86-
6 4

9 0.337 0.239 1.761

0.18- 1.81-
4 6

10 0.308 0.284 1.716

0.22- 1.77-
3 7

10 0.308 0.284 1.716

0.22- 1.77-
3 7

11 0.285 0.321 1.679

0.25- 1.74-
6 4

12 0.266 0.354 1.646

0.28- 1.71-
3 7

13 0.249 0.382 1.618

0.30- 1.69-
7 3

14 0.235 0.406 1.594

0.32- 1.67-
8 2

15 0.223 0.428 1.572

0.34- 1.65-
7 3

16 0.212 0.448 1.552

0.36- 1.63-
3 7

17 0.203 0.466 1.534

0.37- 1.62-
8 2

18 0.194 0.482 1.518

0.39- 1.60-
1 8

19 0.187 0.497 1.503

0.40- 1.59-

853
Chapter 28: Understanding Statistical Process Control

3 7

20 0.180 0.510 1.490

0.41- 1.58-
5 5

21 0.173 0.523 1.477

0.42- 1.57-
5 5

22 0.167 0.534 1.466

0.43- 1.56-
4 6

23 0.162 0.545 1.455

0.44- 1.55-
3 7

24 0.157 0.555 1.445

0.45- 1.54-
1 8

25 0.153 0.565 1.435

0.45- 1.54-
9 1

* D2 is only used for estimating standard deviation when there is one sample per sub-
group.
Reference ANSI Z1.1-1985, Z1.2-1985 & Z1.3-1985: American National Standard, Guide
for Quality Control Charts, Control Chart Method of Analyzing Data, Control Chart Method of
Controlling Quality During Production.
Hints
Double-click the chart area on an SPC page to display the SPC Genie and change the
SPC variables.
The tools and menu items in these procedures automatically open the CitectSCADA
form for you. Move the cursor till it changes to a hand to find these tools or options.

854
Chapter 29: Reporting Information
You can request regular reports on the status of your plant, and reports that provide
information about special conditions in your plant. Reports can be run on a request
basis, at specified times, or when certain events occur (such as a change of state in a bit
address). Output from a report is controlled by a device. A report can be printed when it
runs or saved to disk for printing later. You can use a text editor or word processor to
view, edit, or print the report, or you can display it in CitectSCADA as part of a page.
Reports can also include Cicode statements that execute when the report runs.
Reports are configured in two stages:
l Report properties
l Report format file
If report data is associated with an I/O Device that does not initialize properly at startup
or goes offline while CitectSCADA is running, the associated data is not written to the
report (because the values would be invalid). An error code is written instead.
See Also
Configuring reports
Running Reports
Report Format File
Handling Communication Errors in Reports

Configuring reports
To design, configure and use a report:

1. Configure a device for output of the report (for example, if you want to save a report
to a file when it is run, set up an ASCII_DEV device).
2. Configure the report properties.
3. Edit the report format file. Remember that for an RTF report, the report format file
needs to be saved in RTF format (that is, with an .RTF file extension).
4. Define your PC as a reports server using the Computer Setup Wizard.
To configure report properties:

1. Choose System | Reports to display the Reports dialog box.

2. Enter the reports properties. Click Edit to edit the report format file.
Use the Reports dialog box to configure your reports.

855
Chapter 29: Reporting Information

Reports dialog box

The Reports form has the following properties:
Name
The name of the report. The name can be a maximum of 79 characters. It can consist of
any character other than the semi-colon (;) or single quote ('). The name needs to be
unique to the cluster.

Note: Where Cluster Name is left blank, the name needs to be unique to every
defined cluster.

Cluster Name
The name of the cluster that runs this report. If the Cluster Name is not set, then Citect-
SCADA considers this report to run on every defined cluster.
Time
The time of day to synchronize the report, in hh:mm:ss (hours:minutes:seconds). If you
do not specify a time, the report is synchronized at 0:00:00 (i.e., midnight). Enter a value
of 32 characters or less.
Period
The period of the report, in hh:mm:ss (hours:minutes:seconds). Enter a value of 32 char-
acters or less. Alternatively you can:
l Specify a weekly period by entering the day of the week when the report is to start,
for example, Monday, Tuesday, Wednesday, etc.
l Specify a monthly period by entering the day of the month when the report is to start,
for example, 1st, 2nd, 3rd, 4th, 5th, etc.
l Specify a yearly period by entering the day and the month when the report is to start,
for example, 1st January, 25th February, etc. The day and month needs to be sep-
arated by a space.
If you do not specify a period, the report is run daily.
Trigger

856
Chapter 29: Reporting Information

Any Cicode expression (or Variable tag) to trigger the report. Enter a value of 254 char-
acters or less. If the result of the expression (in this field) is TRUE, and the Time and
Period fields are blank, the report is run. The report is only run when the expression
becomes TRUE, and it needs to become FALSE then TRUE again before the report is re-
run.
Report Format File
The name of the report format file. Enter a value of 253 characters or less. If you do not
specify a file extension, it defaults to .RPT. Any valid file name can be used; however,
you cannot use a Path Substitution in this field. If you specify a filename without a path,
the file saves into the directory predefined as Run. The report is assumed (by the Citect-
SCADA compiler) to be ASCII unless an RTF extension is used.

Note: The file name of your report format file can be up to 64 characters long, or 253
characters including the path. It can consist of any characters other than the single
quote ('), and the semi-colon (;).

Output Device
The device where the report will be sent. Enter a value of 16 characters or less.
For RTF reports that are to be saved as a file, select a device of type ASCII_DEV here.
Due to the differing natures of their content; however, it is not recommended that the
same ASCII device be used for logging both RTF and non-RTF reports.

Note: If two or more reports are running at the same time and are sending their out-
put to the same printer, the output of each report can become mixed. You need to use
semaphores to control the access to the printer in each report. See the SemOpen\
Cicode function. If the report only contains Cicode statements (and has no output
data), this property is optional.

Comment
Any useful comment. Enter a value of 48 characters or less.

Extended forms fields

The following fields are implemented with extended forms (press F2).
Privilege
The privilege necessary by an operator to run this report if the report is a command-
driven report. Enter a value of 16 characters or less.
If the report is time-driven or event-driven, this property is ignored.

Note: If you assign an acknowledgment privilege to a report, do not assign a

857
Chapter 29: Reporting Information

privilege to the command(s) that run the report. If you do assign a different privilege
to the commands, an operator needs to have both privileges to run the report.

Area
The area to which this report belongs. Enter a value of 16 characters or less. Only users
with access to this area (and any necessary privileges) will be able to run this report. For
example, if you enter Area 1 here, operators need to have access to Area 1 (plus any nec-
essary privileges) to run this report.

Running Reports
You can run a report by the following methods:
l Automatically when CitectSCADA starts up
l Automatically at a specified time and period
l Automatically when an event is triggered
l By using a command
l A combination of the above
See Also
Running a report on startup
Specifying times and periods
Using triggers
Using commands

Running a report on startup

You can run a report on startup. CitectSCADA searches for a report called "Startup"
when it starts up, and if CitectSCADA locates this report, it is run automatically. You
can change the name of the default report with the Computer Setup Wizard.
See Also
Specifying times and periods

Specifying times and periods

The period determines when the report is run. You can specify the period in hh:mm:ss
(hours:minutes:seconds), for example:

858
Chapter 29: Reporting Information

Period Comment

1:00:00 Run the report every hour

6:00:00 Run the report every six hours

72:00:00 Run the report every three days

Monday Run the report each Monday

15th Run the report on the 15th of each month

25th June Run the report on the 25th of June

You can also specify the time of day to synchronize the report, for example:

Time Comment

6:00:00 Synchronize the report at 6:00 am

12:00:00 Synchronize the report at 12:00 midday

The time synchronizes the time of day to run the report and, with the Period, determines
when the report is run, for example:

Time Period

6:00:00 1:00:00

In this example, the report is run every hour, on the hour. If you start your runtime sys-
tem at 7:25am, your report is run at 8:00am, and then every hour after that.
See Also
Using triggers

Using triggers
You can use any Cicode expression (or variable tag) as a trigger for a report. If the result
of the expression (in the Trigger field) becomes TRUE, and if the Time and Period fields
are blank, the report is run. For example:

Time

Period

Trigger RCC1_SPEED<10 AND RCC1_MC

This report is only run when the expression (Trigger) becomes TRUE, i.e., when the dig-
ital tag RCC1_MC is ON and the analog tag RCC1_SPEED is less than 10. The expres-
sion needs to become FALSE and then TRUE again before the report is run again.

859
Chapter 29: Reporting Information

If you use the Time and/or Period fields, the trigger is checked at the time and/or period
specified, for example:

Time 6:00:00

Period 1:00:00

Trigger RCC1_SPEED<10 AND RCC1_MC

This report is run each hour, but only if the expression (Trigger) is TRUE (i.e., if the dig-
ital tag RCC1_MC is ON and the analog tag RCC1_SPEED is less than 10).
See Also
Using commands

Using commands
If the Time, Period, and Trigger fields are blank, the report can only be run by a com-
mand that calls the Cicode Report() function.

Report Format File

The report format file specifies how data is formatted in a report. You can use fixed text,
Cicode expressions, and database variables in any report.
You use a text editor that is supported by Windows to create (and modify) the report for-
mat file. If your report format file is in RTF (Rich Text Format), use Microsoft Wordpad.
Including fixed text
You can include fixed text in the report, specifying the text exactly as you want it to
appear (for example, Name of Report, Description, and so on).
Including OLE (RTF files only)
Objects can be linked to or embedded within an RTF report format file; however, such
objects will not be displayed or printed from CitectSCADA.
Using fonts (ASCII format only)
If your format file is in ASCII format, you can use any text font supported by Windows
in the report. To specify a font, use the PrintFont() function. RTF format files do not
require this function, as they use the formatting features of the host word processor.
Including Cicode expressions and variables

860
Chapter 29: Reporting Information

You can include Cicode expressions and variables by enclosing them (and optional for-
mat specifications) in braces {} - for example:

{TIME(1) }
{PV12:####.##}
{PV12:4.2}

The size of each field (number of characters) is determined by either the format spec-
ification, or by the number of characters between the braces. In the above example, the
variable PV12 is formatted with four characters before the decimal point and two char-
acters after.
You do not have to include the format, for example:

{PV12}

Here, the variable is formatted using only four characters (the number of characters
between the braces).
The following rules apply when logging a report to a database device:
l The format (for the report field) do not specify a field size greater than the size of the
relevant field specified in the device.
l No spaces are allowed between each field specification, for example:
{TIME(1) }{PV12:####.##}{PV12:4.2}

Including blocks of Cicode

You can include a block of Cicode, using the following format:

{CICODE}
Statements;
{END}

The block of Cicode is delimited by the commands {CICODE} and {END}. After the {END}
command, the report switches back into WYSIWYG mode. If the entire report is Cicode
or the last section is Cicode, the {END} command is not necessary.
A block of Cicode does not send any output to the device unless you use either the Print
() or PrintLn() functions. If you use one of these functions, the argument is printed to the
device.
Cicode variables (ASCII format only)
You can also declare variables for use within your Cicode block. This is not available in
RTF or HTML format files. Declare any variables at the beginning of the file (i.e. before
any report format or Cicode). Add a {CICODE} block first; for example:

861
Chapter 29: Reporting Information

{CICODE}
INT nVar1;
STRING sVar2;
Statements;
{END}

Remainder of report

Including comments
You can include comments by using the comment character `!' enclosed in braces - for
example:

{!This is a Comment}

A comment in the body of a report differs from a comment in a Cicode block: a comment
in a Cicode block does not require braces.
Including other report elements
The following table describes other elements you can include in reports.

To... Do this...

Issue a form feed Use a form feed specifier: {FF}

Include a plot Use the Plot functions.

Include trend data Use the TrnGetTable() function.

Include trend graphs Use the TrnPlot() function.

Prompt("Shift Report Complete");

{END}
{FF}

This report produces the following output to the device and displays "Shift Report Com-
plete" on the graphics page.

-----------------------------------
SHIFT REPORT
-----------------------------------
6:00am 12/3/92
Shift Production 352.45 tons
Total Production 15728 tons
End of Report

To edit a report format file:

1. From the Reports properties form, select the relevant report, and click Edit. Alter-
natively, click Edit Report.
2. Select the report to edit
3. Click Edit.

Note: If the report format file exists, it is loaded into the editor for you to edit. If the
file does not exist, CitectSCADA creates a new file.

To change the report format file editor:

1. Click the Options tool, or choose File|Options.

2. Enter the name of the new Editor.
3. Click OK.

Handling Communication Errors in Reports

You can handle errors in communication with I/O Devices (for example, an I/O Device
does not initialize properly at startup or goes offline while CitectSCADA is running) in
two ways:
l You can write communication errors and invalid data to the report as error codes.
l You can disable the running of reports that are triggered from an I/O Device, if com-
munication with the I/O device has been lost.

863
Chapter 29: Reporting Information

See Also
Reporting errors in I/O Device data
Suppressing reports

Reporting errors in I/O Device data

If a communication error is detected (with an I/O Device) or if the data is invalid, one of
the following alert messages are written to the report (instead of the value):

Error Meaning

#ASS The value is incorrectly associated (with a substitution string or Genie).

Communication with the I/O Device has been lost

#CO-
M

An attempt was made to divide a number by 0 (zero)

#DIV-
/0

#ERR An uncommon error has occurred. (Use the IsError function to find the occur-
rence.)

Out of memory or more than 64 kb bytes of memory requested.

#ME-
M

Data from this device is pending an initial update to display a value.

#PEN-
D

The value returned is out of range

#RA-
NGE

The value has caused a stack overflow

#STA-
CK

Data from this scheduled device is not available as it has not reached its sched-
#WA- uled interval and has no cache value.
IT

For example:
Report Format:

864
Chapter 29: Reporting Information

{PV_1} {SP_1} {OP_1}

If the above report is run when the value of PV_1 is out of range (for example 101.5),
SP_1 is 42.35 and OP_1 is 60.0, the output of the report is:
Report Output:

#RANGE 42.35 60.0

When reports are written to a database device, you might sometimes want to disable the
alert messages and write the values to the report (even if the values are invalid). Use the
ERR_FORMAT_OFF command to disable alert messages and write data as values.
For example:
Report Format:

{ERR_FORMAT_OFF}
{PV_1} {SP_1} {OP_1}
If the above report is run when the value of PV_1 is out of range (for example
101.5)
, SP_1 is 42.35 and OP_1 is 60.0, the output of the report is:

Report Output:

42.35 60.0

To re-enable the alert messages, use the ERR_FORMAT_ON specifier.

Note: If an I/O Device goes offline and you have disabled communication errors, the
value printed into the report is either 0 (zero) or the last value read from the I/O
Device when the report was last run. In either case, the value is invalid.

Command FileWrite(AlrmFile, Time()); FileWrite(AlrmFile, Date()); . . .

Instead of entering the same statements when necessary in a command, you can define a
label, and then use the label instead of the statements. When you compile your project,
each occurrence of the label is resolved; that is, the expression in the label is substituted
for the label name. For example:

Once defined, a label can be used as a statement in a command, for example:

When an operator issues this command, the expression defined in the label is sub-
stituted in the command.

867
Chapter 30: Using Labels

You can also use the label in combination with other statements, for example:

868
Chapter 30: Using Labels

The main advantage of a label is that it is a global definition, recognized throughout the
CitectSCADA system. If you want to change something (in the above example you might
change the file name or the way the data is logged), you only need to change it in one
place - in the label definition. Other occurrences of the label name will reflect the
changes.
See Also
Using Arguments in Labels
Converting Values into Strings
Substituting Strings
Defining Labels

Using Arguments in Labels

You can define labels that accept arguments enclosed in parentheses (). The following
example shows a label that increments a variable by a specific value:

Label Name Inc(X, STEP)

Expression X = X + STEP

Here, "X" is the variable to be incremented and "STEP" determines the amount of the
increment. You can then use this label in a command, as in the following example:

Key Sequence FastInc

Command Inc(SP12, 10);

An operator can use this command to increment the value of SP12 by 10.

Specifying default values

You can specify a default value for an argument when you define a label, for example:

Label Name Inc(X, STEP = 10)

Expression X = X + STEP

When you subsequently use this label without any arguments in a command, the default
value is used, for example:

Key Sequence FastInc

869
Chapter 30: Using Labels

Command Inc(SP12);

Converting Values into Strings

Sometimes, you need to convert a value into a string before it can be used. In the fol-
lowing example, the value of a tag is converted before it is used in the DspStr() function.

Label Name ShowVariable(TAG)

Expression DspStr(25, "BigFont", #TAG + "=" + TAG:##.#);

In the above example, only one argument (TAG) is passed to a function that actually
requires three arguments (AN, font and message). When you use this label in a com-
mand, the function uses AN 25 and the message displays in "BigFont". Only the third
argument (the actual message) varies.
The third argument passed to the function is:

...#TAG+"="+TAG:##.#

#TAG indicates that the name of the tag (and not its value) is displayed.
TAG:##.# indicates that the value of TAG is converted to a string and displayed. It is for-
matted with two numbers before the decimal point and one number following the dec-
imal point.
You can use the above label in a command such as:

Command ShowVariable(SP12);

When you use this command in your runtime system, the command displays
"SP12=<value>", where value is the actual value of SP12 at the time (for example
SP12=42.0).
See Also
Substituting Strings

870
Chapter 30: Using Labels

Substituting Strings
You can pass a string substitution as an argument in a label, for when several variables
have part of the variable name in common; for example:

Label Name SPDev(TAG)

Expression Prompt("Deviation=" + "IntToStr(CP##TAG## - SP##TAG##));

In the above example, TAG is the common portion of the variable name, and is sub-
stituted at each occurrence in the expression. To display the difference between two var-
iables CP123 and SP123, you would specify SPDev(123) in a command, for example:

Command SPDev(123);

You cannot use a substitution within a string. In the following example, the DESC
Parameter (a text description) will not be substituted as it is between quotation marks:

Prompt("Deviation for ##DESC##=" + "IntToStr(CP##TAG## -

SP##TAG##))

1. Choose System | Labels. The Labels dialog box will display.

2. Enter a Label Name of 128 characters or less. Whenever this name is used (i.e,. in
Cicode or a field), CitectSCADA automatically substitutes the expression below.
3. Enter an Expression to be substituted for the label (maximum length is 254 char-
acters). You can use a label to substitute a name for an entity or Cicode expression;
for instance, when you use the entity (or Cicode expression) in several database rec-
ords.
4. Add a Comment (of 48 characters or less).
5. Click Add to append a new record, or Replace to modify an existing record.

871
Chapter 30: Using Labels

872
Chapter 31: Using Devices
A device transfers high-level data (such as a report, command log or alarm log) between
CitectSCADA and other elements (such as a printer, database, RTF file, or ASCII file) in
your CitectSCADA system. Devices are similar to I/O Devices in that they both allow
CitectSCADA to exchange data with other components in your control and monitoring
system.

You can use devices for various purposes; for example, to send the output of a report to
a printer, or write data to a database.

873
Chapter 31: Using Devices

Using a device you can write data to:

l RTF files
l ASCII files
l dBASE databases
l SQL databases (through ODBC-compliant drivers)
l Printers (connected to your CitectSCADA computer or network)
You can configure any number of devices; however, a device is a common resource. You
can, for example, configure a single device that sends the output of your CitectSCADA
reports to a printer (when they are requested).

874
Chapter 31: Using Devices

See Also
Using groups of devices
Configuring Devices
Formatting Data in the Device
Using Device History Files
About Print Management

Using groups of devices

You can add flexibility to your system by using a group of devices. A group of devices
allows you to export the same data to two (or more) locations.

Using devices to read data

Using a device (and Cicode functions), you can also read data from:
l ASCII files
l dBASE databases
l SQL databases

875
Chapter 31: Using Devices

Note: When you read from a group of devices, data is only read from the first device
in the group.

1. Choose System | Devices. The Devices dialog box appears.

2. Complete the Devices dialog box using the description of the text boxes below.
3. Click Add to append a new record, or Replace to modify an existing record.
For information regarding configuring SQL devices, see Configuring SQL Devices.
Devices have the following properties:
Name
The name of the device. The device name can be the name of a group of devices, or a
label for a device. Enter a value of 16 characters or less.
See Also
Using groups of devices
Using Labels
"Predefined Devices" in the ProductName Technical Reference
Format

876
Chapter 31: Using Devices

Specifies how the data is formatted in the device. The format is determined by the type
of Device, and the data that is sent to the device. Enter a value of 120 characters or less.
See Using Command Fields for information on available fields.
If you are logging alarms or command messages, you need to specify a format, or no
data is written to the device.

Note: The log device for a command is specified wherever the command is defined.
The log device for an alarm is specified at the Alarm Categories form.

When producing reports, the format is ignored. (The format defined for the report is used
to write the report to the device.)
See Also
Formatting Data in the Device
Alarm display fields
Alarm summary fields
Using Command Fields
Header
Additional information for the device. Enter a value of 120 characters or less.
Printer devices
The header is printed on each page. A new page is created each time the form length is
reached. The [Device]FormLength parameter is used to set the form length.
ASCII file devices
Not applicable.
dBASE database devices
Contains the field name used to index the database, for example:

Header {Name}

Note: Index Key fields needs to not exceed 100 characters.

SQL database devices

The connection string for the particular database type.

Note:CitectSCADA database devices only support STRING data types. If you use
another database editor to modify your database, you will want to verify that fields
are in string format.

File Name

877
Chapter 31: Using Devices

The file name of the device. Enter a value of 253 characters or less.
Printer devices
The printer port or UNC name, for example:

File Name LPT1:

File Name COM2:

File Name \\PrintServer\BubbleJet1

When you specify a printer port, you need to include the colon character (:), otherwise
CitectSCADA tries to write to a file (device) with a name similar to the printer port (i.e.
LPT1 or COM2).

Note: When using a UNC name in Windows 95, the printer needs to be in the
Printers section of the Control Panel.

ASCII file devices and dBASE database devices

The name of the active file, for example:

File Name ALARMLOG.TXT

File Name [DATA]:ALARMLOG.TXT

This property is optional. If you do not specify a file name, File Name defaults to \Citec-
tSCADA 7.10\bin\\PowerSCADA Expert 7.30\bin\<Name> on the hard disk where you installed
CitectSCADA. <Name> is the first eight characters of the device name. If you use this
property, verify that no other devices have the same first eight characters in the device
name.
SQL database devices
The database table, for example:

File Name LOGFILE

File Name REPTBL

Type
The type of device. Enter a value of 16 characters or less.

878
Chapter 31: Using Devices

Device Type Device Description

ASCII_DEV ASCII file*

PRINTER_DEV Printer

DBASE_DEV dBASE file

SQL_DEV SQL database

* When defining RTF report properties, an ASCII device would be selected if the report
was to be saved as a file.
This property is optional. If you do not specify a type, the device Type is ASCII_DEV
unless:
The file name is a printer device (LPT1: to LPT4: or COM1: to COM4: or a UNC name),
where Type is PRINTER_DEV, or
The file name extension is .DBF, where Type is dBASE_DEV.
See Also
About Print Management
No. Files
The number of history files. Enter a value of 4 characters or less.
By default, CitectSCADA creates a single data file for each device. (This data file is called
<filename.TXT> or <filename.DBF>, depending whether the device is an ASCII device or
database device.) The number of history files you specify here are in addition to the data
file.

Note: If you do not want history files created, you need to enter 0 (zero) here, and set
the [Device]CreateHistoryFiles parameter to 0; otherwise, 10 history files will be
created as a default. You need to also verify that the data file is of a fixed size. (If the
data accumulates, the file eventually fills the hard disk.)

If you specify -1 the data is appended to the end of one file.

If you are logging alarm, keyboard commands, or reports to the device, specify the
number of files to be created, and the time of each file.
See Also
Using Device History Files

Time

879
Chapter 31: Using Devices

The time of day to synchronize the beginning of the history file, in hh:mm:ss (hours:mi-
nutes:seconds). Enter a value of 32 characters or less. If you accepted the default number
of history files above, and you specify a time and period, 10 history files will be created.
If you do not specify a time, the file is synchronized at 0:00:00 (i.e. midnight).
If you omit both the time and the period, additional history files will still be created
(with the default time and period). If you don't want history files to be created, you need
to set the [Device]CreateHistoryFiles parameter to 0 (zero).
Period
The period of the history file, in hh:mm:ss (hours:minutes:seconds). Enter a value of 32
characters or less. Alternatively you can:
l Specify a weekly period by entering the day of the week on which to start the history
file, for example Monday, Tuesday, Wednesday, etc.
l Specify a monthly period by entering the day of the month on which to start the his-
tory file, for example 1st, 2nd, 3rd, 4th, 5th, etc.
l Specify a yearly period by entering the day and month on which to start the history
file, for example 1st January, 25th February, etc. The day and month needs to be sep-
arated by a space.
If you accepted the default number of history files above, and you specify a time and
period, 10 history files will be created.
If you do not specify a period, the period defaults to Sunday (weekly).
If you omit both the time and the period, additional history files will still be created
(with the default time and period). If you don't want history files to be created, you need
to set the [Device]CreateHistoryFiles parameter to 0 (zero).
Cluster Name
Select a cluster from the list of clusters defined previously with the Servers, Clusters com-
mand in the Project Editor. See "Cluster Definitions ". If this is a single cluster system
this field can be left blank.
Process
Select the type of server (or client) on which the process runs that sends data to the
device. This field is used to prevent a history file being created while the device is active.
If there is no history processing then this field can be left blank
Comment
Any useful comment. Enter a value of 48 characters or less.

880
Chapter 31: Using Devices

Configuring SQL Devices

SQL devices are configured and used in a slightly different way than other types of
devices.

Configuration

Complete the following fields in the the Devices dialog:

l Name - Specify a name for the device, for example mySqlDevice.
l Format - Specify the format of the device. The format is the definition of the column
names in the target database table. For example, {date,10}{day,15}{month,20}{year,4}.
l Header - Specify the connection string for the database. For example, Driver={SQL
Server};Server=MyServer).
l File name - Specify the complete database table name. For example, Test-
Database.dbo.MySqlCalendar.
l Type - The type should be set to SQL_DEV.
Configure the rest of the fields as per other devices (see Configuring Devices).

Usage

When configured, the device can be associated with SCADA elements, or used in Cicode.
SQL devices are used in Cicode in a slightly different way to other types of devices. For
example, the order of DevSetField and DevAppend is different with SQL devices.
The following example makes a connection to a SQL device, cleans the records, adds
new records to the device, finds records matching the condition, then closes the con-
nection:

FUNCTION
DataSQLDeviceLogging()
STRING strValue = "";
INT hConnection = DevOpen("mySQLDevice") // open the device
IF hConnection <> -1 THEN
DevZap(hConnection); //clean the records

DevSetField(hConnection, "date_","30-03-2011");
DevSetField(hConnection, "day_","Wednesday");
DevSetField(hConnection, "month_","March");
DevSetField(hConnection, "year_","2011");
DevAppend(hConnection);

DevSetField(hConnection, "date_","31-03-2011");
DevSetField(hConnection, "day_","Thursday");
DevSetField(hConnection, "month_","March");
DevSetField(hConnection, "year_","2011");

881
Chapter 31: Using Devices

DevAppend(hConnection);

DevSetField(hConnection, "date_","01-04-2011");
DevSetField(hConnection, "day_","Friday");
DevSetField(hConnection, "month_","April");
DevSetField(hConnection, "year_","2011");
DevAppend(hConnection);

DevSetField(hConnection, "date_","02-04-2011");
DevSetField(hConnection, "day_","Saturday");
DevSetField(hConnection, "month_","April");
DevSetField(hConnection, "year_","2011");
DevAppend(hConnection);

IF DevFind(hConnection, "April", "month_") = 0 THEN

strValue = StrTrim(DevGetField(hConnection, "day_"));
END;
DevClose(hConnection); //close the connection
END;
END

Formatting Data in the Device

The device format specifies how to format the data in the device. The format is deter-
mined by the type of device, and the data that is sent to the device.
l Printer and ASCII devices format
l dBASE and SQL database devices format
See Also
Using a database device

Printer and ASCII devices format

The format specifies how each line of data is printed on the printer or written to the
ASCII file, for example:

RFP3 Raw Feed pump 3 Overload 12:32:21

RFP9 Secondary Feed Overtemp 13:02:45

When producing reports, the device format is ignored. The format defined for the report
(i.e. the report format file) is used to write the report to the device.
To include CitectSCADA data you need to specify the field name and (optionally a width
for each field to be printed or written to the file. The format has the following syntax:

{<field name>, [width[, justification]]}

882
Chapter 31: Using Devices

You need to enclose each field in braces {}, for example:

Format {Tag,8}{Name,32}

In this case, two fields are printed or written to the file - Tag, with 8 characters, and
Name, with 32 characters. The width specifier is optional - if you do not specify a width,
the width of the field is determined by the number of characters between the braces, for
example:

Format {Name }

In this case, Name is followed by four spaces - the field is printed or written to the file
with 8 characters.

Creating lists and tables

To set the justification of the text in each field, use a justification specifier. You can use
three justification characters, L (Left), R (Right), and N (None) - for example:

Format {Tag,8,L} {Name,32,R}

The justification specifier is optional - if it is omitted, the field is left justified. If you use a
justification specifier, you need to also use the width specifier.
To display field text in columns, use the tab character (^t) - for example:

Format {Tag,8}^t{Name,32}^t{Desc,32} {Time,8,R}

Including fixed text

You can include fixed text by specifying the text exactly as it is to be printed or written to
the file - for example:

Format Name of Alarm:

Any spaces that you use in a text string are also included in the string.
See Also
Formatting Data in the Device
Using a database device

883
Chapter 31: Using Devices

dBASE and SQL database devices format

The format specifies the structure (field names and field widths) of the database. The for-
mat has the following syntax:

{<field name>, <width>}

You need to use braces ({ }) to enclose each field, for example:

Format {Tag,8}{Name,32}

In this case, the database is created with two database fields - Tag, with 8 characters,
and Name, with 32 characters. The size of each database field is determined by the
width you specify in the format. (Justification character are ignored.) Every database field
is character (string) field types.
You can define your own fields (as well as the standard CitectSCADA fields) for the data-
base device, for example:

Format {Name,16}{Water,8}{Sugar,8}{Flour,8}
{Salt,8}{Yeast,8}{Milk,8}

This database device has the following structure:

Don't leave any spaces between each field definition or at the end of the format string, or
CitectSCADA creates extra fields for each space (in the device). Do not specify a field
name longer than 10 characters, or CitectSCADA truncates the name to 10 characters.
(The dBASE file format limits field names to a maximum of 10 characters.)
In this example, the database is created with seven database fields. To access the above
dBASE device, use a Cicode function similar to the following:

hDev = DevOpen("Recipe");
DevFind(hDev, "Name", "Bread");
PLC_Water = DevGetField(hDev, "Water");
PLC_Sugar = DevGetField(hDev, "Sugar");
. . .
. . .
DevClose(hDev);

884
Chapter 31: Using Devices

dBASE devices
If the database does not exist, it is created with the specified format. If you do not specify
a format, and if the file name specifies an existing dBASE file, CitectSCADA uses the
existing fields in the database.

SQL devices
You need to create the SQL database by an external application before it can be used.
If you edit a dBASE or SQL device record (in an existing project), the associated physical
device is not edited. For example, if the device is a dBASE type device and you add an
extra field in the device, the extra field is not added to existing database files (when you
run CitectSCADA).
If you want to make changes to the file structure of an existing database and retain exist-
ing data, you need to manually edit the data using dBASE, Excel or some other database
tool.
If you want to make changes to the file structure of an existing database and don’t want
keep the existing data:
1. Close the device.
2. Manually delete the device file.
3. Make your modifications.
4. Open the device.
When the device is opened no device file is available and a new data file is
created with the necessary changes.
See Also
Formatting Data in the Device
Using a database device

Using a database device

Before you can use a database device, you need to open it. You can open several devices
at the same time. The DevOpen() function returns an integer handle to identify each
device, as in the following example:

INT hRecipe;
hRecipe = DevOpen("Recipe");

885
Chapter 31: Using Devices

Writing dBASE records using a database device

To write data to a database device, first append a record to the end of the device, then
add data to the fields of the record. For a dBASE database, the DevAppend() function
appends the record, and the DevSetField() function writes data to a field. The following
function writes a recipe record to a device:

FUNCTION
WriteRecipeData(INT hDevice, STRING sName, INT Water, INT Sugar,
INT Flour, INT Salt, INT Yeast, INT Milk)
DevAppend(hDevice);
DevSetField(hDevice, "NAME", sName);
DevSetField(hDevice, "WATER", IntToStr(Water));
DevSetField(hDevice, "SUGAR", IntToStr(Sugar));
DevSetField(hDevice, "FLOUR", IntToStr(Flour));
DevSetField(hDevice, "SALT", IntToStr(Salt));
DevSetField(hDevice, "YEAST", IntToStr(Yeast));
DevSetField(hDevice, "MILK", IntToStr(Milk));
END

Writing SQL records using a database device

To use an SQL device in CitectSCADA, you cannot use every the Cicode Device function;
you can only use the following functions:

DevOpen() DevClose() DevGetField() DevFind() DevWrite()

DevNext() DevSeek() DevAppend() DevWrite() DevZap()

DevControl() DevSetField()

To write CitectSCADA data to an SQL database, use the DevWrite() function, but you
need to add a new record and write to fields in the new record. No data is written to the
database if you do not write to all fields.
For example:

FUNCTION
WriteRecipeData(INT hDevice, STRING sName, INT Water, INT Sugar,
INT Flour, INT Salt, INT Yeast, INT Milk)
DevWrite(hDevice, sName);
DevWrite(hDevice, Water);
DevWrite(hDevice, Sugar);
DevWrite(hDevice, Flour);
DevWrite(hDevice, Salt);
DevWrite(hDevice, Yeast);
DevWrite(hDevice, Milk);

886
Chapter 31: Using Devices

END

The following functions return error 267 (File mode is invalid) when the device type is
SQL:

DevFlush()

DevPrev()

DevDelete()

The follow function returns error 263 (Cannot read file) when the device type is SQL:

DevRead()

The following functions return error -1 when the device type is SQL:

DevSize()

DevRecNo()

Locating and reading database records using a database device

To read data from a dBASE or SQL database device, use the DevFind() function to locate
the record, and then the DevGetField() function to read each field:

FUNCTION
GetRecipe(STRING sName)
INT hDev;
hDev = DevOpen("Recipe");
IF hDev >= 0 THEN
IF DevFind(hDev, sName, "NAME") = 0 THEN
PLC_Water = DevGetField(hDev, "WATER");
PLC_Sugar = DevGetField(hDev, "SUGAR");
PLC_Flour = DevGetField(hDev, "FLOUR");
PLC_Salt = DevGetField(hDev, "SALT");
PLC_Yeast = DevGetField(hDev, "YEAST");
PLC_Milk = DevGetField(hDev, "MILK");
ELSE
DspError("Cannot Find Recipe " + sName);
END
DevClose(hDev);
ELSE
DspError("Cannot open recipe database");
END
END

887
Chapter 31: Using Devices

Deleting records using a database device

You can delete dBASE records with the DevDelete() function. The following Cicode func-
tion deletes records from a dBASE device:

FUNCTION DeleteRecords(INT hDev)

WHILE NOT DevEOF(hDev) DO
DevDelete(hDev);
DevNext(hDev);
END
END

To delete every record from a dBASE database, use the DevZap() function:

FUNCTION DeleteRecords(INT hDev)

DevZap(hDev);
END

To delete records from an SQL database, use the Cicode SQL functions.

Closing a database device

When finished with a device, close it to free Cicode system resources by using the Dev-
Close() function:

DevClose(hRecipe);

To define a group of devices:

1. Choose System | Groups. The Groups dialog box appears.

2. Complete the Groups form.
3. Click Add to append a new record, or Replace to modify an existing record.
See Also
Using Device History Files

Using Device History Files

To makes the long-term storage of logged data easier to organize and more accessible,
CitectSCADA uses a system of rotational history files to store historical data. To use this
system, you need to specify how many device history files you want to keep. For exam-
ple, if you want to keep 10 history files, they would be saved rotationally as illustrated
below:

888
Chapter 31: Using Devices

1. When CitectSCADA begins logging, data is written to a file called <filename>.txt or

<filename>.dbf, depending on the type of device.
2. At midnight the following Sunday, the file <filename>.txt is renamed to <file-
name>.001 and a new <filename>.txt is created.
3. At midnight the following Sunday, the file <filename>.001 is renamed to <file-
name>.002, <filename>.txt is renamed to <filename>.001, and then a new <file-
name>.txt is created.
4. After week 10, the first file is overwritten (week 11 in the first cycle).

Note: The 10 history files are in addition to the default data file that is saved for each
device.

By default, CitectSCADA uses 10 files (if history files are specified). You can change the
default by specifying the number of files to use, for example:

No. Files 20

Comment CitectSCADA uses twenty files for the data

The maximum number of files you can specify is 999.

You can also specify the period between files, i.e., when a new history file is used, for
example:

889
Chapter 31: Using Devices

Period Comment

1:00:00 Use a new file each hour

6:00:00 Use a new file every six hours

72:00:00 Use a new file every three days

Monday Use a new file each week beginning on Monday

15th Use a new file every month beginning on the 15th of each month

25th June Use a new file every year beginning on the 25th of June

Note: Marked improvement in system performance is observed when a period of one

week or more is specified.

You can also specify the time of day to synchronize the beginning of the history file, for
example:

Time Comment

6:00:00 Synchronize the file at 6:00 am

12:00:00 Synchronize the file at 12:00 midday

18:30:00 Synchronize the file at 6:30 pm

The first file does not actually begin at this time: the first file begins when you start your
runtime system. The time and period together determine when new history files are
created, for example:

Time Period

6:00:00 Monday

In the above example, CitectSCADA creates a new file each Monday at 6:00am. If you
start your runtime system at 7:30am on Sunday, your first file only contains 22.5 hours
of data. If you leave your system running, subsequent files start each Monday at 6:00am,
and contain one full week of data.

Archiving data
To archive your data for long-term storage, back up your history files before they are
overwritten. Use the Windows File Manager from the Main program group to check file
creation dates (of the history files) and to back up files. Refer to your Windows doc-
umentation for a description of the File Manager.
See Also
Using Command Fields

890
Chapter 31: Using Devices

Using Command Fields

You use the following fields (or combination) to format a command logging device:

Field Name Description

{UserName,n} The name of the user (User Name) who was logged on when
the command was issued.

{FullName,n} The full name of the user (Full Name) who was logged on when
the command was issued.

{Time,n} The time (in short format) when the command was issued
(hh:mm).

{TimeLong,n} The time (in long format) when the command was issued
(hh:mm:ss).

{Date,n} The date (in short format) when the command was issued
(dd:mm:yy).

{DateLong,n} The date (in long format) when the command was issued (day
month year).

{DateExt,n} The date (in extended format) when the command was issued
(dd:mm:yyyy).

{Page,n} The page that was displayed when the command was issued.

{MsgLog,n} The message sent as the Message Log property (of the com-
mand record).

You can use the following fields (in the command field) for Keyboard commands only:

{Arg1,n} The first keyboard command argument (if any).

{Arg2,n} The second keyboard command argument (if any).

...

{Arg8,n} The eighth keyboard command argument (if any).

{Native_MsgLog,n} The native language version of the message sent as the Mes-
sage Log property (of the command record).

891
Chapter 31: Using Devices

Where n specifies the display field size.

For example, you could have a device configured as follows:

Name KeyLog

Format {Date,9} {MsgLog,27} {Arg1,3} by {FullName,11}

Then a keyboard command (object, page, or system) could be created with the following
configuration:

Log Device KeyLog

Key Sequence ### ENTER

Log Message Density setpoint changed to

Resulting in an output of the following kind: "01/01/99 Density setpoint changed to 123
by Timothy Lee".

About Print Management

The Windows printer management has been designed for page-based printers: laser
printers and shared network printers. The printer driver does not print anything on the
printer until the page is full; it then prints the page. This is the preferred printing
method (when printers are shared on a network), because it minimizes the likelihood of
conflict of data when more than one operator uses the print facility at the same time.
However, this method is inappropriate when logging alarms or keyboard commands. If
you send alarm logging to this type of printer, CitectSCADA flushes the data to the
printer when the current activity completes, or when the [DEVICE]FlushTime parameter
has been exceeded (it defaults to 10 seconds). If, for example, you have one alarm occur-
ring each minute, each alarm is printed on a new page (because the default flush time is
less than the alarm frequency).
You can bypass the Windows print management by writing the output to a file. Set the
device type to ASCII_DEV and specify the file name as lpt1.dos, lpt2.dos or lpt3.dos
(depending on the port to which your printer is connected). The printer needs to be either
on a local port, or a captured network printer. When you log to this device, the data is
printed immediately on the printer with no extra form feeds.

892
Chapter 31: Using Devices

For correct logging operation, reserve one printer to be your logging printer. This printer
has to be a local printer, not on the network server. You can then send any other non-log-
ging printouts, (for example, reports) to a shared network or local printer.

Importing Equipment Tags

Defining an Equipment Hierarchy

The Equipment hierarchy provides you with the ability to design your process using a
hierarchical structure, and can facilitate your transition from a flat tag-based system to a
object-based system. During operation, the equipment hierarchy can be used to browse,
sort and filter lists of tags. When combined with variable tag browse, an operator can
search and display lists of tags based on rich data quality information including tag sta-
tuses such as manual override or control inhibit.
Each item in the equipment database is assigned a place in a hierarchy of equipment.
The hierarchy is based on the complete equipment name, with dot, or period (".") used to
signify levels of the hierarchy.
Referring to naming equipment, the length of the full name for the equipment is rec-
ommended to be less than 128 chars. The maximum length is 254 chars, however long
names can be harder to use within configuration expressions and Cicode. Each item
name (between the dots) should be less than 63 characters. The maximum number of lev-
els that can be defined in a hierarchy is 14. The equipment name field does not support
names with a space character. It is not necessary to define each level of the tree as a sep-
arate item. In the example below there is no entry for Line2, even though there are chil-
dren of Line2.
For example, if you have several items of equipment as shown below:
l Line1
l Line1.Equip1
l Line1.Equip2
l Line2.Equip1
l Line2.Equip2
Then the hierarchy will be as follows:

896
Chapter 32: Understanding Equipment in SCADA

The second example below demonstrates the hierarchy for a factory called 'Factory1"
which has three production lines each identified as Line1, Line2, and Line3. Each pro-
duction line has two assembly stations identified as Assy1 and Assy2. Each assembly
station has two conveyer belts identified as Convey1 and Convey2.
You could define the equipment structure of Convey2 at Assy2 on Line1 of Factory1 as
follows:
Factory1.Line1.Assy2.Convey2
This would create a hierarchy structure as below:

Similarly, the other items mentioned above contained in Factory1 can be built into a log-
ical hierarchy.
Once an equipment hierarchy is defined you can associate tags such as a trend, SPC,
alarm, variable or accumulator with any item in the structure. The equipment hierarchy
can also be associated to clusters to expand the flexibility even more.
See Also
Configuring Equipment
Equipment Properties
Associating Equipment

Configuring Equipment
Select one of the following methods to configure equipment in CitectSCADA:
l The Equipment Editor
l Equipment Forms

Note: Before configuring equipment for your project, you need to understand the fol-
lowing rules. These rules are around naming conventions, and the association of
equipment with clusters
• Naming Equipment in your project
• Association with Clusters

Once you have created, and/or modified equipment types and equipment using the
equipment editor or the equipment forms you need to select Update Equipment.

897
Chapter 32: Understanding Equipment in SCADA

The Update Equipment tool (available under the Equipment menu of the Project Editor)
processes the template for each piece of equipment to manage the associated con-
figuration records. When updating the equipment configuration, the associated records
are updated by modifying, adding or deleting as required.
See Also
Defining an Equipment Hierarchy
Equipment Editor
Associating Equipment

Naming Equipment in your project

The equipment name follows the same naming convention as applied to Variable Tags
with the addition of the "." character used to separate levels within the hierarchy. Note
that the "." character cannot be used as the first character in a name, nor as the last char-
acter unless it is followed by another item within the name. For example '.New-
Equipment' and 'NewEquipment.' are invalid
The equipment item name needs to begin with either an alpha character (A-Z or a-z) or
the underscore character (_). Any following characters needs to be either alpha char-
acters (A-Z or a-z), digit characters (0 - 9), backslash characters (\), or underscore char-
acters (_),:
For example the following are valid equipment names,
l _MyEquipment123
l 'My\Equipment123'
l Equip1.Equip23
l Equip1.Equip2.Equip3
However '\NewEquipment\' is invalid.

Note: If the INI parameter [General]TagStartDigit is set to 1 (the default value is

zero), Equipment names can begin with a numeric character, such as '12equ-
ipmentName'.

In addition, tags can be associated with named equipment. The equipment name follows
the same rules that exist for the I/O, Alarm and Trend Tags in terms of uniqueness:
See Also
Associating with Cluster
Configuring Equipment

898
Chapter 32: Understanding Equipment in SCADA

Association with Clusters

There are two alternative methods of assigning a cluster to equipment. Irrespective of the
method used the first step is to define the cluster in the cluster table. You then have the
option of carrying out one of the following associations:
l Use the Equipment Properties dialog box to configure your equipment, leaving the
Cluster Name field blank so that the equipment will run on all defined clusters.
l Use the Equipment Properties dialog box to configure your equipment, and select a
cluster in the Cluster Name field to restrict the equipment to run only on the selected
cluster.
When naming equipment observe the following rules regarding uniqueness of the name:
l If no cluster associated with the equipment record, then the equipment name will
have to be unique in the entire project.
l If there is more than one cluster in the system and the cluster is not defined in the
equipment record, then the compiler will generate an error.
See Also
Using Equipment
Defining an Equipment Hierarchy
Equipment Properties
Associating Equipment

Using the Equipment Editor

The Equipment Editor is an interface where you can create, modify and delete equipment
types and equipment in your system without having to write to the XML template
directly. You can view equipment types defined in your projects, including equipment
belonging to include projects.:
To configure equipment in your project using the Equipment Editor:

1. From Citect Explorer Menu -> select Equipment

2. Select Equipment Editor
3. Select the Equipment Types tab
4. Add or duplicate Equipment Types
5. Define the elements (associated tags) that belong to the Item
6. Define the fields of the element

899
Chapter 32: Understanding Equipment in SCADA

7. Define the custom parameters (if needed) for the equipment type
8. Define the Accumulators and/or Equipment states for the equipment type
9. Save the Equipment Type
10. Select the Equipment Tab
11. Create/ add, modify equipment based on an Equipment Type. Equipment will be
saved to the EQUIP.DBF
12. Select the Update Equipment tool (available from the Project Editor) to auto generate
the tags associated with equipment. This will populate the relevant tag form
The Equipment Editor will display the last view used for the opened project. If the
project has not previously been opened, the equipment type editor with no types will be
displayed.
See Also
Equipment Editor Tabs

Equipment Editor Tabs

The Equipment Editor has two tabs:
l Equipment - This workspace displays a tree of available equipment from the selected
project and its included projects. On selecting a node you can create new equipment
(linked to an equipment type), and set parameters.
l Equipment Type - This workspace consists of a list of available equipment types and
the project and included projects that contain them, and a tabbed pane in which the
types are opened for editing. Each type contains a description, one or more items, and
a list of parameters. Each item contains a collection of elements (associated tags).
To switch workspace use the tabs at the left of the Equipment Editor window. The tab
will highlight the current selected workspace.

Equipment Types
Use the Equipment type workspace to define the types of objects in your system. Equip-
ment types (groups) defined in your project act like a template that you can use as the
base configuration for that type of equipment in your project. The properties of the tem-
plate, when used to create equipment within your project, can be manually overridden
or left as the default.

900
Chapter 32: Understanding Equipment in SCADA

Note: If you created a project based on one of the StruxureWAre Starter projects an
Equipment Type – Motor is included. Use this type as an example for other Equip-
ment Types.

1 Equipment Type tree-view. Displays Equipment Types for the project as well as included
projects (excludes system include projects).

2 Equipment Type workspace. Each type has its own workspace, when open the workspace is
indicated with a tab. Click on the type name of the relevant tab to display the corresponding
workspace.

3 Add New Item button

4 Item panel. Items related to the Equipment types are listed. Select an item from the list to
view the elements that belong to it. The name of the Item selected is above the Variable tag
element. E.g. Running.

5 Add New Field button

6 Elements Panel. This panel displays the associated fields from the selected tag.The value for
these fields may be configured manually (text), through equipment references or custom
parameters.

Custom Parameters button. Click on this button to reveal the Custom parameters panel. Use
7
the panel to create and organize parameters into groups.

From the project/equipment type tree-view you can add, open, duplicate a type, rename,
move a type to a project, and delete an equipment type.
See Also
Add Equipment Types

Adding Equipment types

To Add a Type:
1. From the list of projects right-click the relevant project
2. Select Add Type.
3. The Add Equipment Type dialog will open.
4. Name the equipment type e.g. Motor_s1

901
Chapter 32: Understanding Equipment in SCADA

5. Select a different project if required. The drop down will show all user-created
include projects
6. Click OK.
The dialog will close and the tree will refresh to display the new Equipment Type. The
new type will be open for editing, where you can edit the description, configure the Items
(associated tags), custom parameters, accumulators and/or equipment states.
An Equipment type with unsaved changes is shown with an asterisk in the tab header.
See Also
Adding Items to Equipment type
Duplicate Equipment Types
Example - Using the Equipment Editor

Duplicate Equipment Types

To duplicate an equipment type:
1. Right-click the type in the type list, and from the menu select Duplicate
2. A duplicate node of the selected Equipment type will appear in the list.
3. The name defaults to a new unique name based on the original type’s name (i.e.
“Typename – _1” or similar), and the selected project defaults to the original type’s
project.
4. Rename the node.
When complete, a copy of the type with the new name is created in the selected project,
with all of the elements, parameters and items copied from the original.
If necessary move the node to the relevant project.
See Also
Adding Items to Equipment type
Modifying Equipment Types

Modifying Equipment Types

To edit an Equipment type:

l Double-click the type in the types list, or

l Right-click the type and select Open, or
l Select the type and press Enter.
To edit the description field type in the field provided. Once complete click away from
the field to commit the changes. Add, delete or modify items and elements as
required.An asterisk will appear next to the header tab indicating unsaved changes.

902
Chapter 32: Understanding Equipment in SCADA

Go to File -> Save to save the changes.

Remove Equipment Types
To delete an equipment type:

1. Right-click the equipment type in the types list.

2. Select Delete from the pop-up menu.
OR
1. Select the equipment type in the types list.
2. Press the Delete key.
Instances of the equipment type are not deleted. Once deleted, the type is removed from
the types list. If the type is currently open in a tab, the tab is closed. Once deleted, the
type is removed from the types list. If the type is currently open in a tab, the tab is
closed.
Move Equipment Types
1. To move an equipment type to any ‘included project’ right-click the type and select
Move to project.
2. The Add New type dialog will open.
3. Select the project you want to move the equipment to.
4. Click OK
The list will refresh and the equipment type will be moved to the new project
Close an Equipment Type
A type may be closed by clicking the tab’s close button, or by selecting File->Close Type
from the menu.
If there are unsaved changes to the type, you need to save the type, discard the changes,
or abort closing the type.
See Also
Adding Items

Items
An Item is an attribute of a physical device; that can be defined as equipment, within
your system. For example: the equipment type ‘Motor’ has numerous items such as Run-
ning, Start and Stop which are all attributes of a motor. Each 'Equipment.Item' reference
can be associated to a variable tag. See Variable Tag Properties for more information.
Add Item to Equipment Type

903
Chapter 32: Understanding Equipment in SCADA

1. Create a new item in an equipment type by selecting the Add New item button above
the Items list in the equipment type workspace.
2. The new item will appear in the list (i.e. “New Item #1”).
3. Name the Item
4. Select File ->Save. The item is created with a single variable element.
See Also
Define the elements belonging to the Item
Modifying Items

Modifying Items
You can also rename and remove an Item.
Rename Item
To rename an item:
1. Right-click the item in the Items list.
2. Select Rename from the pop-up menu.
The item’s name in the list becomes editable. Rename the item. The new name is com-
mitted when you complete editing the text. Save the changes.
Delete Item from Equipment Type
To delete an item right-click the item in the list and select Delete from the pop-up menu.
When an item is deleted, the item listed above or below it will then be selected.
See Also
Adding Elements to Items

Elements
Elements are a combination of tags associated with the item for a particular equipment
type. The following tag types can be added as new elements.

Note: When configuring elements you are allowed none or one of an alarm tag, var-
iable tag, and trend or SPC tag. The type drop down list available from the Add New
Element dialog will only display those element types not previously defined for that
item. In other words if you have configured an analog alarm tag for the item, the
other alarm tags will no longer be displayed in the list.

Accumulators, and equipment states though currently configured at the element level

904
Chapter 32: Understanding Equipment in SCADA

belong to the Equipment Type. When configured a new item node will display
called [Other]. All accumulators and equipment states configured for that equipment
type will be listed under this node.

l Advanced Alarms
l Analog Alarms
l Multi - Digital Alarms
l Digital Alarms
l Time-Stamped Alarms
l Time-Stamped Analog Alarms
l Time-Stamped Digital Alarms
l Variable Tags
l Statistical Process Control Tags
l Trends
Add Element to Item
1. To add a new element to an Item select the Add New Element button.
2. The Add New Element Dialog will open
3. Name the element e.g. Var_Running
4. Select a type from the drop down list provided.For example, Analog Alarm.
5. Click OK
The element is created and added to the item. The associated tag, accumulator and/or
equipment state will be created on selecting “Update Equipment” (from the project
editor).
See Also
Adding Fields to Elements
Modifying Elements

Modifying Elements
Rename Element
Rename an element by right-clicking the name of the element, and selecting Rename
from the popup menu. The new name is saved when finished editing the text.
Remove Element from Item
Delete an element by right-clicking the element, and selecting Delete from the popup
menu.

905
Chapter 32: Understanding Equipment in SCADA

A parameter can be referenced from multiple fields in an element.

You can have grouped and ungrouped parameters.
To define a parameter:
1. In the Parameters panel select a name from the drop down list provided or manually
enter the name of a parameter e.g tagprefix
2. Enter a default value for this parameter or leave it blank
3. Press Enter to save the parameter
Rename Equipment Parameters
1. A parameter can be renamed by clicking on it in the parameter list and modifying
the text. Any references to the parameter in the equipment type are updated when the
parameter is renamed.
2. Parameter names must be unique within their group. If the new parameter name is
not unique, the parameter is highlighted with a red border and a tooltip-style pop-up
that indicates that the name is not unique. The parameter is not renamed until its
name is unique.
3. As the length of the parameter field in the equipment DBF is limited, a warning is dis-
played as a message in the status area of the application when the combined length
of the parameters and a minimum space for their values exceeds this field length.
Remove Equipment Parameters
1. A parameter can be removed by right-clicking on it and selecting Delete from the
pop-up menu.
2. If the group that the parameter belongs to subsequently becomes empty, it will not be
removed.
Set Default Parameter Value
All parameters can have a default value. This is set by typing in the Value column of
the parameter list.
See Also
Parameter Groups
Adding Fields to Elements
Modifying Elements

907
Chapter 32: Understanding Equipment in SCADA

Parameter Groups
You can add, rename and remove parameter groups.
To add a parameter group:
1. Click on the Add Group button.
2. This creates a new group in the parameters list, with a default name and no param-
eters. The name is automatically selected for editing.
To rename a parameter group:
1. Right-click the header of the group
2. Selecting Rename from the pop-up menu. The group’s header becomes editable.
3. When the user completes editing the text, if update equipment has not been triggered
references to parameters from this group will be updated to reflect the new group
name. Currently if update equipment has been triggered the references will not be
updated and will revert to the original name.
To remove a parameter group:
1. Right-click its header
2. Selecting Delete from the pop-up menu.
3. This removes all of the parameters in the group as specified earlier, and then
removes the group from the parameters list.
See Also
Parameters

Equipment Editor
The equipment editor displays the equipment hierarchy for all projects.

1 Equipment tree-view. Displays equipment belonging to the selected project and

its included projects (if any).

2 Equipment description. Links to Equipment type used as template for object.

Equipment workspace. Displays available equipment fields, with referenced

3
fields pre-populated with values defined in the template (check if correct).

908
Chapter 32: Understanding Equipment in SCADA

Equipment with unsaved changes is highlighted with an asterisk.

See Also
Creating Equipment from an Equipment type
Duplicate Equipment

Create Equipment
From the Equipment list select the Name of the Project
Right-click and select New Equipment
In the Add New Equipment Dialog:

1. Name the Equipment

2. Select the Equipment Type from the drop-down list provided
3. Select the project (if different) the Equipment will belong to.
4. Click OK to save or Cancel to stop the creation process
The new equipment will be displayed with default elements and the equipment fields ref-
erenced for the linked equipment type
If necessary, drag and drop the object onto the parent equipment. The tree will refresh
and the object will be created as a child node. Click on the plus sign next to the parent
node to expand the branches.
See Also
Renaming Equipment

Duplicate Equipment
You can create a copy of an object by right-clicking its node in the tree and selecting
Duplicate from the popup menu.
This duplicate is created in the same location as the original, with a unique name (i.e.
“EquipmentName – Copy_1”).
The children of the equipment are not copied.
See Also
Delete Equipment

Rename Equipment
To rename equipment:
1. Right-click the equipment in the tree.
2. Select Rename from the popup menu.

909
Chapter 32: Understanding Equipment in SCADA

3. The name will be editable

4. Once renamed, press enter to commit the changes
See Also
Edit Equipment

Move Equipment
Move Equipment
Move equipment to another parent within the tree by dragging and dropping it. The
equipment cannot be dropped on its own child equipment. All of the equipment’s chil-
dren move with it.
Move Equipment to another project
Change the project that equipment belongs to by right-clicking its node in the tree and
selecting Move to project.
A dialog appears. Change the project that this equipment belongs to.

Close Equipment
An equipment tab may be closed by clicking the tab’s close button.
If there are unsaved changes to the equipment, you can either save the equipment, dis-
card the changes, or cancel closing the equipment.

Delete Equipment
To delete equipment:
1. Right-click the equipment in the tree.
2. Select Delete from the pop-up menu.
OR:
1. Select the equipment in the tree.
2. Press the Delete key.
The equipment and any child equipment that exist are deleted.
See Also
Edit Equipment

910
Chapter 32: Understanding Equipment in SCADA

Example - Using the Equipment Editor

The following basic example has been included to demonstrate the Equipment Editor, its
interface, and functionality.
In this example you will:

l Create a new project

l Create a new equipment type
l Create a duplicate of an equipment type
l Delete Items
l Create Items
l Configure elements and fields
l Configure accumulators and equipment states
l Create Equipment
l Instantiate Equipment

Example - Create a new Project

To create a new project based on the SxW Starter project:

1. From Citect Explorer -> select New Project

2. In the New Project dialog -> Name the project MySxW_StarterEquip
3. Leave the Create project based on starter project check box selected
4. Click OK to save the project
Citect Explorer will refresh and the new project will be listed. In the SxW starter project,
an Equipment type – Motor is provided. This will be used throughout the example.
Refer to creating projects for more information on what other components are included
in a starter project
See Also

Create a new equipment type

Example - Create a new Equipment Type

To create a new equipment type:

1. From the Citect Project Editor select -> Equipment -> Equipment Editor
2. The Equipment Editor will open.

911
Chapter 32: Understanding Equipment in SCADA

3. Select the Equipment Type Tab.

4. The Equipment Type workspace will open

Notice that the project created in the first step is displayed in the Equipment tree, with
the included equipment type template “Motor”.

Double-click Motor. The items, elements and parameters defined for that Equipment
Type will be displayed in the workspace.
The element belonging to the first item ‘Running’ will be displayed.
Select other items and view the elements defined. The items FailStart and FailStop have
an associated alarm tag defined.

912
Chapter 32: Understanding Equipment in SCADA

Scroll down in the workspace to view the fields available to the Alm.FailStart.
When ready create a duplicate of the Motor equipment type.

Example - Duplicate an Equipment Type

To duplicate an equipment type:

1. From the Types tree-view

2. Right-click the ‘Motor’ type
3. From the menu options select Duplicate. A duplicate node will be created. The
default name is immediately editable.

4. Rename to Motor2
5. Click Enter to commit name change and to open Motor2 in the workspace.

913
Chapter 32: Understanding Equipment in SCADA

Next you will delete two items.

Example - Delete an Item

In this step you will delete the items IntLock and IntBypass from the newly created type
Motor2.
To delete an item:

1. Select the IntLock Item from the list

2. Right-click and from the menu select Delete
3. The Item List will refresh.
4. Repeat for item IntBypass
Next you will add a new item.

Example - Create an Item

To create an item:

1. Click on the Add New Item button

2. A new item will be added to the list. The name is immediately editable.
3. Name the new item Speed
4. Press Enter to commit the changes
5. Go to File -> Save to save the changes
You will notice the empty variable tag element created automatically.

914
Chapter 32: Understanding Equipment in SCADA

In the next step you will configure the elements and add and delete fields.

Example - Configure Elements and Fields

In this step you will configure the variable, analog alarm and trend (associated tag) ele-
ments for the item Speed. You will also set a custom parameter (though parameters are
stored at the equipment type level).
To configure elements and fields:

1. Right-click the default name of the variable tag and select Rename

2. Name the variable tag Var.Speed and press Enter to commit the changes
3. In the Tag Name field right-click and select Equipment Fields ->From the list of
fields select Tag Prefix
This will create a reference from this tag type to the corresponding equipment field.
On selecting Tag Prefix the following {equipment.TAGPREFIX} will be inserted into the
field. Modify the value with _SPEED to make it {equipment.TAGPREFIX}_SPEED.
4. Complete the remainder of the variable tag element fields as outlined in the screen
shot below:

915
Chapter 32: Understanding Equipment in SCADA

Next you will add two new fields

5. Click on the Add New Field button
6. A new field will be added. From the drop-down list select the field name Raw Zero
Scale. Note: the fields available are those from the corresponding variable tag form.
7. Set the value to 0

8. Repeat the previous two steps – selecting Raw Full Scale and setting the value as
1000.
Next you will add the Alarm and Trend elements
9. Select the Add New Element button
10. In the Add New Element Dialog name the element AnaAlm.Speed
11. From the Type drop-down select Analog Alarms
12. Click OK

916
Chapter 32: Understanding Equipment in SCADA

The Analog Alarm element will be added to the bottom of the workspace.
13. Click on the arrow to open the element to fill in the fields.
14. For the fields Tag Name, Alarm Name and Variable Tag enter the value as {equip-
ment.TAGPREFIX}_SPEED
15. Delete the fields after Variable tag to before the High High field. For this field you
will define an un-grouped custom parameter.
16. Click on the Custom Parameter button. The custom parameter dialog will open.

17. In the Name field enter HH. Default value is 900

18. Click away from the field to commit the changes. Move the mouse onto the element
workspace to close the custom parameter dialog.
19. In the High High field, right click to open the menu. You will notice a new option
under Equipment fields called Ungrouped parameters. The parameter you defined
in the previous steps is listed here.

When complete the parameter will be referenced as follows:

917
Chapter 32: Understanding Equipment in SCADA

20. Complete the remainder of the alarm fields copying the values from the screen shot
above
Next you will add another element. This element will be associated to a trend tag.
21. Click on the Add New Element button
22. From the Add new element dialog
23. Name the Trend tag – Trend.Speed
24. Select Trend tag from the drop down list and click OK
25. For tag name – right click on the value field and select Equipment fields -> tag pre-
fix. Modify the name to be {equipment.tagprefix}_SPEED
26. Repeat for Expression field
27. From the sample period drop down select 00.00.01
28. Refer to the screen shot below when configuring the reminder fields.

29. To add the Area Field. Click the Add field button.
30. From the Name field drop down list select Area.
31. Right click and select Equipment fields and select Area.
32. Click Save to save the element and Equipment type.

918
Chapter 32: Understanding Equipment in SCADA

In the next step you will configure the accumulator and equipment states.

Example - Configure Accumulators and Equipment States

Accumulators and Equipment states are stored at the type level, even though currently
you add them as you would an associated tag element.
To configure an accumulator and equipment state:

1. Select the Add new element button

2. From the Add new element dialog name the accumulator – Accum.Speed
3. From the drop down select Accumulators
4. Click OK
The Accumulator will be open for editing. Complete the fields as pictured in the image
below:

5. Click File-> Save

919
Chapter 32: Understanding Equipment in SCADA

At this point close the Equipment Editor and then reopen it. Click on the Equipment
Types tab -> select Motor 2. You will see a new item called [Other] will be listed. The
accumulator you added is available from there as will any equipment states you con-
figure.

In this next step you will add an equipment state.

6. Select the Add new element button
7. Name the state OFF.Speed
8. Select Equipment States from the drop down list and click OK
9. In the Name field enter OFF
10. For Cluster Name, right-click in the field and select Equipment Fields -> Cluster. The
field reference will be {equipment.Cluster}
11. Leave the remainder fields blank and save the Equipment State.
In the next step you will create equipment based on the Motor Equipment Type.

Example - Create Equipment

To create Equipment:

1. Select the Equipment Tab

2. From the Equipment tree-view select the project you want to add equipment to .

920
Chapter 32: Understanding Equipment in SCADA

3. Right-click and select New Equipment

4. Name the Equipment Motor_L1
5. From the Type drop down list select Motor2
6. Confirm the project selection and click OK
7. The newly created equipment will be open in the workspace.
8. Save the Equipment – File -> Save
9. Complete the fields as shown in the image below:

10. Repeat Steps 2 to 6 - this time naming the Motor - Motor_L1_L2

11. In the Motor_L1_L2 workspace, complete the fields this time leaving the default HH
value at 900
12. Save the new motor
In the next step you will Instantiate Equipment

Example - Instantiate Equipment

To instantiate Equipment:

1. Close the Equipment Editor

2. From the Citect Project Editor-> select Equipment ->Update Equipment

3. The Update Equipment tool will run

921
Chapter 32: Understanding Equipment in SCADA

Using the Equipment Forms

Prior to v7.40 you could only configure equipment using the equipment forms available
from the Citect Editor.
To configure equipment in your project using the Equipment Forms you need to complete the fol-
lowing tasks:

1. If using the Equipment forms an Equipment XMl template with Tag Name and OUT-
PUT defined needs to be added.
2. Add Equipment Types. With the Equipment type you define the base tags and param-
eters that will then be used as a template (saved to xml file) for an 'instance' of the
equipment (object).
3. Create/ add, modify equipment instances based on an Equipment Type. Instance will
be saved to the EQUIP.DBF.
4. Select the Update Equipment tool to auto generate the tags associated with equip-
ment. This will populate the relevant tag form.
See Also
Importing Equipment Using XML Templates

Equipment Types
Use this dialog to add Equipment Types in your project.

Note: In v7.40 the Equipment Editor was introduced. Use the editor to add equip-
ment types, define elements and parameters without having to manually alter the
Equipment XML Template.

Name
The equipment type, such as pump, light, valve, etc. Enter a value of 254 characters or
less. The names in this field populate the Type drop down in the Equipment Properties
form.
Template
Filename for the XML template for the equipment type. Enter a value of 254 characters
or less. See Equipment Templates for information on defining equipment templates.

922
Chapter 32: Understanding Equipment in SCADA

Note: If no template file is specified you will need to manually create and define the
parameters belonging to Tags, Alarms, Trend, and Accumulators.

Comment
Any useful comment. Enter a value of 254 characters or less.
See Also
Configuring Equipment
Defining an Equipment Hierarchy
Equipment Properties
Associating Equipment

Equipment Properties
Equipment has the following properties:

Note: Advanced users can use the DBF plug-in for Microsoft® Excel to edit and save
records directly in the EQUIP.DBF file .

Name
The name of the equipment. The length of the complete name for the equipment is rec-
ommended to be less than 128 chars. The maximum length is 254 chars, however long
names can be harder to use within configuration expressions and Cicode. This can be
either the name of a single piece of equipment or an item of equipment within an equip-
ment hierarchy. Equipment hierarchies can be no more than 14 levels deep, and each
item should be 64 characters or less.
When naming Equipment the following rules apply:
l Equipment names need to be unique within the same cluster; however multiple
equipment with the same name can be defined, if each of the equipment is under a
different cluster.
l Equipment names cannot be the same as alarm tag names.
l Dot (.) notation may be used in equipment name to denote a equipment hierarchy.
E.g. Plant1.Filling.Tank1. Each dot delimiter denotes an extra level in the equipment
hierarchy. Up to 14 levels of hierarchy is supported. Length of individual equipment
may not exceed 64 characters.
l Individual names (delimited by a dot (.) character) within an equipment path need to
follow tag name syntax. E.g. '%', '?', '/', etc. characters are not allowed as part of the
name.

923
Chapter 32: Understanding Equipment in SCADA

l Name of root level equipment may not be the same as any cluster names. E.g. if
Cluster1 is defined in project, you cannot name the equipment "Cluster1.xxx".
l Name of the root level equipment may not be a reserved word. E.g. IF, FOR, WHILE,
END, OR, AND, etc. are not allowed as equipment name.
Type
The specific type of equipment in the system. This drop down box is populated from the
types database created by the Equipment Types form.
Cluster Name
The name of the cluster that this equipment runs on. If the Cluster Name is not set, then
this equipment will run on all clusters defined in the cluster table. The cluster should be
configured otherwise the compile will not be successful.
Tag Prefix
Designed to store the prefix that is used for tags related to the equipment. It can be used
at runtime to find or build a related tag name from an equipment.
I/O Device
The I/O Device used to communicate with this piece of equipment. Specify redundant
devices with a comma between primary and standby, for example, "IODev1,IODev2".
Enter a value of 254 characters or less.
Page
The name of the page on which this equipment appears. Enter a value of 254 characters
or less.
Help
The help context string. Enter a value of 254 characters or less.
Comment
Any useful comment. Enter a value of 254 characters or less.
The fields Scheduled and Default State are used specifically when setting schedules for
this item of equipment. For details on these fields refer to Configuring Equipment for
inclusion in Scheduler
Default State
The name of the default State of the equipment as defined in Configuring Equipment
States.
Scheduled
Specifies if the equipment is included in any scheduled actions. The options are "true" or
"false". See Configuring Scheduler.

Extended forms fields

924
Chapter 32: Understanding Equipment in SCADA

The following fields are implemented with extended forms (press F2). Note that some of
the fields listed below may be displayed in the previous section of the form.
Location
A string describing the location of the equipment. Enter a value of 254 characters or less.
Area
The area number or label to which this equipment belongs. Only users with access to
this area (and any necessary privileges) will be able to perform operations on the equip-
ment. For example, if you enter Area 1 here, operators need to have access to Area 1
(plus any necessary privileges) to perform operations on the equipment. Enter a value of
16 characters or less.
Composite
The equipment specific composite name derived from the name of the equipment (max-
imum 254 characters)
Parameters
List of parameters to be used with the template configuration. This is a property list sep-
arated by semi-colon characters. For example: MyProp1=abc; MyProp2=def;
MyProp3=123. This field is not available at runtime.
Custom1 .. Custom8
User-defined strings that can be used for filtering equipment when using the Cicode
search functions (maximum 254 characters each).
See Also
Configuring Equipment
Defining an Equipment Hierarchy
Equipment Types
Associating Equipment

Associating Equipment
Association with Tags

The following types have been extended to allow association of them with items of equip-
ment. This is configured using the "Equipment" field of the configuration dialog for each
type. The field provides a ‘picklist’ in the configuration dialog. You can select a value or
manually enter an equipment name. The compiler will check the existence of the equip-
ment referenced. The cluster should be configured otherwise the compile will not be suc-
cessful. Use this method as an alternative to referencing a cluster in the equipment
properties dialog if the equipment is defined for all clusters.

925
Chapter 32: Understanding Equipment in SCADA

l Advanced Alarms
l Analog Alarms
l Multi - Digital Alarms
l Digital Alarms
l Time-Stamped Alarms
l Time-Stamped Analog Alarms
l Time-Stamped Digital Alarms
l Variable Tags
l Statistical Process Control Tags
l Accumulators
l Trends
See Also
Configuring Equipment
Defining an Equipment Hierarchy
Equipment Properties
Associating Equipment

Importing Equipment Using XML Templates

Equipment tags can be created by importing them in much the same way as tags can be
imported using TagGen. An XML template is used to specify the fields of input and out-
put databases, and define filters and transformation rules that create tags from existing
database fields.
Equipment templates are configuration files that are linked with equipment types. Each
definition for an equipment type can have an associated template file specified.
The Update Equipment tool (available under the Equipment menu of the Project Editor)
processes the template for each piece of equipment to manage the associated con-
figuration records. When updating the equipment configuration, the associated records
are updated by modifying, adding or deleting as required. For example, a set of asso-
ciated records defined by the template may consist of a set of variable tags, alarms and
trends. When an equipment record is added, the update tool will create the associated
records. If the template is modified, the update tool will modify the associated records. If
the equipment record is deleted, the update tool will delete the associated records.
See Also
Configuring Equipment
Using Equipment
Equipment Templates

926
Chapter 32: Understanding Equipment in SCADA

Equipment XML Template

The equipment template is an XML file that uses proprietary tags and attributes to spec-
ify the fields of input and output databases, and define filters and transformation rules
that create tags from existing database fields. It uses the existing TagGen syntax rules.
The template file is linked to a specific equipment type. Equipment types can be sup-
plied from different sources such as: the SCADA product, add-on pack, external library
or user defined. Types defined by your project should use a project specific prefix to
avoid conflicting with templates from another source. You should not use 'SE' or 'LIB' as
prefixes for your template type names to avoid conflict with future product supplied tem-
plates.
It is recommended that the template file name should use the corresponding equipment
type name for consistency. When adding the template to your project, the equipment
type name should be the type name used by the template (see parameters).
An equipment template XML file consists of five sections:
l Header
l Parameters
l Input
l Outputs
l Footer
Sample template files are located in the example project directory, and include Building
Level.xml, Building Light Dimmer.xml, Building Light.xml, Building Room.xml, Plant
Level.xml, Plant Light.xml, and Plant Line.xml.
See Also
Configuring Equipment
Importing Equipment Tags

Equipment Templates: Header

The template (XML) file should contain the header section that defines the:
l version
l start of the template node
l template description
The example below can be used without modification. However the header should
reflect the actual encoding and the characters used. There are two ways to achieve this,
either:
l change the encoding in the header e.g. to iso-8859-1 (latin-1) if using ANSI characters.
or

927
Chapter 32: Understanding Equipment in SCADA

l change any ANSI characters used to their Unicode equivalent.

Example

<?xml version="1.0" encoding="utf-8"?>

See Also
Equipment Templates
Importing Equipment
Using Equipment

Equipment Templates: Parameters

The template (XML) file must contain a parameter section that defines the equipment
type parameter. Other parameters can be added within this node as needed. Refer to the
advanced section below or the 'TagGen' help topic in the product help for additional
information.
The parameter string is used to define the template type name that is referenced in other
parts of the template file. To use the example below, replace:
l [Type] with the name of your equipment type.
This should be unique across the templates used in your project(s). It must match
the value specified in the name field of the record that defines the template type in
the project.
l [TypeRef] with an abbreviation (if required) of the type name.
This is recommended to be less than 16 chars. When using an abbreviation, it
should follow the same rules as the type name, such that it has to be unique
across the templates used in your project(s).

Example

<param name="type" desc="equipment type parameters">

<string name="name">[Type]</string>
<string name="ref">[TypeRef]</string>
</param>

See Also
Equipment Templates
Importing Equipment
Using Equipment

928
Chapter 32: Understanding Equipment in SCADA

Equipment Templates: Input

The template (XML) file should contain an input section that defines the input node for
the equipment database (DBF) file source. The input node is defined within the XML tem-
plate node and contains the list of database fields that are to be available for use by the
template. Only one input node can to be defined within the template.
The example below can be used without modification and lists the complete set of the
available data fields from the equipment database (DBF) file.
There are three built-in functions that can be used to manipulate strings in the XML tem-
plate:
l SubString(string, start, count)
l Split(string, delimiter)
l ToProperty(string, separator, delimiter)
These functions are the same as used in the TagGen XML templates and are described
in Built-in Functions.

Example

<input name="equipment" file="equip.dbf" desc="Equipment Database">
<field name="name"></field>
<field name="cluster"></field>
<field name="type"></field>
<field name="iodevice"></field>
<array name="iodevice_list">{Split('{iodevice}',',')}</array>
<field name="tagprefix"></field>
<field name="area"></field>
<field name="page"></field>
<array name="page_list">{Split('{page}',',')}</array>
<field name="help"></field>
<field name="location"></field>
<field name="comment"></field>
<field name="scheduled"></field>
<field name="defstate"></field>
<field name="param"></field>
<array name="param_list">{ToProperty('{param}','=',';')}</array>
<field name="custom1"></field>
<field name="custom2"></field>
<field name="custom3"></field>
<field name="custom4"></field>
<field name="custom5"></field>
<field name="custom6"></field>
<field name="custom7"></field>
<field name="custom8"></field>

929
Chapter 32: Understanding Equipment in SCADA

</input>

See Also
Equipment Templates
Importing Equipment
Using Equipment

Equipment Templates: Outputs

The template (XML) file can contain 1 or more output sections that define the con-
figuration records that are to be created in other database (DBF) files. The output nodes
are defined within the template node and contain the list of database fields that are to be
updated in the new record. An Output Node should be added for each record that is to
be created, such as a variable tag, alarm, trend, etc.
The values specified for each of the Output Field elements will be written to the database
(DBF) field of the output file. Values from input fields and parameter strings can be ref-
erenced within this section to construct the resulting value for the output record field.
Each output node must have a unique output name specified across the records in the
template.
Refer to the following available output databases section for specific details on each of
the available output databases and other advanced topics.
The example below shows a sample for an output to the variable database (DBF). For
each output section, the field names specified must include the Output Common fields
and the fields specific to each Output Database.
To use the example below, replace the following in your template:
l [FileRef] with a short string reference for the output destination database. Such as
'Var', 'Trend', 'AlmDig', 'Menu', etc. Examples are provided with the list of available
databases
l [RefID] with a unique index (1, 2, 3, etc.) or a related string value for the entry (such
as ON, STOP, etc.) for the specific output record.
l [TypeRef] with the abbreviation of the type name as defined in the parameter section.
This may need to be an abbreviation of the full type name as the total length of [Type-
Ref].[RefID] must be 32 chars or less to fit the 'taggenlink' field.

Example

<output name="[FileRef].[RefID]" file="variable.dbf" filter="'{equipment.type}=

930
Chapter 32: Understanding Equipment in SCADA

{type.name}'">
<field name="taggenlink" load="true">[TypeRef].[RefID]</field>
<field name="linked">1</field>
<field name="editcode">11</field>

<field name="name" key="true">{equipment.tagprefix}[Tag Suffix]</field>

<field name="type">[Tag Data Type]</field>
<field name="unit">{equipment.iodevice_list[0]}</field>
<field name="addr">[Tag Address]</field>
<field name="comment">[Tag Comment]</field>
</output>

See Also
Equipment Templates
Importing Equipment
Using Equipment

Equipment Templates: Output Node

The output node contains the following attributes:
l Output Name
The output node name attribute should be unique across the output nodes in the
template. One way to achieve this consistently is to use the format of [FileRef].
[RefID] (as outlined in Equipment Templates: Outputs). The recommended value
for [FileRef] is listed with each output database.
l Output File
The output node file attribute refers to the filename for the associated database
(DBF) file.
l Output Filter
The output node filter attribute is used to match the equipment defined in the
equipment database (DBF). The filter value needs to match the type name specified
in the type filed of the equipment. The recommend value for the filter is the param-
eter string for the type defined at the beginning of the template file.
Each output node defines the associated Output Common fields and Output Data-
base fields for the record that is to be created.
See Also
Equipment Templates: Outputs
Equipment Templates
Importing Equipment
Using Equipment

931
Chapter 32: Understanding Equipment in SCADA

Equipment Templates: Output Field

The output node fields can reference the values from the associated equipment input rec-
ord. The following is a list of the fields that can be used based on the input section of the
template (XML) file. The value is referenced using the syntax '{equipment.<Field Name>}'
where <Field Name> can be used from the list below:

Input Name Description

Area The security area

Cluster The associated cluster

Comment The configuration comment

custom1 .. 8 The custom runtime fields

Defstate The default state for the scheduler

Help The help reference

Iodevice The list of IO devices

iodevice_list[n] The array of IO devices, where n in the zero based index

Location The location reference

Name The full equipment name

Page The list of pages

page_list[n] The array of pages, where n in the zero based index

Param The list of parameters

param_list[name] The list of parameters, where name is the specific parameter name

scheduled The configuration of scheduler participation

Tagprefix The prefix for the associated tags

Type The equipment type

See Also
Equipment Templates: Outputs
Equipment Templates
Importing Equipment
Using Equipment

Equipment Templates: Output Common Fields

There are three common fields that should be used with each output node:

932
Chapter 32: Understanding Equipment in SCADA

l Output Tag Gen Link

The taggenlink field specifies a name that is used to identify the record in the data-
base so that it is linked with the template. This allows the record to be found for
an update or delete operation.
The value should include a unique reference to the template type and a reference
to the output record within the template. The recommended way to achieve this
consistently is to use the format of [TypeRef].[RefID] (as outlined in Template Sec-
tion: Outputs).
l Output Linked
The linked field should be set to '1'.
l Output Edit Code
The edit code is a number that represents the bitmask of the database (DBF) fields based
on the physical order in the DBF file. When the bit in the mask is set, the corresponding
field will be marked read-only in the Project Editor form. If no fields are to be marked as
read only, then this field can be left blank or removed from the output definition.
The algorithm to determine an edit code is listed in Equipment Templates: Output Data-
base. The combined edit code for few fields is a sum of edit codes of all fields. For exam-
ple, the edit code for first (edit code = 1), second (edit code = 2), fourth (edit code = 8) and
20th fields (edit code = 524288) is 1 + 2 + 8 + 524288 = 524299, or in decimals: 0x00001
(edit code for first field) + 0x00002 (edit code for second field) + 0x00008 (edit code for
third field) + 0x80000 (edit code for 20th field) = 0x8000B
See Also
Equipment Templates: Outputs
Equipment Templates
Importing Equipment
Using Equipment

Equipment Templates: Output Database

Below is a list of available output databases and the corresponding output files and out-
put file references to use in your equipment template.

Database Output File Output File Reference

Accumulators file="accums.dbf" Accum

Advanced Alarms file="advalm.dbf" AdAlm

Alarm Categories file="category.dbf" ACat

Analog Alarms file="anaalm.dbf" AAlm

Devices file="devices.dbf" Dev

933
Chapter 32: Understanding Equipment in SCADA

Database Output File Output File Reference

Digital Alarms file="digalm.dbf" DAlm

Equipment file="equip.dbf" Equip

Equipment States file="eqstate.dbf" State

Events file="events.dbf" Event

Fonts file="fonts.dbf" Font

Groups file="groups.dbf" Group

Labels file="labels.dbf" Label

Local Variables file="locvar.dbf" LVar

Menu Configuration file="pagemenu.dbf" Menu

Multi-digital Alarms file="argdig.dbf" MDAlm

Parameters file="param.dbf" Param

ReMapping file="remap.dbf" Remap

Reports file="reports.dbf" Rep

SPC Tags file="spc.dbf" SPC

Time Stamped Alarms file="hresalm.dbf" TSAlm

Time Stamped Analog Alarms file="tsana.dbf" TAAlm

Time Stamped Digital Alarms file="tsdig.dbf" TDAlm

Trend Tags file="trend.dbf" Trend

Variable Tags file="variable.dbf" Var

To determine acceptable field names for Tags and Alarms

To determine the acceptable field names and, respective edit codes, either open citect.frm
and find the respective output file without an extension (for example, advalm for
advanced alarms) or open the respective dbf in the DBF Add-In. All fields listed in the
dbf are acceptable field names. The edit code of the first field in the table is always 1.
The edit code of the fields other than 1 equals the edit code of the previous field times 2
(i.e. the edit code of the second field is 2, third - 4, fourth - 8 and so on).
See Also
Equipment Templates: Outputs
Equipment Templates
Importing Equipment
Using Equipment

934
Chapter 32: Understanding Equipment in SCADA

Equipment Templates: Footer

The template (XML) file should contain a footer section to help ensure that the XML is
formatted correctly. The footer contains the end marker for the template node.
The example below can be used without modification.

Example

</template>

See Also
Equipment Templates
Importing Equipment
Using Equipment

Troubleshooting Equipment Templates

After running Update Equipment there are no records created in the output database
files
Check that the type name defined in the first parameter of the template file is the same
as the name defined for the Equipment Type record of the project.
After running Update Equipment there are duplicate records created in the output data-
base files
Check that the 'taggenlink' field in the output section of the template was not changed.
When this field is changed, any previously generated entries need to be manually
deleted.
See Also
Equipment Templates
Importing Equipment
Using Equipment

935
Chapter 32: Understanding Equipment in SCADA

936
Chapter 33: Using External Databases
You can store and update runtime data from your plant floor in a database external to
CitectSCADA. You can also use CitectSCADA to send information from the database
(such as a recipe) to I/O Devices in your plant.
CitectSCADA supports two types of databases:
l dBASE databases
l SQL databases
By using an external application to read and write the same database records, you can
effectively interface to an external application through, for example, a relational data-
base.
CitectSCADA provides two methods of communication with a database:
l using Vijeo Citect Devices
l using the SQL class of Cicode functions
Devices are most useful when the automatic reporting and logging features of Citect-
SCADA are used.

dBASE databases
The dBASE file format has become an industry standard for data storage, and Citect-
SCADA supports the standard dBASE format. You can use any database editor (that sup-
ports dBASE III files) to create a database, and to read and write database records.
To connect to a database, you need to define a CitectSCADA Device. Devices specify the
format and location of the database, for example:

Name Recipe

Format {Name,16}{Water,8}{Sugar,8}{Flour,8} {Salt,8}{Yeast,8}{Milk,8}

Header Name

File [DATA]:RECIPE.DBF
Name

Type DBASE_DEV

937
Chapter 33: Using External Databases

Com- Recipe Device (dBASE file)

ment

SQL databases
SQL (Structured Query Language) also has become an industry standard. SQL is a com-
mand language that allows you to define, manipulate, and control data in SQL data-
bases - and in other relational databases. Most database servers support SQL. SQL gives
you direct access to database servers on other platforms, such as computers, mini-com-
puters, and mainframe computers.
You can use the CitectSCADA Device functions to set up the format and locations of
each of your SQL databases. Alternatively, use the SQL functions for direct control over
SQL transactions.
You need to define a CitectSCADA Device to specify the format and location of the data-
base, for example:

Name Recipe

In the Format field, specify the field names in the SQL database, for example:

For- {Name,16}{Water,8}{Sugar,8}{Flour,8} {Salt,8}{Yeast,8}{Milk,8}

mat

The Header is the database connection string for ODBC connection, for example:

Header DSN = ORACLEDATABASE

Enter the database table name in the File Name field:

File Name RECIPE

Type SQL_DEV

Comment Recipe Device (SQL)

See Also
Using Structured Query Language

938
Chapter 33: Using External Databases

Using Structured Query Language

You can use Structured Query Language (SQL) functions for direct access to an SQL data-
base, instead of accessing the database as a Device. Using direct database access can pro-
vide greater flexibility. The SQL functions provide access to SQL databases through any
ODBC-compatible database driver, for example MS Access, FoxPro, Paradox, etc.

NOTICE
To avoid SCADA and database PERFORMANCE DEGRADATION please consider:

- Build queries that require an acceptable use of system resources (memory, CPU,
threads).
- Limit scope of queries with parameter-driven WHERE clauses.
- Avoid using SELECT * to return all columns.
- Do not perform queries with null values for date time parameters.
- Try to balance load between relational database management systems (RDBM) and
SCADA, for example consider sorting data on the client side rather than the server side.
- Consider using stored procedures to minimize the number of round trips to the server.

Failure to follow these instructions can result in equipment damage.

SQL functions provide absolute control and flexibility over connections and queries. Que-
rying a database via the Device system is slower than constructing a query via a SQL
function due to the generic nature of a device.
CitectSCADA 7.30 introduces the use of ADO.NET library of SQL functions, which pro-
vides a modern approach to data access, which can be programmed using any of .NET
managed languages, and is supported and further developed by its manufacturer. Fur-
ther the new ADO.NET approach enables you to have multiple recordsets per con-
nection, and multiple queries per recordset. Previous versions restricted you to 1
recordset per connection and 1 query per connection. More importantly the new imple-
mentation delegates connections, disconnections and query executions to separate appli-
cation threads meaning that SQL queries need no longer be blocking actions.
The technology facilitates connections to databases from various vendors and obtains
data sets by executing either ANSI SQL commands or any database specific dialects of
SQL (if a dedicated provider is used) such as T-SQL or PL/SQL.
Connections can be established to databases which:
l Have an ODBC driver
l Have an OleDB provider
l Use MS SQL Server

939
Chapter 33: Using External Databases

Specifically, the Cicode SQL DB interface can be used to connect to either Historian or
Historical Alarm databases as long as they use databases fulfilling one of the above con-
ditions and store their data in types that can be read by the Cicode SQL interface.
See Also
Limitations When Using Legacy SQL Functions
Database Connection Objects
Connecting to an SQL database
Basic SQL Scenarios
Alarm Server Database Specification

Limitations When Using Legacy SQL Functions

The SQL library used in CitectSCADA prior to release 7.30 has a number of limitations
and these are documented in the Knowledge Base (article Q4014). This library was not
designed to handle large scale SQL data transactions. For large volumes of data it is rec-
ommended that CitectSCADA Reports (CitectHistorian) be used. Note that new functions
using ADO.NET do not share these limitations.
If you intend to use the embedded SQL library in CitectSCADA, consider the following:
l Use "Simple" model for a SQL database to limit transaction information logging to
transaction log file.
l Use the fixed size of transaction log to restrict the log file growing.
l Back up the database regularly to keep the transaction log size under control. When
SQL Server finishes backing up a database or its transaction log, it automatically trun-
cates the inactive portion of the transaction log. If the transaction log file is full, your
database transactions will cease.
l Keep working tables as small as possible. When CitectSCADA SQL adds or appends
a new row to data table, it uses SELECT * first to get column information. If there are
hundred and thousand of records in the table, this action will certainly hinder the per-
formance.
l Use SQL Server trigger to remove records from the working tables to the permanent
tables. In this way, sizes of the working tables that are directly interfaced with Citect
are not growing unrestricted.

Database Connection Objects

The new implementation introduces database connection objects as containers for param-
eters describing SQL connections to the database.
Users can execute SQL queries via DB connection objects and return either disconnected
SCADA recordsets or the connected SCADA recordset holding results of the queries.

940
Chapter 33: Using External Databases

Disconnected SCADA recordsets have no direct association to their DB connection

objects and their lifetime is not limited by the DB connection objects’ lifetime. They
should be closed in Cicode when no longer necessary.
The connected SCADA recordset is directly associated to the DB connection object. The
relation is 1-1 and there cannot be more than one connected recordset per one con-
nection. The associated connected recordset is called further a default recordset.
SQL functions from the previous SCADA are kept and their functionality, from a user’s
point of view, is the same as before (see Cicode functions for minor exceptions).
A set of new Cicode SQL functions is introduced together with the new ADO interface.
These new functions can be divided into four categories:
l Creation/connection – functions servicing separate creation of DB connection objects
and separate connection initialization
l Multiple recordsets per connection – functions enabling users to obtain and use han-
dles to disconnected recordsets (the old database access methods limited the number
of recordsets per connection to one)
l Parameterization – functions helping to provide more secure way of building SQL
queries
l Multiple queries per connection – functions enabling users to obtain and use handles
to queries (the old database access methods limited the number of queries per con-
nection to 1)
See Also
Basic SQL Scenarios

Basic SQL Scenarios

Two basic scenarios of using the Cicode SQL database interface are:
l Accessing and analyzing data in a CCicode procedure
l Accessing and displaying data on a graphics page

Accessing data in a CCicode procedure

The CCicode SQL database interface enables users to create a connection object, connect
it to a database, execute SQL queries and step through records in either the default con-
nected recordset, using legacy Cicode functions, or a disconnected recordset, using the
new Cicode functions. See examples in SQLCreate and SQLConnect Cicode function
descriptions.

941
Chapter 33: Using External Databases

In previous versions, this scenario could be problematic because connecting to databases

and accessing data might hold SCADA Kernel’s Tasks and temporarily block the entire
application. The new implementation delegates connections, disconnections and query
executions to separate application threads. The SCADA kernel thread, which initializes
one of those actions, is suspended and waits for synchronization while other threads
can continue processing their tasks.

Displaying data on a graphics page

Typically this scenario is used when the result of a query is displayed on a graphic page
in the form of a table with the possibility of scrolling forward and backward through the
data.
In this case the data from a disconnected SCADA recordset is displayed on a graphic
page using the SQLGetField and SQLIsNullField SQL functions.
Data pertaining to the SQL query is copied to the disconnected SCADA recordset just
after executing the query. This behavior means that there is no additional data fetching
when you iterate through disconnected recordsets later.

Note: When executing queries, there is a direct relation between data size, execution
time and memory consumption: the more data fetched the longer execution time and
the larger amount of physical memory taken by the SCADA recordset. Take care to
design your queries so that they return only amount of data compatible with avail-
able resources and performance expectations.

Since recordsets reside in memory while active, it is your responsibility to close unused
SCADA recordsets when they are no longer required.
Disconnected SCADA recordsets don’t depend on the existence of either the database con-
nection object or the SQL connection to a database. The recordsets can therefore be seen
as disconnected immediately after executing a query. They do not synchronize with the
source database after that point. Afterwards, the SQL connection to a database can either
stay open or be closed.
Connecting to an SQL database
Executing SQL commands
Using a transaction
Expressing dates and times in SQL

Connecting to an SQL database

Using legacy functions

942
Chapter 33: Using External Databases

Before you can use SQL commands, you need to connect to the SQL database. In pre-
vious versions of CitectSCADA you would use the SQLConnect function to provide the
access. It has the format:

SQLConnect(sConnect);

where sConnect is the connection string, for example:

INT hSQL;
hSQL = SQLConnect("DSN=DBASE_FILES;DB=C:\ODBC\EMP;LCK=NONE;CS=ANSI");
! Connect to a dBASE Compatible Database File.

INT hSQL;
hSQL = SQLConnect("DSN=EXCEL_FILE;DB=C:\ODBC\EMP;FS=10");
! Connect to an Excel File.

INT hSQL;
hSQL = SQLConnect("DSN=ORACLE_TABLES;SRVR=X:ACCTS;UID=SCOTT;PWD=TIGER");
! Connect to an Oracle Database.

Refer to the documentation that accompanied your SQL server for details about con-
necting to an SQL database.
To close a legacy database connection, use the SQLDisconnect function with the handle
to the connection object.

Using ADO.NET functions

The new interface requires two calls in order to open a connection to a database. The
first call uses SQLCreate which prepares the database connection object. A second call
SQLOpen establishes the SQL connection to the database.
SQLOpen can be used to reopen previously closed connections.

Note: SQL connections to databases can be closed sometimes by either databases or

ADO.NET when certain conditions are fulfilled (for example through idle time expi-
ration, active pooling mechanism logic).

To close an ADO.NET database connection, use the SQLClose function to close the con-
nection and then the SQLDispose with the handle to the connection object.
New functions can be used with the pre-existing ones. However, as a good pro-
gramming practice, it is advised not to mix the old and the new interface. A hardware
alarm will be generated if a SQLDisconnect is detected when there are connections
opened with SQLCreate/SQLOpen, or if SQLClose/SQLDispose are detected and there are
connections opened with SQLConnect.

943
Chapter 33: Using External Databases

See Also
Executing SQL commands
Working with recordsets

Working with recordsets

ADO.NET uses disconnected recordsets to view data from a database. These are created
by the function SQLGetRecordset. A handle to the created recordset is returned and can
be used in subsequent functions.
To access data from a specified column and row, use the SQLGetField function with a
recordset handle. Null detection can be performed by using the new SQLIsNullField func-
tion. See the code example in the SQLCreate function for a simple example.
ADO.NET allows you to create many queries per single database connection object. Que-
ries are created using the SQLQueryCreate function and disposed by the SQLQue-
ryDispose function.
See Also
Parameterized Queries

Parameterized queries
Parameterized queries are now possible with the new ADO.NET SQL interface. This pro-
vides the possibility to define queries with parameters which can be substituted later by
concrete values (integers, reals or strings). This is especially useful when a query is built
using end user data, such as user names and passwords, inserted via graphical pages
(forms). When correctly applied, parameterized queries can prevent SQL injection
attacks.
Parameters are defined for each DB connection object and concrete values are substituted
into queries just before executing the function from the SQLExec family.
The parameters exist in DB connection objects as long as the objects exist. The function
SQLParamsClearAll can be used to remove all parameters from a specified DB con-
nection object. There is currently no way to iterate through all existing parameters in a
DB connection object nor to remove a single selected parameter from the object’s col-
lection.
Each database provider (ODBC, OleDb, SQL Server) implements parameterized queries
in different ways. As SQL queries can be very complicated, it is difficult to provide a
generic converter for unifying the parameterization syntax. So to use parameterized que-
ries, you should have knowledge of how they work on a particular provider and struc-
ture your Cicode accordingly.

944
Chapter 33: Using External Databases

See the examples in SQLParamsSetAsInt, SQLParamsSetAsString and SQLPar-

amsSetAsString.

Executing legacy SQL commands

SQL allows you to manipulate data in a non-procedural manner; you specify an oper-
ation in terms of what is to be done, not how to do it. SQL commands allow you to:
l Create tables in the database.
l Store information in tables.
l Select exactly the information you need from your database.
l Make changes to your data and to the structure of a table.
l Combine and calculate data.
The SQLExec() function executes any SQL command that your SQL server supports. For
example, to create a database table, you would execute the SQL "CREATE TABLE " com-
mand:

SQLExec (hSQL, "CREATE TABLE recipe ('Name' CHAR(16), 'Water' CHAR(8),

'Sugar' CHAR(8), 'Flour' CHAR(8), 'Salt' CHAR(8), 'Yeast' CHAR(8), 'Milk' CHAR(8))
");

To add records into the database table, use the "INSERT INTO" command. The com-
mand has the following syntax:

INSERT INTO <filename> [(<col_name>, . . .)] VALUES (<expr>, . . .)

This command adds the values for each field in the table, for example:

SQLExec(hSQL, "INSERT INTO recipe VALUES ('Bread', '10', '5', '7', '1', '1', '2')");

Column names are optional; however, if you omit column (field) names, the values are
inserted into the fields in the same order as the values.
To read data from an SQL database, use the SQL "SELECT" command. You can use the
"SELECT" command to read an entire set of records, or a row, from the table. You can
then use the SQLGetField() function to read the data in each field, for example:

SQLExec(hSQL, "SELECT * FROM recipe WHERE NAME = 'Bread'");

If SQLNext(hSQL) = 0 Then
PLC_Water = SQLGetField(hSQL, "WATER");
PLC_Sugar = SQLGetField(hSQL, "SUGAR");
PLC_Flour = SQLGetField(hSQL, "FLOUR");
PLC_Salt = SQLGetField(hSQL, "SALT");
PLC_Yeast = SQLGetField(hSQL, "YEAST");

945
Chapter 33: Using External Databases

PLC_Milk = SQLGetField(hSQL, "MILK");

END

To delete database records, use the SQL "DELETE" command. The command has the fol-
lowing syntax:

DELETE FROM <filename> [WHERE <conditions>]

This command deletes values from the table, for example:

SQLExec(hSQL, "DELETE FROM recipe WHERE NAME = 'Bread'");

SQLBeginTran(hSQL); ! Begin the transaction

SQLExec(hSQL, "UPDATE recipe SET water = '12' WHERE NAME = 'Bread'");
SQLExec(hSQL, "UPDATE recipe SET milk = '1' WHERE NAME = 'Bread'");
IF . . . THEN
SQLCommit(hSQL); ! Commit the transaction
ELSE
SQLRollBack(hSQL);! Cancel the transaction
END

Check the ODBC-compatibility level of your database driver if you cannot use trans-
actions.
See Also
Expressing dates and times in SQL

Expressing dates and times in SQL

The way in which SQL dates are expressed depends upon the particular database sys-
tem. With dBASE, you normally specify a date in braces, for example {02/18/95}. For
Oracle, use the format: to_date(`02/18/95', 'MM/DD/YY'). Other ODBC drivers might
require another format - a common ODBC format is: `YYYY-MM-DD'.

Note: Date references in an external database have to be based on the Gregorian

946
Chapter 33: Using External Databases

Calendar, or the database tables needs to be exported to text files before use in Citect-
SCADA. Dates in Microsoft Access database tables exported as text files are stored as
Gregorian values.

See Also
Conversions between database and Cicode types

Database independent date-time syntax

For database independence, you can use the following syntax for dates and times:

[<format>'YYYY-MM-DD HH:MM:SS.FFFFFF']

where:
l <format> (the first character after the opening square bracket) needs to be one of the
following:
l d - date
l t - time
l dt - date and time.
Whether you are specifying a date, time, or date and time, you need to provide the com-
plete 26 character string, for example:

[d'1995-02-18 00::00.000000']

Refer to the documentation that accompanied your SQL server for further information
about SQL commands.

Conversions between database and Cicode types

Any type of database field can be requested in statements. SCADA converts values of the
fields to MBCS 8-bit strings which may not always be possible. For example:
l Single byte database strings or numbers can be converted to MBCS 8-bit strings, proc-
essed and displayed by SCADA
l Multi-byte strings can be converted to MBCS. Processing and displaying can be done
as far as: SCADA supports MBCS and is properly parameterized, OS has Language
packs installed and is properly parameterized
l Blobs (binary large objects) cannot be converted.
An error is returned when conversion to 8-bit strings is not possible.

947
Chapter 33: Using External Databases

NOTICE
LACK OF DATA CONVERSION

Ensure that all your database fields can be converted. Otherwise, when conversion is pos-
sible, some data may not be converted, but there is no indication that has occurred. For
example when SCADA isn't properly parameterized.

Failure to follow these instructions can result in equipment damage.

There are a large number of custom DB types that need macros/functions to be called on
the database side of the SQL connection for their proper conversion to strings.

MS SQL Server DB types and only their subset

Format of the CiCode string returned

MS SQL Server DB type by either SQLRecordsetGetField or
SQLGetField*

CHAR(), NCHAR(), VARCHAR(), NTEXT, NVARCHAR The text is converted to MBCS 8-bit string.
(), TEXT, XML

BIT, BIGINT, INT, SMALLINT, TINYINT Integer as a text string

DECIMAL(,), FLOAT, NUMERIC(,), REAL, MONEY, Real as a text string.

SMALLMONEY

UNIQUEIDENTIFIER A unique id stored as a 16-byte binary

value and usually converted to a GUID-like
string

SQLVARIANT The sqlvariant is a type which can encap-

sulate other types. The format of the result-
ant string depends on the encapsulated
type and ability to convert it to a string.

DATE, DATETIME, DATETIME2(), DATE- Date and time as a string. Only one format
TIMEOFFSET, SMALLDATETIME, TIME() and UTC. If users wish to have date/time
in a different format, have to use DB side
conversion macros/functions in their
SELECT queries.

No conversion possible. The returned

string is empty. An error is set during the
query execution by either SQLExec()
/SQLNext() or SQLGetRecordset().
Moreover, Geography, Geometry and Hier-
BINARY(), VARBINARY(), IMAGE, GEOGRAPHY, archyID need additional CLR types not dis-
GEOMETRY, HIERARCHYID, TIMESTAMP tributed with .NET platform. If need to use
objects of those types in queries directly
(without explicit conversions by macros),
the CLR types need to be installed either
separately or with SQL Server. Otherwise
such queries return error 307. A separate

948
Chapter 33: Using External Databases

Format of the CiCode string returned

MS SQL Server DB type by either SQLRecordsetGetField or
SQLGetField*

setup with the CLR types can be down-

loaded from http://ww-
w.microsoft.com/en-
us/download/details.aspx?id=30440.

MS Access types and only their subset

Format of the CiCode string returned

MS Access DB type by either SQLRecordsetGetField or
SQLGetField*

Text, Memo, Hyperlink, Lookup Wizard The text is converted to MBCS 8-bit string.

Yes/No, AutoNumber Integer as a text string

Number, Currency Integer as a text string or (if necessary)

Real as a text string.

Date/Time Date and time as a string. Only one format

and UTC. If users wish to have date/time
in a different format, have to use DB side
conversion macros/functions in their
SELECT queries.

No conversion possible. The returned

string is empty. An error is set during the
OLE Object
query execution by either SQLExec()
/SQLNext() or SQLGetRecordset().

* The string has to be shorter than 255 characters, otherwise an error is thrown.
The Cicode runtime engine tries to automatically convert strings to target data types
when a cast operation is necessary. The following conversions are potentially allowed:
STRING to INT and STRING to REAL.

949
Chapter 33: Using External Databases

950
Chapter 34: Exchanging Data with Other Appli-
cations
You can transfer data between CitectSCADA and other software for storage, analysis,
and post processing, or to control and tune your CitectSCADA system.
CitectSCADA uses the following methods to exchange data:
l dynamic data exchange (DDE), where CitectSCADA can act as a:
l DDE server providing tag values to requesting clients
l DDE client to request data from other applications.
l open database connectivity (ODBC), where CitectSCADA functions as an ODBC
server, allowing other applications to read CitectSCADA variables directly.
l By using a common external database, where CitectSCADA and other applications
use the same database to store and share information.
CitectSCADA also supports importing and linking variable tag data from external data-
bases. See Linking, Importing, and Exporting Tags.

Using DDE (Dynamic Data Exchange)

Microsoft Windows DDE allows the continuous and automatic exchange of data
between different Windows applications on the same machine without the need for any
user intervention. For example, your company's Production group might use a spread-
sheet application to graphically represent plant-floor data (product output). This could
be dynamically updated with the latest live data using DDE to read values directly from
CitectSCADA.
Windows DDE uses the DDE protocol to send messages between applications that share
data.
Dynamic Data Exchange occurs between a DDE client application (which requests the
data or service) and a DDE server application (which provides the data or service). The
DDE Client starts the exchange by establishing a conversation with the DDE server, and
requesting data or services. The DDE server responds to these requests by providing the
data or services to the DDE Client. The DDE Client terminates the conversation when it
no longer needs the DDE server's data or services.

Note: As the DDE protocol is not designed for high-speed data transfer, the use of

951
Chapter 34: Exchanging Data with Other Applications

DDE is only appropriate when data communication speed is not critical.

l For information about DDE conversations, see DDE conversations and client syntax.
l To establish a DDE conversation between applications on the same computer, see Set-
ting up DDE conversations.
l To establish DDE conversations between applications running on different computers
over the same network, see Network DDE.
l To establish DDE Conversations with the CitectSCADA tag database directly, see Con-
necting to the CitectSCADA tag database using DDE.

Note: When reading or writing to CitectSCADA tags using DDE, you might unknow-
ingly add to your CitectSCADA license point count. Once the dynamic point count is
greater than the license point count, the software protection mechanism will ter-
minate CitectSCADA runtime. Therefore, when accessing tags via DDE, it's impor-
tant to remain aware of how many points you have used. For details, see license
point count in the Installation and Configuration Guide.

DDE conversations and client syntax

Two applications participating in Dynamic Data Exchange are said to be engaged in a
DDEconversation. The application that initiates the conversation is the DDE Client, and
the application that responds to the DDE Client is the DDE server.
An application can have several DDE conversationsrunning at the same time. The appli-
cation can be the DDE Client in some conversations (requesting data or services), and
the DDE server (the data/service provider) in others. Each request or response in a DDE
conversationspecifies the data or service to be sent or received.

Note: A DDE conversation is sometimes referred to as a channel or a link.

The syntax sent by the DDE Client when it tries to establish a DDE conversation with
the DDE server, consists of three parts:
l The name of the application to retrieve the data from.
l The file or topic name which contains the data to be retrieved.
l The cell range, value, field, or data item that's being requested.
These are combined in the format:

<DDE server application name>|<DDE Topic name>!<DDE Data item

952
Chapter 34: Exchanging Data with Other Applications

name>

where:
l <DDE server applicationname> identifies the DDE server application.
l | (pipe character) separates the DDE server application name from the DDE Topic
Name with no spaces between them.
l <DDE Topic name>identifies the context of the data. For DDE Servers that operate on
file-based documents, DDE topic names are typically file names. For other DDE
Servers, they are other DDE application-specific strings.
l ! (exclamation character) separates the DDE Topic Name from the DDE Data item
name with no spaces.
l <DDE Data item name>is a string that identifies the data item that a DDE server can
pass to a DDE Client during a DDE transaction. In some instances, the DDE Data
item name is optional. Refer to the DDE application documentation for particulars.

Note: In the DDE Client syntax structure example above, every placeholder shown
inside arrow brackets ( <placeholder> ) has to be replaced with the actual name of
the item that it describes. Do not include the arrow brackets and the placeholder
words they contain in the statement, and are shown here only for your information.

As the DDE protocol was designed in an era before long file names, DDE only supports
the use of short (8 character) file names. To overcome this limitation, enclose the three
parts of the DDE syntax within single quotes respectively. For example:

Citect|Variable!'Process Variable 1'

This instructs DDE to treat the characters within the quotes as strings, thus permitting
them to contain long file names, the space character (), the pipe character (|), the excla-
mation or bang character (!), or any other non alphanumeric character.
See Also
Setting up DDE conversations

Setting up DDE conversations

The DDE protocol itself does not support the launch of applications, so both the DDE
Client application and the DDE server application needs to already be running before
any DDE conversations can occur (unless the calling application is coded to detect and
launch the DDE server application when necessary).

953
Chapter 34: Exchanging Data with Other Applications

At the beginning of a DDE conversation, a DDE Client requests the services of a DDE
server using DDE Client syntax (which contains the DDE server application name, topic
or file name, and the data item name in the request). For DDE Client syntax details, see
DDE conversations and client syntax.
To set up an application as a DDE Client, that is, to request data from a DDE server
application, you need to use appropriate values in the DDE Client syntax as follows:
DDE server application name
The DDE server name is usually the DDE server application name, for example the DDE
server name for CitectSCADA is "Citect", the DDE server name for Microsoft Excel is
"Excel", the DDE server name for Microsoft Word is "WinWord", and the DDE server
name for Microsoft Access is "MSAccess". Most DDE Servers respond to only one name.

DDE Topic name

The DDE Topic name for CitectSCADA is either "Data" (if you use the Cicode DDE func-
tions) or "Variable" (if you use CitectSCADA as the DDE server and want to access the
variable tag database directly). The DDE Topic name for Microsoft Excel is the name of
the worksheet (which may also include the workbook name enclosed in square brackets).
The DDE Topic name for Microsoft Word is the document name. The DDE Topic name
for Microsoft Access is the Database name and Table name, Query name or an SQL
string as detailed in the following note:

Note: The proper DDE Client syntax of the DDE Topic name section for accessing a
Microsoft Access database is constructed like this: "<DataBaseName>; TABLE <Table-
Name>".

The <DataBaseName> placeholder is for the name of the Access database file followed
by a semicolon ( ; ). You might have to include the file path; however this might not be
the case (i.e. if it is known that Access will be running with the target file open). The
.MDB suffix is optional (as .MDB is the default suffix for Access databases), unless the
full path was included.
The TABLE <TableName> is the command string to instruct Access which table data
you intend to converse with. DDE also supports the use of QUERY <QueryName> or
SQL <SQLString> in place of TABLE <TableName>.
The use of the semi-colon ( ; ) after the '<DataBaseName>' placeholder, and the use of
UPPERCASE for the 'TABLE', 'QUERY', and 'SQL' commands in the DDE string syntax
are necessary. The whole section needs to be enclosed in quotes ( " ).
DDE Data item name

954
Chapter 34: Exchanging Data with Other Applications

The DDE Data item name for CitectSCADA depends upon the DDE Topic name being
used. When using 'Variable' as the DDE Topic name to access the variable tag database
directly, the DDE Data item name is the CitectSCADA variable tag name. When using
'Data' as the DDE Topic name to access a value posted using the Cicode DDEPost() func-
tion, the DDE Data item name is the posted name.
The DDE Data item name for Microsoft Excel is the cell range in Row number Column
number format (for example R1C1). The DDE Data item name for Microsoft Word is a
bookmark name. The DDE Data item name for Microsoft Access is dependant upon
which topic name was used. Refer to the Microsoft Access Help for details.

Note: These CitectSCADA DDE help topics and examples were originally written for
Windows 3.xx and subsequently updated for Office 95 on Windows 95. Microsoft
has since introduced security measures with Office 2000 and later versions which,
by default, block Office applications from being DDE Clients. For security details, see
Using DDE with Microsoft Office applications.

CitectSCADA can perform as both a DDE server and as a DDE client as necessary. To set
up CitectSCADA to use DDE, see Exchanging CitectSCADA data via DDE.
CitectSCADA comes with an Excel workbook file which contains macros to help you
insert correct DDE Client syntax links from your CitectSCADA runtime project tag data-
base directly into an Excel worksheet.

DDE function types

There are two classes of DDE functions in Cicode, the original DDE functions and the
later DDEh functions.
DDE functions
The original Cicode DDE functions do not return a DDE Channel Number and were
designed to insulate the user from the need to manage DDE Channels. The DDERead(),
DDEPost(), DDEWrite(), and DDEExec() functions each perform a single exchange of
data. Each of these functions starts a DDE conversation with the external application,
sends or receives the data (or command), and ends the conversation - in one operation.
DDEh functions
The Cicode DDEhfunctions were introduced to afford more control over DDE com-
munications, especially for Network DDE and for circumstances where it is necessary to
explicitly terminate and re-initiate a DDE Channel (after deleting rows from a table for
example).
The DDE handle (DDEh...)functions return a handle to the conversation - a DDE channel
number.

955
Chapter 34: Exchanging Data with Other Applications

Use the DDEh handle functions for Network DDE, and for Access DDE.
See Also
Exchanging CitectSCADA data via DDE

Exchanging data via DDE

CitectSCADA runtime can exchange data as a DDE server or a DDE Client.
CitectSCADA behaves as a DDE server when providing other applications with access
to its data. When acting as a DDE server, CitectSCADA runtime can:
l Provide DDE access to the complete variable tag database automatically with no fur-
ther setup necessary
l Provide access to selected variable values by posting select CitectSCADA data using
DDE
CitectSCADA behaves as a DDE client when requesting other applications to provide
access to their data. When acting as a DDE Client, CitectSCADA runtime can:
l Read data directly from another application
l Write data directly to another application

Note: You can also execute commands in another application from CitectSCADA
with the DDEExec() function. Similarly, you can run Cicode functions from another
application by passing the functions through that application's DDE Execute com-
mand.

See Also
Connecting to the CitectSCADA tag database using DDE

Connecting to the tag database using DDE

CitectSCADA runtime behaves as a DDE server and automatically provides DDE access
to the complete variable tag database with no further setup necessary.
To create DDE links to the CitectSCADA variable tags, use the DDE Client syntax. For
syntax details, see DDE conversations and client syntax.
In the DDE Client call, the DDE Application name needs to be "Citect", the DDE Topic
name needs to be "Variable", and the DDE Data item name needs to be the CitectSCADA
tag name.
For instance, the PV1 tag value can be accessed from a cell in Excel containing the fol-
lowing formula:

=Citect|Variable!PV1

956
Chapter 34: Exchanging Data with Other Applications

If the CitectSCADA variable tag name contains spaces or non-alphanumeric characters,

the DDE data item section of the DDE Client call syntax needs to be enclosed within sin-
gle quotes. For example:

=Citect|Variable!'Process Variable 1'

CitectSCADA runtime and the DDE Client application (for example Excel) need to both
be running on the same computer. For information about DDE conversations, see DDE
conversations and client syntax.
To establish a DDE conversation between applications on the same computer, see Setting
up DDE conversations.
To establish DDE conversations between applications running on different computers
over the same network, see Network DDE.

Posting select data using DDE

You might have a tag naming convention which is not DDE compatible, or inap-
propriate for use in a DDE call. CitectSCADA provides the ability to publish specific tags
under different names in DDE. This involves using the DDEpost function.
To make selected CitectSCADA variable values or the results of calculations available to
external DDE Client applications currently running on the same computer, use the
Cicode DDEPost() function to have CitectSCADA runtime behave as a DDE server.
This conversation is one-way, which allows an external DDE Client application (like
Excel, Word, etc.) to read the value from CitectSCADA using DDE. The Client application
cannot change this value in CitectSCADA.
You can use this function to present data under a different name than its source. For
instance, the following example presents the value of variable tag PV1 as "Process1".
The following Cicode example posts the value of variable PV1 using DDE:

DDEPost("Process1", PV1)

Once posted, this value can be accessed, for example, from a cell in Excel containing the
following formula:

=Citect|Data!Process1

or from a field in Microsoft Word containing the following function:

{DDEAuto Citect Data Process1 }
Notes:

957
Chapter 34: Exchanging Data with Other Applications

l The name of the posted value (for example Process1) not to exceed 8 characters or
contain spaces if you want to link to it via a Microsoft Word DDE field. Microsoft
Excel, however, accepts long data item names if enclosed within single quotes (for
example 'Process Variable 1').
l You need to use Data as the DDE Topic name when accessing posted values. See Set-
ting up DDE conversations.
This method of DDE connection requires that both CitectSCADA runtime and the DDE
Client application (for example Excel or Word) are running on the same computer at the
same time. Once the DDE connection has been made, the DDE Client would normally
display the updated value of the CitectSCADA DDE posting as soon as it becomes avail-
able, usually within milliseconds of the post.
Unfortunately, this posting method of DDE linking is subject to breakage whenever
CitectSCADA runtime is closed, even if CitectSCADA runtime is subsequently restarted.
The DDE Client application might not detect the lack of connection, as updates to the
data in the DDE Client (for example Excel) only occur after each post by the DDE server
(CitectSCADA runtime). If no further posts occur, and in this scenario none will (as the
DDE link is disconnected), the DDE Client application receives no update, and sub-
sequently might display data which could be out of date. This disconnected state will
remain until the DDE link in the DDE Client application is refreshed or the DDE Client
application is restarted.
See Also
Writing values to a DDE application

Writing values to a DDE application

To write a CitectSCADA variable value directly to an external DDE server application
currently running on the same computer as CitectSCADA, use the Cicode DDEWrite()
function.
For example, writing data from CitectSCADA to a Microsoft Office Application (using
CitectSCADA as the DDE Client and the Office application as the DDE server), could be
done using the following Cicode DDEWrite() function examples:

! Write PV1 to Excel

! Assumes the existence of Sheet1
DDEWrite("Excel", "Sheet1", "R1C1", PV1);

! Write PV1 to Word

! Assumes the existence of TestDDE.doc already loaded in Word
! containing the bookmark named TagPV1
DDEWrite("Word", "TestDDE", "TagPV1", PV1);
! MS Access does not support direct DDE writes.

958
Chapter 34: Exchanging Data with Other Applications

This DDE function is one-way, so to update the tag value in the remote DDE server
application, this function will need to be called every time the value of this CitectSCADA
variable changes.
Writing directly to a DDE server assumes a prior knowledge of the DDE server. In the
above example, the spreadsheet or document needs to exist and Excel or Word (as appro-
priate) needs to be running for the DDE communication to be successful.
Notes:
l Instead of using the once only DDEWrite(), you could use the multiple use DDE han-
dle function DDEhPoke().
l Verify that remote requests are enabled in the other application. For example, in
Excel, you need to verify the Ignore other applications check box is cleared (the
default setting). In Excel 2003, use Tools | Options | General to adjust this setting.
l The High security setting (if selected) on Microsoft Office 2000 and later versions
does not appear to affect the use of remote DDE Client requests with those Office
applications. See Using DDE with Microsoft Office applications.
See Also
Reading values from a DDE application

Reading values from a DDE application

To read a value into a CitectSCADA variable directly from an external DDE server appli-
cation currently running on the same computer as CitectSCADA, use the Cicode DDERead
() function. For example:

PV1 = DDERead("Excel", "[Book1]Sheet1", R1C1);

The data from Row 1, Column 1 on Sheet 1 of Book 1 in Excel is read and stored in the
CitectSCADA variable "PV1". This DDE function is one-way, and will need to be called
whenever the value needs to be updated in CitectSCADA.
Reading from a DDE server assumes a prior knowledge of the DDE server. In the above
example, Excel needs to be running and the appropriately named spreadsheet needs to
exist. The CitectSCADA variable PV1 needs to also have been previously declared.

Note: Instead of using the once only DDERead(), you could use the multiple use DDE
handle function DDEhRequest().

Verify that remote requests are enabled in the other application. For example, in Excel,
you need to confirm that the Ignore other applications check box is cleared (the default
setting). In Excel 2003, use Tools | Options | General to adjust this setting.

959
Chapter 34: Exchanging Data with Other Applications

The High security setting (if selected) on Microsoft Office 2000 and later versions does
not appear to affect the use of remote DDE Client requests with those Office applications.
See Using DDE with Microsoft Office applications.

Using DDE with Microsoft Office applications

Microsoft has introduced security measures with Office 2000 and later versions which,
by default, block Office applications from being DDE Clients. See Microsoft Office secu-
rity.
Microsoft Office applications appear to support varying degrees of long file names with
DDE. See Long file names in DDE.
To enable DDE remote requests in Microsoft Excel, you need to verify the Ignore other
applications check box is cleared (the default setting). In Excel 2003, use Tools | Options
| General to adjust this setting.

Long file names in DDE

According to MSDN Knowledge Base article Q109397, DDE does not support long file
names, so DOS alias names needs to be used for directory and file names longer than
eight characters (i.e. C:\mydocu~1\file.mdb).
Different Microsoft Office applications differ in their support for the use of long file
names when used as DDE Clients. For instance, Microsoft Word does not appear to sup-
port the use of DDE data item names which exceed 8 characters, while Microsoft Excel
however, accepts long data item names if enclosed within single quotes. See Posting
select CitectSCADA data using DDE for an example.

Microsoft Office security

In the interests of data security, Microsoft Office 2000 and later versions have their secu-
rity settings set to high by default. To view or change your security level in Excel or
Word, choose Tools | Macro, click Security, and click the Security Level tab.
l If you have your security level set to High (the default setting), then communication
with external DDE Servers will not be available unless they are digitally signed and
trusted. What you see in Excel cells that use the DDE function is #N/A , and with no
additional explanation as to why the DDE functions aren't working. The High secu-
rity setting (if selected) does not appear to affect the use of remote DDE Client
requests with those Office applications as DDE Servers.
l If you set your security level to Medium, you are asked if you want to run any DDE
Servers that are not digitally signed and trusted and that are referenced by DDE func-
tions.

960
Chapter 34: Exchanging Data with Other Applications

l If you set your security level to Low, external DDE Servers are run regardless of
whether they are digitally signed and trusted, or not.

Note: If you need to manipulate another application's objects from Microsoft Office,
consider using OLE Automation.

Network DDE
Network DDE is a version of the DDE protocol for use across a network. For information
about DDE, see Using DDE (Dynamic Data Exchange). For details about setting up Citect-
SCADA to use DDE, see Exchanging CitectSCADA data via DDE.
Just like the establishment of a DDE conversation between applications running on the
same computer, a network DDE conversation uses the same DDE protocol to share data
between applications running on separate computers connected to a common network.
Network DDE is a Windows Service used to initiate and maintain the network con-
nections, security, and shared file space needed for using DDE over a network, and
needs to be running on both computers at the same time. For startup details, see Starting
network DDE services.
A network DDE trusted share needs to be manually created for the Network DDE server
application on the Network DDE server application machine. This instructs the Network
DDE Service (on the DDE server application machine), as to which application and topic
to connect with. It is this share name which the Network DDE Client application can
subsequently communicate with. For details, see Setting up network DDE shares.
The Network DDE Client starts the Network DDE conversation by connecting to the Net-
work DDE Share on the Network DDE server computer. For details, see Using network
DDE.

Starting network DDE services

For Network DDE to function, NetDDE.EXE needs to be installed and running on both
machines before attempting to conduct a Network DDE conversation. NetDDE.exe is a
Windows Service system file that is used to communicate the shared dynamic data
exchange used by Network DDE. It has no graphical user interface (it runs as a back-
ground Windows service).
It is necessary to initiate the automatic activation of Network DDE Services, or manually
run NetDDE.EXE on both machines before attempting connection.
To manually start Network DDE services:

961
Chapter 34: Exchanging Data with Other Applications

l On the Windows Start menu, click Start | Run, type in "netdde" (without the quotes)
and press the Enter key. Do so on both machines.
To automatically start the Network DDE Services on machine startup:

l With Windows 2000 and later, use the Windows Services Manager (select Start |
Control Panel | Administrative Tools | Services) to set the Network DDE
servicefrom Manual to Automatic. To do so, right-click the service and select Prop-
erties from the pop-up menu. On the General tab select Automatic from the drop-
down list of the Startup type field. Click OK. Close evry window and restart the
machine.
To verify that the NetDDE Services are running:

l The Windows Task Manager lists NetDDE.exe on the Processes tab when running.
To view the Windows Task Manager, press CTRL+ALT+DEL.
l The Service Administrative Tools also lists the status of Network DDE and Network
DDE DSDM. To view the Windows Services Manager, select Start | Settings | Con-
trol Panel | Administrative Tools | Services.

Note: If you are using only the Microsoft Client Service for NetWare Networks,
the NW IPX/SPX/NetBIOS compatible protocol needs to be enabled for
NetDDE.exe to load.

To test that Network DDE is operational between two machines on the same network
Microsoft Windows ships with a network DDE application called Chat. It is installed in
the system32 folder.
1. On the Windows Start menu, click Start | Run, type in "winchat" (without the
quotes) and press the Enter key. Do so on both machines.
2. On one machine, select the Chat menu Conversation | Dial or click the dial button.
The Select Computer dialog will display.
3. Select the other computer from the list, and click OK. Chat will attempt to establish a
network DDE conversation between the computers.

Note: If Chat is not already running on the other computer, it times-out and states
that the other computer didn't answer. If however, the other computer is already
running Chat, it will keep dialling until answered.

4. On the other machine, (while it is being dialed), select the Chat menu Conversation |
Answer or click the answer button. Type in a message and it will display in the Chat
window on the other machine. The conversation will continue until either machine
hangs up.

962
Chapter 34: Exchanging Data with Other Applications

Once a Chat conversation is established, it proves that both machines are properly set-
up and capable of handling network DDE conversations. You can view the share prop-
erties for Chat$ by using the DDEShares.exe application as described in Setting up net-
work DDE shares.
You don't have to run Chat to use Network DDE with CitectSCADA. This Network DDE
test only uses Chat as an example to confirm Network DDE functionality between two
machines. Once you have established that Network DDE is functional, close the Chat
windows, create the Network DDE Trusted Share for your Network DDE server appli-
cation, and connect to the share using Network DDE. See Connecting to a network DDE
shared application.

Setting up network DDE shares

To be able to create a DDE link over a network, the computer serving as the Network
DDE server needs to be setup to provide a NetworkDDE Share to establish a network
DDE Channel.

Note: You only have to create a DDE Share if you intend to use DDE between two
separate applications running on different machines, and you only have to create the
DDE Share on the machine that contains the application which will be the DDE
server.

The Windows DDESHARE.EXE utility enables users to manage DDE shares. The 32-bit
version is shipped with each Microsoft operating system and is located in the Win-
dows\System32 sub-directory.
To manually launch the DDE Share utility:

l On the Windows Start menu, click Start | Run, type in "ddeshare" (without the
quotes) and press the Enter key.
When DDEShare.EXE is running, it displays the DDE Share utility window containing
two icons which launch the DDE Shares dialog, and the DDE Trusted Shares dialog:
In the DDE Share utility, double-click the left icon (without the check mark) to display
the DDE Shares dialog box:
The DDE Shares dialog is used to create, manage, and delete global DDE shares on your
computer, and to view the DDE shares of any computer on the network. You can use
this dialog to confirm the names of shares available on any machine on the same net-
work. From the DDE Shares menu, select Shares | Select Computer and choose the com-
puter name you're interested in from the list.

963
Chapter 34: Exchanging Data with Other Applications

DDE Shares
There are three types of DDE shares: old style, new style, and static. CitectSCADA only
supports the static type. The names of static shares follow the convention

<ShareName>$

so to set up a CitectSCADA server computer as a Network DDE share, use the name
"Citect$" as the sharename on that computer. To expose the CitectSCADA runtime var-
iable tag database for suitable DDE linking, use the word "Variable" as the DDE Share
Topic name.

Note: The trailing dollar sign ($) is necessary as part of the DDE share name syntax.

To create a DDE share:

1. In the DDE Shares dialog, click Add a Share. The DDE Shares Properties dialog
appears. Verify that the fields are blank, or unchecked, except for the Grant access to
every item radio button which needs to be checked.
2. Click Permissions. The DDE Share Name Permissions dialog appears.
3. Read and Link is the default permission setting. If you want to write data to the DDE
Share application, change the permission to Full Control.
4. Click OK.
5. Click OK to save the Share, and return to the DDE Shares dialog.
See Also
Using DDE Trusted Shares

Using DDE Trusted Shares

When a network DDE Client user connects to a network DDE Share from a remote com-
puter, Network DDE accepts the request only if both:
l The user who created the share has granted trusted status to the share.
l The user who created the share is currently logged on to the server computer.
To link to the CitectSCADA tag database, and permit write actions from an external
application using Network DDE, the DDE Client computer needs to be granted appro-
priate Trusted status.
To create a trusted share:

1. On the DDE Shares dialog, highlight the new 'Citect$' share entry, and click Trust
Share to display the Trusted Share Properties dialog box.

964
Chapter 34: Exchanging Data with Other Applications

2. Check Initiate to Application Enable to allow new connections to the DDE share.
3. Click OK.
To view the trusted shares:

1. In the DDESHARE utility double-click the right icon (with the check mark) to display
the DDE Trusted Shares dialog.
2. The DDE Trusted Shares dialog lists the DDE shares that are trusted in the current
user's context. You can view and modify trusted share properties and remove DDE
shares from the list of trusted shares.
3. Once setup is completed, close the DDE Share utility dialog box.

Using network DDE

Microsoft Network DDE Service needs to be running on both computers to communicate
using Network DDE. For startup details, see Starting network DDE services.
Before a Network DDE Client can establish a DDE conversation with a Network DDE
server application, the Network DDE server application computer needs to already have
setup a Network DDE Share. For details, see Setting up network DDE shares.

Note: You cannot connect using Network DDE to a shared application on the same
machine. You can only connect using Network DDE to a shared application on
another machine (which needs to also be on the same network).

To connect to a Network DDE shared application, you use an altered version of the DDE
syntax, which replaces the "<ApplicationName>" with "<ComputerName>\NDDE$" and
replaces the "<TopicName>" with the Network DDE server Share "<ShareName>", and
continues to use the "<DataItemName>" as normal.
At first glance, there appears to be no way to specify the DDE Application or Topic
names in the Network DDE syntax call, and indeed, that is the case. However, the DDE
Application and Topic names are defined in the DDE server Share settings. So, when the
Network DDE server machine receives the call (from the Network DDE Client) con-
taining the Share name, it knows which application and topic to connect with. See Con-
necting to a network DDE shared application.

Connecting to a network DDE shared application

The network DDE Client specifies the remote DDE server share in the normal DDE
Client syntax by replacing the DDE Application name and DDE Topic name with the
DDE server computer name and DDE server share name in the call. For DDE client syn-
tax details, see DDE conversations and client syntax.

965
Chapter 34: Exchanging Data with Other Applications

With Network DDE Client syntax, the DDE Application name is replaced with the fol-
lowing string enclosed in single quotes:

'\\<ComputerName>\NDDE$'

where "<ComputerName>" is the name of the computer running the DDE server appli-
cation, and "NDDE$" notifies Windows on the remote computer that the calling DDE
Client wishes to establish a Network DDE channel. You cannot omit the NDDE$ string,
or it won't work.
The DDE Topic name is replaced with the following string also enclosed in single
quotes:

'<ShareName>'

where "<ShareName>" is the name of the DDE Trusted Share previously set-up on the
DDE server computer. The DDE Share on the DDE server machine contains the details of
which application and topic to create the Network DDE link with. Most often, DDE
server share names end with a $ character.

Note: You need to use a separate DDE share name on the remote computer for each
combination of DDE application name and DDE topic name you want to share. You
can not declare the topic as a wild card (*).

For example, to create a Network DDE link with the following criteria:
l CitectSCADA variable tag name: "PV1"
l CitectSCADA server computer name: "PlantSvr"
l Remote DDE Share name: "Citect$"
you would construct a Network DDE Client call containing:

'\\PlantSvr\NDDE$'|'Citect$'!PV1

In Excel, the following formula could be placed directly into a worksheet cell:

='\\PlantSvr\NDDE$'|'Citect$'!PV1

If prompted for a username and password, use one that has appropriate permissions on
the DDE server computer.

Note: You cannot omit the DDE syntax pipe character (|) or exclamation character
(!), nor can you enclose those characters within quotes (').

966
Chapter 34: Exchanging Data with Other Applications

CitectSCADA comes with an Excel workbook file which contains macros to help you
insert correct DDE Client syntax links from your CitectSCADA runtime project tag data-
base directly into an Excel worksheet.

Using ODBC drivers

CitectSCADA supports the open database connectivity (ODBC) standard. Many man-
ufacturers of database packages now also supply an ODBC database driver for their soft-
ware. As well as these there are independent parties manufacturing ODBC database
drivers for various databases, such as Intersolv Q+E with their DataDirect ODBC Pack.
Usually, any ODBC driver for your database will work.
See Also
Installing the ODBC driver
About the ODBC driver
Setting up ODBC
Getting the correct syntax with ODBC
Programming style with ODBC
Using CitectSCADA as an ODBC server

Installing the ODBC driver

You need to install and setup up your ODBC driver from the Windows Control Panel.
To do this:
1. Open the Windows Control Panel.
2. Click the ODBC icon to start the ODBC setup utility (if you do not already have an
ODBC icon in your control panel, you might need to install the icon. See the doc-
umentation provided with your ODBC driver).
3. Click Add to set up a DataSource.

Note: If your ODBC driver is not included in the list of Installed ODBC Drivers,
return to the ODBC setup utility and install your driver (select the Drivers... but-
ton).

4. From the Add Data Source dialog box, select your ODBC driver. The Setup dialog is
displayed.
5. Enter the Data Source Name of the driver that you used previously. For example, if
you had used SQL with a dBASEIII database, then your connection string would
have been "DRV=QEDBF". To avoid changing the connection strings throughout your

967
Chapter 34: Exchanging Data with Other Applications

project, use a Data Source Name of QEDBF.

6. Run your CitectSCADA project.
Some Cicode SQL functions will not work if your ODBC driver has limited functionality.
This situation is not frequently encountered, and in most cases affects only the ability to
use transactions with the SQLBeginTran(), SQLCommit(), and SQLRollBack() functions. If
you are using the Intersolv Q+E ODBC drivers, it is unlikely you will experience any loss
of functionality.
You might need to change the data source in the Control Panel each time you switch
from using one ODBC-compatible driver to another, for example from a dBASE file to an
Access database. Click the ODBC icon and select from the list of available data sources.
(Refer to the documentation supplied with your driver for more information.)
Notes:
l For maximum compatibility with the Cicode SQL functions, the ODBC driver has to
provide a minimum of functions. For example, if your driver does not support the
ODBC function SQLTransact, you cannot use the Cicode functions SQLBeginTran(),
SQLCommit(), and SQLRollback().

l Any functions you might have created in early versions are backward-compatible.
Q+E drivers are now ODBC-compliant, so you need to upgrade your old Q+E data-
base driver to a Q+E ODBC database driver.
See Also
About the ODBC driver

About the ODBC driver

CitectSCADA connects directly to the Microsoft Access ODBC driver, which allows appli-
cations to access information stored in MDB (Microsoft Access Database) files without
actually running Microsoft Access. (Microsoft Access uses the "Jet Engine" DLL to access
information stored in MDB files.)
ODBC normally implies heavy use of SQL statements to manipulate data. SQL state-
ments can become quite complex and verbose. To implement them in Cicode they often
have to be separated into sub-strings so that the maximum string length for Cicode var-
iables is not exceeded.
With Access, it is possible to call queries that have been defined in Access so that the
SQL statements become quite simple and straightforward. The Access tables & queries
can be used to implement RELATIONSHIPS and JOINS, to SORT & SELECT only
those rows (records) and return only those columns (fields) of particular interest at the
time.

968
Chapter 34: Exchanging Data with Other Applications

Developing queries in Access also has an advantage that the resulting Recordsets can be
viewed in Access to test that they contain the data that is expected. The queries can incor-
porate SQL Functions (such as BETWEEN & AND).
The Jet Engine can also call upon theVBA Expression Service. This means that many
non ANSI functions can also be used (both in SQL statements and Access Query Def-
initions) provided there is no need to migrate to a non Access system at a later date.
Refer to VBA Functions Reference in the Access or Excel help system (only those func-
tions with (VBA) after them and are appropriate to an SQL environment, are likely to
work in an SQL statement).
See Also
Setting up ODBC

Setting up ODBC
To use ODBC, the Access ODBC Driver needs to be installed. This can be obtained from
Microsoft and is included with Microsoft Office. The installation programme (for exam-
ple, for Microsoft Office) will copy the necessary drivers and the Jet Engine DLL into the
appropriate Windows directories when the appropriate Data Access/ODBC options are
selected.
With the Driver installed on the PC the ODBC Icon can be selected from the Control
Panel and a Data Service Name set up for the desired MDB. This is used in the DSN=
part of the connect string.
The Jet Engine DLL is quite large (1 MB) and the execution speed of the runtime (and
your application) can be impacted if the Windows Virtual Memory Manager (VMM)
swaps it out of memory. The next time an SQL is executed there will be short delay
while the DLL is loaded back into memory. To force the VMM to keep the DLL in mem-
ory, design a simple dummy table with only one record and one field and set up a
Cicode task that frequently (say every 10-15 seconds) calls a SELECT query based only
on the dummy table. This has no significant effect on CPU load and keeps the DLL in
memory.
See Also
Getting the correct syntax with ODBC

Getting the correct syntax with ODBC

The ODBC syntax for SQLs varies from the Access syntax in some ways. A good way to
get the syntax correct and view the resulting Recordset is to use the query designer in
Microsoft Query then copy the SQL text from it into Cicode. Because MS Query uses
ODBC, any syntax that works in it will work when called via ODBC from Cicode. MS
Query can also be used to confirm that the DSN is correct.

969
Chapter 34: Exchanging Data with Other Applications

MS Query tends to create SQL text that is more complex than necessary. In particular it
includes the path with the file name which is not necessary because the path is already
defined in the DSN entry. It is considered bad practice to hard code file paths. MS Query
also tends to prefix column (field) names with the table names to avoid any chance of
ambiguity. Again this is not always necessary and it is desirable to keep the SQL text as
brief as possible in your code.
The SQL statement text generated by the query designer can be pasted into Execute SQL
window (under the File menu of MS Query), any surplus text removed and the SQL state-
ment tested until the simplest syntax that works can be found. There is provision to save
the SQL text if necessary. The final version of the SQL statement can be used with con-
fidence in Cicode.
See Also
Programming style with ODBC

Programming style with ODBC

Most of the sample code in the following topics do not include error checking and report-
ing:
l Reading data from an access table with ODBC
l Writing data to an access table with ODBC
l Deleting rows from an Access table with ODBC
l Calling action queries with ODBC
l Parameter queries using ODBC

Note: These examples exclude error checking to keep them as simple as possible.
However, both common sense and accepted programming practices mandate that
you include error checking in your ODBC code.

Give consideration to implementing most of the complexity of queries in Access Query

Definitions where they are easier to design and the results are easily viewed. A WHERE
clause can be used when calling the query to select only the desired rows at run time.
Where tables have many columns (fields), the Access Query Definitions can be used to
restrict any particular call to view only the fields of interest.
It is helpful to build the SQL test up into strings. Firstly the ODBC function calls become
simpler. Secondly the strings can be passed to TraceMsg() to make debugging simpler.
Remember that the Jet Engine runs on the same PC as CitectSCADA and that complex
queries returning large Recordsets can have an adverse impact on CPU and memory
resources. However, excessive impact on PC resources can be avoided by careful table,
query and relationship design.

970
Chapter 34: Exchanging Data with Other Applications

If there is a need to execute the queries on a Remote Computer, the code can set up on a
Reports Server or an Event Server. This is especially relevant if the code is to be triggered
by an event in a PLC. If the code is to be triggered by a User at a Display Station, and the
query is considered too CPU intensive, the Display Station can be used to set the PLC bit
that calls to code or call the Report using the Cicode Report() function. Another pos-
sibility is to use the Cicode MsgRPC() function to call a Cicode function (with param-
eters, if necessary) on a remote computer. Each of these alternatives require CitectSCADA
to be running on the remote computer.
See Also
Comparing DDE with ODBC

Comparing DDE with ODBC

Each has advantages and disadvantages. In general DDE is suitable for simple require-
ments but ODBC give serious thought if the limitations of DDE become too restrictive.
DDE Advantages
l No need to set up a Data Service Name (DSN); however, a DDEShareName is nec-
essary for Network DDE.
l Can call Access Macros & Functions.
DDE Disadvantages
l Record sets with rows that exceed the maximum Cicode string length cannot be read
directly.
l Rows (records) are returned to string variable with TAB characters between columns.
You need to parse the string in Cicode to obtain the column (field) values.
l SQL over DDE cannot perform actions (such as INSERT, UPDATE or DELETE).
l DDE Client and server applications need to be be running at the same time.
ODBC Advantages
l MS Access does not have to be running. ODBC uses the JET Engine DLL on the same
PC. This an advantage in many ways but can consume excessive PC resources if not
managed properly.
l Large SQL statements can be split into sub-strings.
l SQLGetField makes easier to get data from fields (columns). There is no need to parse
the data in Cicode.
l Can handle large numbers of fields (columns) in the Recordset.
l SQL can perform actions (such as INSERT, UPDATE or DELETE).
ODBC Disadvantages
l Requires that a Data Service Name (DSN) be set up.

971
Chapter 34: Exchanging Data with Other Applications

The JET Engine DLL cannot be directly called on a remote PC, (Reports or MsgRPC() can
be used however, to run SQL statements on a Remote Computer which needs to be be
running CitectSCADA).
See Also
ODBC compatibility

ODBC compatibility
This section describes the necessary and optional ODBC functions that your database
driver needs to support:
l Essential functions
l Optional functions

Essential functions
The CitectSCADA SQL devices and Cicode functions only work if the database driver
supports the following ODBC functions:

Level 0 Level 1

SQLAllocConnect SQLColumns

SQLAllocEnv SQLDriverConnect

SQLAllocStmt SQLGetData

SQLBindCol SQLGetFunctions

SQLColAttributes SQLGetInfo

SQLDescribeCol SQLGetTypeInfo

SQLDosconnect SQLParamData

SQLError SQLPutData

SQLExecDirect SQLSetConnectOption

SQLExecute SQLSetStmtOption

SQLFetch

972
Chapter 34: Exchanging Data with Other Applications

SQLFreeStmt

SQLGetCursorName

SQLNumResultCols

SQLPrepare

SQLRowCount

SQLSetParam

Optional functions
CitectSCADA SQL devices and Cicode functions also use the ODBC functions listed in
the table below. While these functions are not necessary for operation, if they are absent
in a driver, the error code 307 (SQL database error) will be returned if the ODBC driver
does not support the necessary ODBC functions. To get the message associated with the
error, call the Cicode function SQLErrMsg.
Level 0

SQLTran- If the driver does not support this function, the Cicode functions SQLBe-
sact ginTran(), SQLCommit(), and SQLRollBack() are not supported.

Level 1

SQLSpecial CitectSCADA uses this function if it is available. There is no loss of func-

Columns tionality otherwise.

SQLTables (no effect on CitectSCADA)

Level 2

SQLData The driver does not need to support this function. It is provided by ODBC.
Sources

SQLEx- Without this function, CitectSCADA cannot take advantage of the native
tended database's ability to fetch records at random.
Fetch

SQLSet- Without this function, CitectSCADA cannot take advantage of the native
Scroll database's ability to fetch records at random.
Options

973
Chapter 34: Exchanging Data with Other Applications

SQLMore (no effect on CitectSCADA)

Results

SQLNa- (no effect on CitectSCADA)

tiveSql

SQLProce- (no effect on CitectSCADA)

dure Col-
umns

See Also
Using CitectSCADA as an ODBC server

Using CitectSCADA as an ODBC server

The ODBC server support allows CitectSCADA to function as an SQL database server.
This will allow third-party applications that support ODBC to access data directly from
CitectSCADA. This means that users can have direct access to data in CitectSCADA with-
out having to develop Cicode or reports to export the data.
Currently, the CitectSCADA ODBC server allows variable tags to be accessed. The table
for the variable tags is named 'TAGS' and the format is as follows.

NAME Variable tag name read only

VALUE The current runtime value read/write

CitectSCADA can only function as a database server at runtime. Using tags through
ODBC at runtime can still add to your CitectSCADA License point count. Once the
dynamic point count is greater than the license point count, the software protection
mechanism will shutdown CitectSCADA runtime. Therefore, when accessing tags via
the ODBC server, it's important to keep aware of how many points you have used. For
details see License point count in the Installation and Configuration Guide.
Setting up the CitectSCADA ODBC server:
You need to have TCP/IP installed on your computer first.
1. Choose Start | Settings | Control Panel.
2. Double-click the ODBC icon.
3. Click Add on the User DSN tab.

Note: If you select other tabs you will see that the CitectSCADA ODBC driver has

974
Chapter 34: Exchanging Data with Other Applications

been automatically installed.

4. Select the Citect Driver from the list and click Finish.
5. Enter "Citect" in the Data Source field. If you do not want to use this name, make
sure the name you use is one word.
6. Enter the Computer Name in the Host field. The Computer Name is specified in the
Network section of the Control Panel.
7. Click OK.
Accessing the CitectSCADA ODBC server using MS Query (V2.00):
All ODBC capable applications use different ways to construct queries for accessing
CitectSCADA tags. The example instructions for using MS Query, given here, show a
simple implementation. MS Excel and MS Access use the same method.
1. Verify that you have MS Query installed on your computer.
2. Set up the CitectSCADA ODBC server.
3. Run CitectSCADA.
4. Run MS Query.
5. From the File menu (in MS Query) select New Query.
6. Select the CitectSCADA Data Source Name (DSN) from the Available Data Sources
list. Click the Use button.
7. Select the Tags table. Click the Add button and then the Close button.
8. You can now run a query to extract the Tag data from CitectSCADA. The simplest
way to see this is by double-clicking Names and Tags.
Accessing the CitectSCADA ODBC server using MS Query (V8.00):
Unlike Version 2.00, User DSNs are not used by Version 8.00. Instead it uses File DSNs
which by default are stored in Program Files\Common Files\ODBC\Data Source folder. File
DSNs are not stored in the Windows registry, they are text files given the .DSN exten-
sion. When you connect to an existing data source, only the available File DSNs that are
stored on that PC are displayed. MS Query V8.00 does not display User or System DSNs.
The simplest solution is to create a File DSN that points to a User DSN.
To create a file DSN that points to a user DSN:

1. Use a text editor (Notepad for example) and create a file containing the following two
lines:
[ODBC]
DSN=<MyUsrDSN>

975
Chapter 34: Exchanging Data with Other Applications

where <MyUserDSN> is the name of an existing user DSN that you have created
via the ODBC icon in the Control Panel.
2. Click Save As on the File menu and type a name that includes a .DSN file extension.
For example, "Citect_File.dsn" is a valid name. Include the quotation marks so that
the .DSN file name extension is added correctly. Save it to the default File DSN direc-
tory listed above, then it will appear in the DSN list box.
3. Open the ODBC Manager from the Control Panel and verify that you can see your
newly created File.DSN.
4. Open the ODBC Manager from the Control Panel and verify that you have created a
User DSN called <MyUsrDSN>. For example:
1. Select Citect Driver and click Finish.
2. Type "Citect" in the Data Source field (i.e., <MyUsrDSN>).
3. Enter Computer Name in the Host field.
When you run MS Query, you can now select your File DSN from the list.
See Also
Reading data from an access table with ODBC

Reading data from an access table with ODBC

You can use a SELECT query to read data from an Access table or to call an Access
query.
A query is preferred over a table if there are many more columns in the table than are
needed at the time, if the data needs to be sorted, or if you need to relate or join several
tables. The Cicode necessary is as follows:

Function SQLTest
INT hSQL, iResult;
hSQL = SQLConnect("DSN=ODBCTest;UID=YourUID_C;PWD=YourPWD");
IF hSQL <> -1 Then
iResult = SQLExec(hSQL, "SELECT * FROM qryRecipes
WHERE Recipe Between '3000' And '6000'");
IF iResult = 0 Then
WHILE SQLNext(hSQL) = 0 DO
TraceMsg(">" + SQLGetField(hSQL, "Recipe")
+ "<>" +SQLGetField(hSQL, "Flour")
+ "<>" +SQLGetField(hSQL, "Water")
+ "<>" +SQLGetField(hSQL, "Cocoa") + "<");
END
SQLDisconnect(hSQL);
ELSE
Message("SQL Error", SQLErrMsg, 48);
END
ELSE
Message("SQL Error", SQLErrMsg, 48);

976
Chapter 34: Exchanging Data with Other Applications

END
END

Appending data with ODBC

To append data to an Access table using ODBC, you can use an SQL INSERT statement.

Function SQLInsert
INT hSQL, iResult;
hSQL = SQLConnect("DSN=ODBCTest;UID=YourUID;PWD=YourPWD");
IF hSQL <> -1 Then
iResult = SQLExec(hSQL, "INSERT INTO tblRecipes
(Recipe, Flour, Water, Cocoa) VALUES ('X1234', 2, 3, 4)" );
SQLDisconnect(hSQL);
END
END

To avoid having to deal with SQL statements, you can use the standard Cicode device
functions to append records to an Access table. First configure an SQL device. If the table
has many fields that do not need to be written to, define only those fields that are nec-
essary in the device definition (this keeps the device definition simple and reduces the
number of DevWrite instructions). DevOpen, DevWrite and DevClose can then be used
to add records to the table.
CitectSCADA accepts successive DevWrites until they equal the number of fields in the
device definition at which time it constructs an SQL INSERT statement. The DevWrites
needs to contain data for fields in the same order as the device definition. Do a DevOpen
followed immediately by successive DevWrites for as many records as are necessary
then a DevClose to avoid data being out of context.
See Also
Editing data with ODBC

Editing data with ODBC

To edit data in an Access table there needs to be a unique (usually primary) key to iden-
tify the row (record) to be changed. This is to be able to provide a WHERE clause that
will apply only to that row in an SQL UPDATE.
Toedit data, read the data in the normal way, keeping track of the unique key. Any
changed values can later be written to the same row using an UPDATE query with a
WHERE clause.

977
Chapter 34: Exchanging Data with Other Applications

Function SQLUpdate
INT hSQL, iResult;
hSQL = SQLConnect("DSN=ODBCTest;UID=YourUID;PWD=YourPWD");
IF hSQL <> -1 Then
iResult = SQLExec(hSQL, "UPDATE tblRecipes SET Flour = 20,
Water = 30,Cocoa = 40 WHERE Recipe = 'X1234'");
SQLDisconnect(hSQL);
END
END

Note: The ODBC/SQL environment does not let you edit the "Current Record" (there
is no current record). Consequently you cannot use DevAppend or DevSetField to add or
modify records.

See Also
Deleting rows from an Access table

Deleting rows from an Access table

The DELETE keyword is used with a WHERE clause to delete the necessary row or rows.
If the WHERE clause is not based on a primary key, more than one record may be
deleted.

Function SQLDelete
INT hSQL, iResult;
hSQL = SQLConnect("DSN=ODBCTest;UID=YourUID_C;PWD=YourPWD");
IF hSQL <> -1 Then
iResult = SQLExec(hSQL, "DELETE FROM tblRecipes WHERE
Recipe = 'X1234'");
SQLDisconnect(hSQL);
END
END

See Also
Calling action queries with ODBC

Calling action queries with ODBC

Access ACTION queries cannot be called in a SELECT query such as:

"SELECT * FROM qdeDeleteRecipe"

To call an Access ACTION via ODBC, use the Call statement in SQLExec:

"{Call qdeDeleteRecipe}"

978
Chapter 34: Exchanging Data with Other Applications

The statement needs to be enclosed in {curly} braces.

The Call statement can be used to Call SELECT queries, the resulting Recordset being
accessible in the normal way.
See Also
Parameter queries

Parameter queries
Many ODBC Servers will accept PARAMETERS in a Call statement so that PARAM-
ETERS can be defined in a Query Definition on the server and their values supplied by
ODBC Clients at run time. Unfortunately, the Access Jet Engine uses Parameter Markers
which are not supported in the standard Call statement. The method outlined here can
be used as a work-around.
For each query that requires PARAMETERS, design a arguments table with the same
name as the query but with a different prefix. For example, if the query is qryParamTest,
the TABLE could be called argParamTest.
The TABLE could have, say, five fields called Param1, Param2, Param3, Param4,
Param5.
Add this table to the Access Query Definition for qryParamTest. Then the field names
can be used as PARAMETERS anywhere in the Query Definition.

979
Chapter 34: Exchanging Data with Other Applications

A simple Cicode function can be written to which the query name (without the prefix)
and PARAMETERS are passed. The function inserts "arg" in front of the query name and
executes a DELETE from the TABLE (to verify that it is empty) and then performs an
INSERT to leave the table containing ONE RECORD with the desired PARAMETERS in
the appropriate fields. The function then prefixes the query Name with "qry" and calls
the query.

Function SQLCall(INT hSQL, STRING sQueryName, STRING sArg1 = " ", STRING sArg2 = "
",
STRING sArg3 = " ", STRING sArg4 = " ", STRING sArg5 = " ")
STRING sTable, sQuery;
sTable = "arg" + sQueryName;
sQuery = "qry" + sQueryName;
SQLExec(hSQL, "DELETE FROM " + sTable);
SQLExec(hSQL, "INSERT INTO " + sTable + " (Param1, Param2, Param3, Param4,
Param5) VALUES ('" + sArg1 + "', '" + sArg2 + "', '" + sArg3 + "',
'" + sArg4 + "', '" + sArg5 + "')");
SQLExec(hSQL, "{Call " + sQuery + "}");
END

Calling the Function from Cicode is then as simple as:

SQLCall(hSQL, "ParamTest", "2000", "4000");

The default parameters for SQLCall needs to be SPACES if "Allow Zero Length" is "No"
in the Access table Definitions for fields Param1, Param2 etc.
The function can be used to call many different PARAMETER queries.
An advantage of this work-around is that, even after CitectSCADA has been shut down,
the query can be called from Access and, because the PARAMETERS are still stored in
the arguments table, the resulting Recordset can be viewed in Access.
Another method is to design queries that perform any necessary joins, sorting and field
selection the call them using a WHERE clause to select the desired rows (records).
See Also
Access and Cicode date/time conversions

Access and Cicode date/time conversions

Access and Cicode have different Date/Time variables data types. Date references in an
external database has to be based on the Gregorian Calendar.
You can convert between date and time in three ways:
l Convert to real numbers - In both Cicode and Access you can equate real numbers to
data/time variables, like this:
AccessTime = 25568.66667 + (CicodeTime/86400);
CitectTime = 86400*(AccessTime - 25568.66667);

980
Chapter 34: Exchanging Data with Other Applications

l Convert to strings - The Data and/or Time are converted to and from text strings
using the standard conversion functions available in each environment.
l Use the #Date/Time# SQL syntax - The Jet Engine will convert and Dates and Time
strings enclosed in # markers. This date could be useful in a WHERE clause:

SELECT * FROM qryMyQuery WHERE 'Date' BETWEEN #3/20/96# AND #3/27/96#

The American Date format is used in this case, the Jet Engine DLL ignores the local Date
and Time settings as set in Windows Control Panel.

Using Microsoft Excel to Edit .dbf Tables

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.
The ProjectDBFAddIn is an optional component included in the installation of Citect-
SCADA and is accessed from the installer. If you did not select installation of the Add-In
during installation, you can install it at a later time by navigating to the Pro-
jectDBFAddIn folder of your CitectSCADA installation and running the setup.exe in that
folder.

Note: The installation of the projectDBFAddIn will only be available if a version of

Microsoft Excel is detected by the installer on the target computer.

Compatibility
This Add-In is specifically designed for use with Microsoft Excel 2007 or later, it is not
compatible with Microsoft Excel 2003.

Note: Add-in supports Microsoft Excel 2013 (32 bit) only.

Integration with Microsoft Excel

When you open Microsoft Excel, an additional toolbar, or an additional tab, called
project DBF Add-in is available depending on the version of Excel that you are using.
The fields and buttons on this toolbar allow you to choose:

981
Chapter 34: Exchanging Data with Other Applications

1. The path to the master.dbf.

2. A CitectSCADA project from the master.dbf .
3. A .dbf file (table) belonging to the selected project.
4. Save changes made to a .dbf file (table).
5. Save changes without re-indexing the table, or save and re-index.
6. Save a dbf file with a different name.
7. Open a dbf file in any location
However, you can also open .dbf files using the File > Open command.
Protected Tables
The installation of the Add-In incorporates a list of tables that by default are excluded
from being opened using the Add-In interface. This list is in a file called Exclud-
edProjectTables.xml and can be found in the Add-In installation directory.
These tables are system tables that are maintained by CitectSCADA, and it is rec-
ommended that these files are not edited externally in Microsoft Excel. To minimize the
likelihood of additional tables being edited with Microsoft Excel you can add their
names to the ExcludedProjectTables file using a text editor. You can also view the
default list of tables using a text editor, or an XML compliant browser.
Read Only Tables
Projects which are read only, or contain read only tables, are displayed in the list of
tables when selected from the Add-In buttons. If you try to open a read-only table (.dbf
file) an alert (sometimes referred to as a "warning") message is displayed advising that
the table is read only. You can still open and edit a read only table but you will not be
able to save it.
A table could be read-only for the following reasons:
l The project is read-only.
l The table is open in the CitectSCADA Project Explorer.
l The user trying to edit the file does not have read and/or write privileges.
If you attempt to save a read-only table an alert message is displayed advising that the
table is read only.
See Also

Functionality

982
Chapter 34: Exchanging Data with Other Applications

Functionality
The add-in is automatically available to Excel when the add-in is installed by the Citect-
SCADA installation. When you open Microsoft Excel you will see a new toolbar called
Project DBF Add-in, containing the following fields and buttons:
1. Master.dbf location
2. SaveDBF table
3. SCADA project
4. SCADA table
5. Save DBF
6. Save As
7. Open DBF
8. Save Only/Save and re-index
To access the tables using the Add-In:

1. If the location of the Master.dbf file is not displayed in the master.dbf location field, it
will display Enter path to master.dbf. Click on this field to display a dialog box
where you can enter the location. This populates the SCADA Project field.
2. Click the drop down arrow in the SCADA Project Field to select the Project in which
the .dbf file (table) resides that you want to open. This populates the SCADA Table
field.

Note: Any tables listed in the ExcludedProjectTables.xml are excluded from the list of
tables.

3. Click the drop down arrow in the SCADA Table field to select the table. The table will
open in Microsoft Excel as a new worksheet named with the table name. If the table
is a read only table an alert (sometimes referred to as a "warning") message is dis-
played advising you that it is read only.
Alternatively, if the dbf file that you wish to open is not the Master.dbf file, or is not
located in the root dbf file location, click the Open DBF button and browse to the location
of the dbf file that you want to open.
To edit the contents of the table in Microsoft Excel
A table in .dbf format is displayed in Microsoft Excel in the following equivalent format:
l A field is displayed as a column.
l A record is displayed as a row.
l A field within a record (data) is displayed as a cell.

983
Chapter 34: Exchanging Data with Other Applications

You may edit any of the data in the table, shown as cells within a row. You may delete a
record shown as a row, and add a record. However you cannot change the structure of
the table by modifying the name of any Field, shown as a column, add a column or
delete a column. If you do change the structure an alert message will be displayed when
you attempt to save the table.
If you edit a cell in the table take care not to exceed the maximum field length set for that
field in the table.
To save a table in Microsoft Excel

1. Select to Save and re-index the table, or Save Only, from the drop down control on
the toolbar.
If you do not re-index an indexed table the table will be saved more quickly, but you will
need to manually re-index the table when you have completed your edits. To re-index
manually, select Pack from the File menu of the CitectSCADA Project Editor.
2. Click the SaveDBF table button.
When you save the table the Add-In performs the following checks prior to saving the
table:
1. Verifies that the file type is .dbf.
2. Checks for any changes in table structure that may have been made. For restrictions
on changes to the table structure, refer to "To edit the contents of the table in Micro-
soft Excel".
3. Updates the existing table according to the data in the Microsoft Excel worksheet.
4. Re-indexes the updated table if it is was an indexed table (if Save and re-index was
selected).
If the edited table in the Microsoft Excel worksheets does not pass every check, an alert
(sometimes referred to as a "warning") message is displayed and the existing table on
disk will not be affected until you correct the condition that caused any check to not
pass.
You can also save a dbf file with a different name by clicking the Save As button on the
toolbar and entering a name for the file. This method of saving also includes the option
of saving the dbf file with or without re-indexing the table.

Note: If you attempt to save a table in .dbf format in Microsoft Excel using the Micro-
soft Excel File > Save command an alert message is displayed advising you that the
file cannot be saved in the current format and that use the SaveDBF button on the
Microsoft Excel toolbar.

984
Chapter 35: Genies and Super Genies
There are two types of Genies within CitectSCADA:
Genie - collection of related objects, which you add to your graphics pages when you
configure your system. You can paste any number of Genies onto a graphics page (for
example, multiple pumps on the same page).
Super Genie - dynamic pages (usually pop-ups), to which you pass information when
the page displays at runtime. You can use Super Genies for pop-up type controllers (to
control a process, or a single piece of plant floor equipment).
CitectSCADA includes libraries of Genies and Super Genies that you can use in your sys-
tem. You can also define your own and add them to a specific library to be reused again
within your project.
See Also
Genies
Configuring Super Genies

Genies
Usually each object on a graphics page is configured individually. With a Genie, you
can combine several related objects into a group, and store the group in a Genie library
(similar to a symbol library). The Genie can then be used as a single object (pasted,
moved, resized, etc.), and the elements configured collectively. Many types of graphic
objects, and their configuration data, can be stored with the Genie.
Genies work by substituting common information in an object. Genies can be groups of
objects (start/stop controller) or even one object (a button), that you may want to save in
the genie library so you can reuse it through out the project.
The advantage of using a Genie is that objects are defined once, and then after you place
the Genie onto a page, you only need to configure the substituted properties.
Before using Genies you need to understand the following term:
Substitution –A substitution can be a number or name you use to define an object or
group of object’s properties when creating a genie. Used as a placeholder the property is
replaced at runtime with a real value.
See Also
Configuring Genies
Defining Substitutions for Genies

985
Chapter 35: Genies and Super Genies

Using Genies

Defining Substitutions for Genies

To define a Genie, you use substitution strings for the properties of the objects that will
be specific to each instance. You can use substitution strings for any text property in any
object (in the group of objects). To specify a piece of text as a substitution string, enclose
the string between percentage (%) characters.

Note: The use of %AREA% within a genie substitution is not supported.

For STRING variable type substitutions enclose the %% in quotation marks e.g.
“%label%”, so that CitectSCADA does not read it as a tag.

Note: You are not restricted to using only variable tags as substitution strings. Any
expression can be substituted, such as constants or labels, or equipment.item tag ref-
erences e.g %Tank.Level%. Only fields that accept text can have Genie tag sub-
stitutions. You can also define substitutions to variables that aren't in the current
project by using the IFDEF function.

See Also
Configuring Genies
Using Genie Substitutions in Templates

Configuring Genies
Configuring a new Genie is similar to creating a page with graphical objects, but with
genies there is no background. Typically you create a new Genie using the Graphics
Builder, add the objects, defining the Genie substitutions, and save the Genie in a Genie
library.
To create a new Genie:

1. From the File menu select New.

2. Click the Genie button.
3. Create your Genie object (defining your substitutions).
In the first example a button object will be created and saved as a genie:

1. Select the button object from the drawing toolbox

2. Draw a button and in the button properties dialog:
l Configure the appearance of the button
l Configure the input command

986
Chapter 35: Genies and Super Genies

l Configure the Cicode function and its parameters.In the example the parameters have
been substituted with a placeholder.

In this example both substitutions are STRING variable types, therefore the %% char-
acters have been enclosed in quotation marks.
3. Click OK to close the button properties dialog.
4. Click the Save tool, or choose File | Save.
5. Select the Project and Library in which to store the Genie.
6. Enter a name for the Genie in Genie.
7. Click OK. (To create a new library for the Genie, click New. In the field provided
name the new library and click OK. The name of the library is added to the library
list.)
In the second example two objects are combined and saved as a genie.
A text object that shows the Level of Tank 1, and a symbol object that indicates if Tank 1
is in use.
1. Select the symbol set object from the drawing toolbox
2. Drag onto the blank genie page, the symbol set dialog will open
3. Configure the appearance of the symbol set (Type, On symbol when, OFF symbol, On
symbol)
4. Select the text object and place onto the page under the symbol.
5. Configure the text object (Type, Expression)
6. Click OK
7. Click the Save tool, or choose File| Save.

987
Chapter 35: Genies and Super Genies

See Defining Substitutions for Genies

See Also
Using Genies
Maintaining Genies

Using Genies
Once you have created (defined and saved) your Genie, you can use it on any graphics
page.
Using the first genie example (the button) from the create genie topic:

1. Click the Paste Genie tool in the toolbox or choose Edit | Paste Genie
2. In the Paste Genie dialog, select the library the genie belongs to.
3. Select the genie from the list and click OK (Or double-click the thumbnail of the
genie)
4. The genie is pasted onto the graphics page. A dialog will open, prompting you to con-
figure the properties of the genie. You will see that the field names match the ‘sub-
stitutions’ used when creating the genie. Click OK to close the dialog.

988
Chapter 35: Genies and Super Genies

At runtime the dialog values you entered into the prompt replace each substitution in
the genie.
To reuse this genie in the project you would enter a different title and example text when
prompted.

Note: To display the properties of the individual objects in a Genie (instead of the
Genie Properties), hold the Control (CTRL) key down and double-click the object. If,
however, a link to the Genie has been retained, most of these properties will be read-
only.

Using the second genie example:

For the on/off indicator you will need to configure the InUse and the Level substitution
fields.
1. Click the paste genie tool.
2. Select the library (from the Library list) that contains the Genie.
3. Select the on/off indicator and click OK.
4. The genie is pasted onto the graphics page and you are prompted to configure the
substituted values. In the example below variable tags are used but you can also ref-
erence the variable tags using the variable tag's associated equipment and item name
e.g For Line1\Tank1\Level associated equipment is Line1.Tank1, and Item Name is
Level, therefore you could reference the variable tag using Line1.Tank1.Level.

989
Chapter 35: Genies and Super Genies

The examples used above are simple uses of a Genie. You can define Genies that use
many objects, with substitution strings for any text property (or properties) of an object.

Note: If you use structured tags, you can use substitution strings within a tag name
to construct more sophisticated Genies. See Using Structured Tag Names with
Genies.

1. Click the Open tool or choose File |Open.

2. Select the Genie tab.
3. Select the Project and Library in which the Genie is stored.
4. Select the Genie.
5. Click OK.
To delete a Genie from the project, select the Genie name, and click Delete.
If you modify a Genie after you have used it in your project, occurrences of the Genie
may be automatically updated throughout the project

990
Chapter 35: Genies and Super Genies

If you modify a Genie when the project is running in the background, you need to per-
form an Update Pages to see the changes in the runtime project. If a runtime page con-
taining the Genie is displayed when the change is made, it will not be updated until you
exit then re-display it.
See Also
Configuring Genies
Using Genies
Using Genie Substitutions in Templates

Using Genie Substitutions in Templates

When you create a new custom template you can add objects to the template and con-
figure the object or group of objects as a Genie.
Configure the Genie using substitution strings (%) for the relevant properties of each
object. (If you have default values for any property, you can add the default values to the
native objects.)
Save the new template.
When you subsequently create a new page based on the template, double-click the Genie
and a single dialog will appear prompting you for the value or values of the substitution
strings used in the template. This is how the templates for trending and SPC were
created.

Using structured tags with Genies

When you define a Genie, you can add a prefix or suffix to a Genie property to generate
the complete tag when the Genie is used. For example, if you define a Genie property as
%tag%_PV, and then use DEV1 for the tag, the Genie will generate the complete tag
DEV1_PV. This is also the case if you reference the variable tag using the associated
equipment and item name, %equipment.item%_PV. if you use PUMP.SPEED for equip-
ment.item, the genie will generate the complete tag PUMP.SPEED_PV.
You can add extra information at the beginning (prefix), or on the end (suffix) of the
Genie property, or use both a prefix and suffix in the same Genie property. For example,
if you have defined a loop controller with three bar graphs (created using the fill prop-
erty in a rectangle) to display the tags DEV1_PV, DEV1_SP and DEV1_OP, you can con-
figure a Genie as follows:
Each rectangle has a separate Genie tag:

Level expression %PV_Tag%

991
Chapter 35: Genies and Super Genies

Level expression %SP_Tag%

Level expression %OP_Tag%

When you configure the Genie (with the Genie dialog), you have to enter three separate
tags: DEV1_PV, DEV1_SP and DEV1_OP. However, if you use structured tags, you can
configure the rectangles as follows:

Level expression %Tag%_PV

Level expression %Tag%_SP

Level expression %Tag%_OP

In this case, you only have to enter one tag (DEV1) to generate six objects. The Genie
automatically concatenates DEV1 with either _PV, _SP, or _OP, depending on where the
tag is substituted. As well as a reduction in configuration time, this Genie is easier to
maintain.

Note: The above example illustrates the power of Genies. The more complex and the
greater number of objects in a Genie, the greater the advantage of using structured
tags. You can also make complex Genies by using multiple variables for a Genie
property. For example, %Level%_TIC_%Occ%_PV or any combination of prefix, suffix and
number of Genie variables.

See Also
Using structured tags with Super Genies

Super Genies
Individual pages (popup controllers, loop tune pages, etc.) are often used to control and
monitor devices. Super Genies are ideal when there are many devices of the same type
within a project, because you can re-use them without re-configuring for each device.
You can configure the common properties once, which is then passed to the Super Genie
at runtime.
Before Configuring a Super Genie you need to understand the following terms:
Association- An association is a name or number tag reference that you can use when
defining a Super Genie substitution. Used with ‘Ass’ Super Genie Cicode functions to
assign, and set the dynamically generated values of the Super Genie at runtime.

992
Chapter 35: Genies and Super Genies

Substitution –Used as a placeholder, the Super Genie substitution is replaced at runtime

with a real value. A Super Genie substitution is comprised of the data type (optional)
and association that you use to define an object or group of object’s properties when cre-
ating a Super Genie.
See Also
Configuring a Super Genie
Defining Substitutions for Super Genies
Defining Associations for Super Genies

Defining Substitutions for Super Genies

You can only use Super Genie substitution in the properties of an object that accepts
tags, commands and expressions. You can also use Super Genie substitutions in log mes-
sages for object touch and keyboard commands, tool tips, page keyboard commands, or
as part of the comment for Trend objects, and Color Floods. However, you cannot use the
Super Genie syntax in a report, alarm, trend, or background Cicode function.
To mark a tag as a substitution string, enclose the tag between question mark (?) char-
acters, in the following format:
?<Data Type> <Association>?
where:
l Data Type is optional except in the case of the STRING variable type, which needs to
be explicitly specified. When Data_Type is left blank, CitectSCADA will correctly type-
cast variable types other than STRING at runtime.

Note: Explicit type casting to BCD, BYTE, LONGBCD, UINT and ULONG types is
not supported for the substituted tag. Use typeless substitutions for these types.

l Association - Can be a Number or a Name.

l Number determines which variable tag (1 to 256) will be substituted when the
Super Genie is displayed (using the Super Genie functions). If you use more than
one substitution string in your Super Genie, make your numbers sequential. This
will make the Super Genie functions easier to use.
l Name determines which variable tag or equipment.item tag reference will be
substituted when the Super Genie is displayed. For example, if a substitution is
defined with the name SPEED, and explicitly specifies the type as REAL, the sub-
stitution would be referenced as ?REAL SPEED? on the graphics page. The page
substitution may be referenced as many times as necessary on the Super Genie
page.

993
Chapter 35: Genies and Super Genies

If you do not specify a data type, it will default to TYPELESS. Typeless substitution
allows you to pass tags of BYTE, BCD, DIGITAL, INT, UINT, LONG, LONGBCD, or
REAL types, but not STRING. When you make a typeless substitution, CitectSCADA will
automatically try to convert the substituted 'data' to the correct type at runtime.

Note: You might want to use typeless substitutions because they offer more flex-
ibility, but be aware that errors can be harder to find.

See Also
Defining Associations for Super Genies
Configuring Super Genies

Defining Associations for Super Genies

You can define Associations for Super Genies two ways:
Using the Ass () Cicode functions. As part of the Cicode expression the association can
be passed directly to the Super Genie substitution. The Ass () functions are processed just
before runtime, to generate the real value of the Super Genie. However if the page asso-
ciation is not able to be performed there will be no default value or value on error avail-
able.
Using the Page Properties – Associations tab – you can reference or edit existing asso-
ciations. In using this tab you can add those associations that are currently in use in a
Super Genie substitution and define the appropriate default value and value on error
fields. You can also add a description.
See Also
Defining Substitutions for Super Genies
Configuring a Super Genie

Configuring a Super Genie

You can configure and save a Super Genie either as a page or a library object.
See Also
Configuring a Super Genie as a Page
Configuring a Super Genie as a Library Object

Configuring a Super Genie as a Page

You can configure and save a Super Genie as a normal graphics page. This means that
when you use the Super Genie you are not required to define a Genie to call it, and
instead can use any graphics object.

994
Chapter 35: Genies and Super Genies

Note: If you configure a Super Genie in this way and name the page with an ! prefix
to hide it, you need to select List System Pages from the Graphics Builder Options
menu to show the page with the other pages, so you can then select it and edit the
page.

To create a new Super Genie page:

1. From the toolbar select New, or go to File | New

2. Select Page
3. Choose a Page template and click OK
4. Define the page properties e.g. size of page
5. Place an object on the page e.g. numeric expression
6. Define the objects properties.
7. Select the type of object
8. In the expression field enter the association (placeholder) – don’t forget to enclose the
name or number in question mark characters. E.g. ?Level?

Note: When creating a Super Genie, if you reference an association that has not been
defined on the Page Properties - Associations tab, it will be assumed to be an asso-
ciation type substitution with no Default, Value on error, or Description. You will
need to define the Default, Value on error, and add a Description (if necessary)
directly in the associations tab.

9. Click OK to apply the changes

10. Select File | Save
11. In the Save dialog, select the project the page will belong to (be aware that tab options
are unavailable)
12. Name the Super Genie page and click OK

995
Chapter 35: Genies and Super Genies

In the example above there are two numeric expressions on the Super Genie page. When
configuring the Super Genie the association name Level was added directly to the page
properties- associations tab. The other association name Position will be passed to it at
runtime using an Ass() Cicode function.
See Also
Using a Super Genie Page
Configuring a Super Genie as a Library Object

Configuring a Super Genie as a Library Object

You can configure and save a Super Genie as a Super Genie library object. If you save
your Super Genie as a library object it is not saved as a normal page and thus is not
instantiated. A Super Genie library object is only instantiated when attached and then
called from a genie. Once the library object is instantiated the Super Genie can be called
from other objects.

996
Chapter 35: Genies and Super Genies

To create a new Super Genie (using the Super Genie library option):

1. From the toolbar select New, or choose File | New.

2. Click the Super Genie option.
3. A blank Super Genie library object page will open.
4. In this example a pop up that displays numerous values will be created.

5. From the tool bar select Save or go to File|Save.

6. The Save as dialog opens. The Super Genie tab is active, with no other options avail-
able. Enter a name for the Super Genie in the Super Genie field (!sg2_multi)
7. Select the Library and Project in which to store the Super Genie. Like Genie libraries,
Super Genies libraries are global and can be used between projects.
8. Click OK.

Note: The first eight characters of the Super Genie name needs to be unique for each
Super Genie. Save it in a Super Genie library using an exclamation mark (!) prefix.
This keeps the pages hidden in the configuration environment (they are visible only
if attached to a Genie).

See Also
Using a Super Genie Library Object

997
Chapter 35: Genies and Super Genies

Using a Super Genie Page

To use a Super Genie page you need to add an object to the graphics page. This object
can be anything from a new menu item, a button, or a symbol that is configured to call
the “Super Genie”. When configuring the object, you use one of the “Ass” Cicode func-
tions that at runtime replace the substituted parameters with the associated values.
If you use the ‘Ass’ Cicode function you need to use it once for each value you want to
pass to the Super Genie. If you use the ‘AssMetadata’ Cicode function matching meta-
data will be processed, with the values dynamically generated and set where applicable
on the Super Genie page at runtime.

Note: When embedding a Super Genie in another. The embedded Genie (for the
embedded Super Genie) needs to use AssMetadata functions instead of Ass func-
tions.

Using the basic Super Genie example created previously:

1. The button properties dialog will display

2. Configure the appearance of the text on the button
3. Configure the Input tab as outlined below. (In this example the Ass Cicode function
is used to highlight how an association can be passed directly from the Cicode or
defined in the page properties of the Super Genie. )

998
Chapter 35: Genies and Super Genies

Note: You can also use Equipment.Item to reference a variable tag instead of using
the variable tag name. For example:Instead of variable tag name "Milk_Level" you
may reference the tag using "MilkMixer.Level" where Milk Mixer is the Equipment
name and Level is the item Name.

4. Save the graphics page

You can use Super Genie pages more than once. For example, another button could be
added to the graphics page, with the Value defined in the Metadata tab a different var-
iable tag. When the user clicks on that button at runtime the associated value for that
variable tab will be displayed.
See Also
Using a Super Genie Library Object
Maintaining a Super Genie

Using a Super Genie Library Object

Using a Super Genie library object is initially not as simple as using a Super Genie page.
To use a Super Genie library object you need to:

l Create and save a Genie object

l ‘Attach’ the Super Genie library object to the Genie.
l Whenever you use that genie the Super Genie will be attached. You will have to
‘Detach’ the Super Genie if you do not want to use that genie with the Super Genie.

Note: When the Super Genie is attached to a genie, the Super Genie library object is
instantiated and becomes a new page in your project. This means any object can be
configured to call the Super Genie page.

Create and Save a Genie object

In the following example a button will be created and saved as a genie. The Super Genie
library object created in a previous example will then be attached to the genie.
1. Select File | New Genie
2. Draw the button that the user will click at runtime to display the popup. This button
will call a Super Genie Cicode function, which performs the associations and dis-
plays the dynamically generated values
3. Configure the input tab. In the example below the AssMetadata Cicode function is
used to call the Super Genie.

999
Chapter 35: Genies and Super Genies

4. Configure the Metadata tab – define the name | value pairs. Match the name of the
metadata with the name of the association, so the dynamically generated value is
assigned to the correct association at runtime.

Note: For metadata values with no corresponding tag configured, place the value
within single quotes otherwise a hardware alarm will be raised. For example if a
value MyTitle has been configured to substitute a Super Genie window title (?TItle?),
then configure the value as 'MyTitle'

5. Save your genie to a genie library.

Attach a Super Genie to the Genie

Attaching a Super Genie to a Genie:

1. With the Genie open, select Edit | Attach Super Genie.

2. Click Add, and the Super Genie Dialog box will open.
3. Select the library the Super Genie belongs to.
4. Select the Super Genie to attach e.g. !PopUp_SG and click OK.
5. The Super Genie is added to the Attach Super Genie list.
6. Click OK to save the changes, or click Cancel.

Note: A Super Genie can be attached to more than one Genie.

1000
Chapter 35: Genies and Super Genies

Using a Super Genie with a Genie:

1. From the graphics page select Edit | Paste Genie, browse for the Genie you just
created, and select it.
2. On Pasting the Genie, a dialog will open prompting you to fill in the fields and enter
the variable tags.

1001
Chapter 35: Genies and Super Genies

Note: To avoid compilation errors variable tags or equipment.item tag references

used in a Super Genie need to be defined in the variable tags database. Alarm tags
can also be used (allowing you to use alarm tag properties).

Using tags through Super Genies at runtime increases your dynamic license point count.
Super Genies called after you have reached your point limit will return #COM. For more
information see license point count in the Installation and Configuration Guide.
See Also
Maintaining a Super Genie
Using a Super Genie Page

Maintaining a Super Genie Page

You can open an existing Super Genie page to edit it.When you modify a Super Genie
when the project is running in the background, you will be prompted to 'Update Pages'
to see the changes in the runtime project. If a runtime page containing the Super Genie is
displayed when the change is made, it will not be updated until you exit then re-display
it.
For those pages created from a Super Genie library object, if the parameter [CtDraw.RSC]
AllowEditSuperGeniePage is set to 0 a message will be displayed that will help prevent
you from editing the Super Genie page directly. Instead you will need to edit the Super
Genie Library object that created that page.See Maintaining a Super Genie Library Object.
If the parameter [CtDraw.RSC]AllowEditSuperGeniePage is set to 1 a message will be
displayed that will ask for confirmation before allowing you to edit the page directly.

Note:Changes made to a page (created from a Super Genie library object) will be over-
ridden when you ' Update Pages'.

To open an existing Super Genie Page:

1. Click the Open tool or choose File |Open.

2. Select the Pages tab.
3. Select the Projectthe page belongs to.
4. Select the Super Genie.
5. Click OK.
To delete a Super Genie page from the project:

1. Click the Open tool or choose File |Open.

2. Select the Pages tab.
3. Select the Projectthe page belongs to.

1002
Chapter 35: Genies and Super Genies

4. Select the Super Genie and click Delete.

5. A message will display. Click Yes to delete the page from the project and its records.
Click No to delete the page from the project only. Click Cancel to cancel the operation.

Note: If you delete a Super Genie page that is in use,the object configured to call the
page at runtime will become inoperable.

See Also
Using Constants and Arrays with Super Genies

Maintaining a Super Genie Library Object

You can open an existing Super Genie library object to edit it.If you modify a Super
Genie library object when the project is running in the background, you will be
prompted to 'Update Pages' to see the changes in the runtime project. If a runtime page
containing the Super Genie is displayed when the change is made, it will not be updated
until you exit then re-display it.
To open an existing Super Genie library object:

1. Click the Open tool or choose File |Open.

2. Select the Super Genie tab.
3. Select the Projectthe Library in which the Super Genie is stored.
4. Select the Super Genie.
5. Click OK.

Note: If you delete a Super Genie page that is in use,the object configured to call the
page at runtime will become inoperable.

To delete a Super Genie library from the project:

1. Click the Open tool or choose File |Open.

2. Select the Super Genie tab.
3. Select the Projectand the library the Super Genie belongs to.
4. Select the Super Genie and click Delete.
5. A message will display. Click OK to delete the library object.
Deleting a Super Genie library object that has been attached to a Genie will not cause
that Genie to become inoperable at runtime.
See Also
Using Constants and Arrays with Super Genies

1003
Chapter 35: Genies and Super Genies

Using Constants and Arrays with Super Genies

You can use Constants and Arrays with Super Genies.
See Also
Constants
Arrays

Constants
The ability to pass constants into Super Genies is restricted in that, the constant asso-
ciation can only be where you can enter a normal Cicode tag - keyboard command, sym-
bol address field etc. The following types of constants are supported: STRING, INTEGER,
DIGITAL, REAL, and LONG.
To pass a constant you need to format the argument in the Ass function to include a sin-
gle quote on either side. For example, to pass the constant data 1.2345 into a Super
Genie, you would call the Ass function like this:

Ass(hWin, sArg, "'1.2345'");

To pass a variable tag or equipment.item tag reference, you don't need the single quotes.
For example, to pass variable tag TAG1 into a Super Genie, you would call the Ass func-
tion as follows;

Ass(hWin, sArg, "TAG1");

Or if using equipment.item to reference the variable tag:

Ass(hWin, sArg, "Pump.Speed");

?<Data Type><Substitution String>? [<element>]

Only arrays of data type DIGITAL, INT, REAL, and LONG are supported.
See Also
Using array offsets

Using array offsets

Using array offsets with a tag that is an array

If you have a tag Tag1 defined as an array of 4 elements. For example, when using the
GENERIC protocol the tag has an address I1[4]:

Tag1 = I1[4] -> I1

Tag1 represents the registers I1, I2, I3 and I4. When Tag1 is used with the Ass() Cicode
function it behaves as follows:
l If you associate a value using Ass(hWin, "X", "Tag1", 0) then the substitution string
?X?[0] gives the value in I1.
l If you associate a value using Ass(hWin, "X", "Tag1", 0) then the substitution string
?X?[2] gives the value in I3.
l If you associate a value using Ass(hWin, "X", "Tag1[0]", 0) then the substitution string
?X?[2] gives the value in I3.
l If you associate a value using Ass(hWin, "X", "Tag1[1]", 0) then the substitution string
?X?[2] gives the value in I4. This is because the two offsets are added together to deter-
mine the final offset within the array variable.
l If you associate a value using Ass(hWin, "X", "Tag1[2]", 0) then the substitution string
?X?[2] gives the error #ERR. This is because the sum of the two array offsets gives a
position (Tag1[4]) that is outside the bounds of the array.
Using array offsets with a tag that is not an array

1005
Chapter 35: Genies and Super Genies

If you have a tag Tag2 defined as a single value. For example, when using the GENERIC
protocol the tag has an address I1:

Tag2 = I1 -> I1

When Tag2 is used with the Ass() Cicode function it behaves as follows:
l If you associate a value using Ass(hWin, "X", "Tag2", 0) then the substitution string
?X?[0] gives the value in I1. This is because a non-array tag is equivalent to an array
with one element.
l If you associate a value using Ass(hWin, "X", "Tag2[0]", 0) then the substitution string
?X?[0] gives the value in I1. This is because a non-array tag is equivalent to an array
with one element.
l If you associate a value using Ass(hWin, "X", "Tag2", 0) then the substitution string
?X?[2] gives the error #ERR. This is because a non-zero offset cannot be applied to a
non-array tag.
l If you associate a value using Ass(hWin, "X", "Tag2[0]", 0) then the substitution string
?X?[2] gives the error #ERR. This is because a non-zero offset cannot be applied to a
non-array tag.
l If you associate a value using Ass(hWin, "X", "Tag2[1]", 0) then the substitution string
?X?[2] gives the error #ERR. This is because a non-zero offset cannot be applied to a
non-array tag.
l If you associate a value using Ass(hWin, "X", "Tag2[2]", 0) then the substitution string
?X?[2] gives the error #ERR. This is because a non-zero offset cannot be applied to a
non-array tag.

Nesting Super Genies

CitectSCADA allows you to nest Super Genies. Nesting refers to where one Super Genie
is embedded in another. For this to work, the embedded Genie (for the embedded Super
Genie) need to use AssChain functions instead of Ass functions.
See Also
Super Genie areas

Super Genie areas

When you display a Super Genie, the area of the Super Genie is inherited from its par-
ent. For example, if the parent page is in area 1, when you display a Super Genie it will
also be area 1. This allows you to call the same Super Genie from different pages in dif-
ferent areas.

1006
Chapter 35: Genies and Super Genies

The inherited area may be avoided by defining the Super Genie to have a specific area.
Then, every instance of the Super Genie will have the same area, no matter which area
its parent is from. Super Genies will only inherit areas if their area is blank.

Super Genie Library Objects and Associations

When you define a Super Genie, you are actually creating a Super Genie template, sim-
ilar to a page template. When a Genie calls the Super Genie library object, this template
is used to create a new Super Genie page. At this point, any Associations saved with the
template are copied across to the Super Genie page. However, if subsequent changes are
made to the Associations of the template, the Associations of the Super Genie page are
not updated.
After the Super Genie template associations have been modified the Super Genie page
created from the template needs to also be updated. If it is not updated then your page
may display out-of-date e associations.

Using structured tags with Super Genies

Super Genies do not support direct concatenation of the Super Genie tag with other infor-
mation (as do Genies). For example, ?INT 1?_PV is not valid and will generate a com-
piler error. However, you can concatenate the tag using a Cicode expression. You need to
use a unique Super Genie variable for each real tag, and concatenate the tag with the
Ass Cicode function. For example, if you have defined a loop controller with three bar
graphs (created using the fill property in a rectangle) to display the tags DEV1_PV,
DEV1_SP and DEV1_OP, you can configure a Super Genie as follows:
Each rectangle has a separate vGenie tag:

Level expression ?INT 1?

Level expression ?INT 2?

Level expression ?INT 3?

If you do not use structured tags, you can call the Ass function for the above Super
Genie as follows:

AssPage("PageName", "DEV1_PV", "DEV1_SP", "DEV1_OP");

OR using equipment.item

1007
Chapter 35: Genies and Super Genies

AssPage("PageName", "Equip1.item_PV", "Equip1.item_SP", "Equip1.item_OP");

To concatenate information for the Super Genie, you could also write your own Cicode
function, as follows:

FUNCTION
AssMine(STRING sPage, STRING "DEV1")
AssPage(sPage, sTag + "_PV", sTag + "_SP", sTag + "_OP");
END

OR using equipment.item

FUNCTION
AssMine(STRING sPage, STRING "Equip1.Item")
AssPage(sPage, sTag + "_PV", sTag + "_SP", sTag + "_OP");
END

With this function, you can call your AssMine() function (for example, from a command
button), and pass a single tag (DEV1), as follows:

AssMine("PageName", "DEV1");

OR using equipment.item

AssMine("PageName", "Equip1.Item");

Writing your own Cicode function to call a Super Genie provides extra flexibility; how-
ever, you can also use a Super Genie (for example, from a button command) to call the
Ass function, as follows:

Execute command with tag AssPage("%Page%", "%tag%_PV", "%tag%_SP",

"%tag%_OP");

Execute command using equip- AssPage("%Page%", "%Equip1.item%_PV",

ment.item reference "%Equip1.item%_SP", "%Equip1.item%_OP");

When you use the above Super Genie, you only enter the page name and tag or equip-
ment.item once.
You need to pass the tag name (by enclosing it in quotation marks) to the Super Genie
functions. You cannot pass the tag values. For example, if you pass %tag%_SP (no
quotes), the value of the variable and not the tag name is passed to the Super Genie, and
the association will not succeed, and a runtime error may result.
See Also
Using structured tags with Genies

1008
Chapter 35: Genies and Super Genies

Hiding Graphics Objects

You can configure a graphics object so that if the variable tag specified for the object is
not defined in the tag database at compile time, the object does not display on a graphics
page.
The expression entered in the Hidden Whenfield of an object's property is used to deter-
mine if the object will display. The expression evaluates to either TRUE or FALSE and
the object is hidden when the expression is TRUE.
You define the variable tag and conditions under which the object is hidden by entering
an IFDEF statement into the Hidden When field when you configure the object. The
IFDEF statement is evaluated by the compiler and the value of the resulting expression
or variable tag will determine whether or not the object is hidden.
This can significantly reduce the number of necessary genies, as the configuration engi-
neer does not need to generate several smaller genies to cater to operations driven by a
slightly different range of tags.
See IFDEF macro for more information on using the IFDEF macro for hiding graphics
objects. For more information on the IFDEF macro in general, see IFDEF.

IFDEF macro
The IFDEF statement consists of three arguments:

IFDEF (<"Tag Reference">, <Hidden When value if tag defined>, <Hidden When value if
tag
undefined>)

The first includes a tag reference (variable tag name or Equipment.Item). If the variable
tag is defined in the tag database at project compilation, the IFDEF statement is replaced
in the Hidden When field by the second argument. If the variable tag is undefined, the
Hidden When field will contain the third argument.
Example 1

IFDEF("Bit_1", 0, 1)

In the above example, if Bit_1 is defined in the tag database, the value in the Hidden
When field will be 0. If Bit_1 is undefined, the value will be 1. Since the object is hidden
when the value is TRUE, the object will be hidden when BIT_1 is undefined (i.e. when
the Hidden When field contains 1).
Example 2

1009
Chapter 35: Genies and Super Genies

IFDEF("Bit_2",,"1")

If the second argument is omitted, as in Example 2, the variable tag specified in the first
argument is used. If Bit_2 is defined, therefore, the Hidden When field will contain Bit_
2. The value of the variable tag Bit_2 is then used to determine if the object is hidden. A
non-zero value will equate to TRUE, causing the object to be hidden.
If Bit_2 is undefined, the Hidden When expression evaluates to 1 (TRUE) and the object
is hidden.
To enter an IFDEF statement in the Hidden When Field:

1. Double-click the graphics object for which you want to edit the field.
2. Select the Appearance tab.
3. Click the Hidden When field and enter the IFDEF statement.
4. Click OK.

1010
Chapter 36: Multi-Language Projects
CitectSCADA supports a language switching capability that allows text within the run-
time environment to be translated into a variety of languages.
Items such as alarm descriptions, button text, keyboard/alarm logs, graphics text and
Cicode strings can be marked for translation during the configuration of a project, and
then displayed in a specified language at runtime. A project can support multiple lan-
guages, and you can dynamically switch between them.

Note: Text translation does not happen automatically. A language can only be sup-
ported if the required translations are manually inserted into localized language data-
bases.

See Also
Preparing a project for multi-language support
Setting the local language used at runtime
Changing the local language during runtime

Preparing a project for multi-language support

To properly prepare a project for multi-language support, you need to consider the fol-
lowing procedures:
l Defining the languages supported by a project
With the release of version 7.30, a CitectSCADA project includes a database
named LANG.dbf. This database specifies which local languages you would like a
project to support. During compilation, a local language database is created for
each language defined in LANG.dbf.
See Defining the languages supported by a project.
l Translating the language databases
Local language databases are used to define the translations from native language
to local language. When a project is compiled, any text that is marked for trans-
lation is drawn into the supported language databases. You can then manually
edit a databases to define the translations required for the specified language.
Recompiling the project will then capture the translations you have input.
See Translating the language databases.

1011
Chapter 36: Multi-Language Projects

l Marking text and alarm text for translation

Language change indicators are used to identify any text you would like trans-
lated at runtime.
CitectSCADA distinguishes between a project's native language (that is, the lan-
guage used by the developer during configuration), and the local language (the lan-
guage displayed to the end user). Based on this principle, any text marked with a
language change indicator can be converted from native language to a local lan-
guage at runtime.
See Marking text for translation and for alarm specific strings Marking alarm text
for translation.
See Also
Setting the local language used at runtime

Marking text for translation

During project development, you need to mark any text you want change to another lan-
guage at runtime with a language change indicator, like this:
@( Native Text [,Width [,Justify]])
where Native Text is the text to be translated. This text will be replaced by the local equiv-
alent at runtime.
Be aware that the brackets are necessary as they specify the extent of the native language
text; Width and Justify are optional (indicated by the square brackets).
For example, if English is the native language, you could enter the following alarm
description:

Equipment Desc: @(Pump, 20, R)

This indicator serves two purposes; it flags the text as native, and tells CitectSCADA to
change the text from native to local at runtime.
By default, the text that you enter here can be in any combination of upper- and low-
ercase. In other words, Motor Inoperative will be considered the same string as motor
inoperative or MOTOR Inoperative, and they will have the same local language trans-
lation. Case-sensitivity can be introduced by setting the [Language]CaseSensitive param-
eter to 1.

1012
Chapter 36: Multi-Language Projects

Note:
1. The [Language]CaseSensitive parameter does not apply to alarm strings. Alarm
strings are always case sensitive. For example Motor Inoperative is different to
MOTOR INOPERATIVE.
2. Alarm fields no longer support Width and Justify options.
Refer to the topic Marking Alarm Text for Translation for more information

Width can be assigned any value from 0 to 254. If the local text is longer than specified,
it is truncated and left-justified. If a width is not specified, the field is the length of the
local text and the text left-justified.
Justify specifies the text justification and can only be used with Width.
Justify can be one of the following values:
l l or L - Left
l r or R - Right
l c or C - Center
l n or N - None
For example, to limit the local text in the previous case to 20 characters with right jus-
tification:

Equipment Desc: @(Pump, 20, R)

Characters that are normally part of the formatting - @ , () - can also be used within the
native text. To do this, place a caret (^) character before them. For example, to include a
comma without introducing a formatting error:

Equipment Desc: @(Pump^, overload, 20, R)

Note: The caret (^) character does appear at runtime or in the language database.

See Also
Defining the languages supported by a project

Marking alarm text for translation

During project development, you need to mark any alarm text you want change to
another language at runtime with a language change indicator.

1013
Chapter 36: Multi-Language Projects

As of v7.40 partial translation of alarm related strings such as "ABC@(DEF)” or “@(ABC)

DEF” and multiple markers per sentence such as “@(ABC)DEF@(IJK)” is no longer sup-
ported. During compilation, the @ at the beginning of the sentence is accepted and the
brackets removed so that the whole sentence will be translated. Any “@(“ encountered in
the middle or end of the sentence (anywhere not at the beginning) will trigger a compiler
alert message and will be removed.

Note: For alarm related strings the Escape character ^ is removed during com-
pilation. When used immediately preceding a valid translation marker such as ^@
(text), it will skip translation and will be removed.

The following table outlines translation marker scenarios and what will happen if:

Compiler Error
Scenario Translated Display as Language
message

@(Text) Yes Text In selected lan- None

guage

@(Text) some No Text some text In default lan- Unsupported

text guage e.g. Eng- syntax for mark-
lish ing translation
text, it will not
be translated.

Some text @(at No Some text at the In default lan- Unsupported

the end) end guage e.g. Eng- syntax for mark-
lish ing translation
text, it will not
be translated.

Some text @(in No Some text in the In default lan- Unsupported

the middle) and middle and more guage e.g. Eng- syntax for mark-
more lish ing translation
text, it will not
be translated.

@(Text) and @ No Text and more In default lan- Unsupported

(more text) text guage e.g. Eng- syntax for mark-
lish ing translation
text, it will not
be translated.

@@(Text) No Text In default lan- Unsupported

guage e.g. Eng- syntax for mark-
lish ing translation
text, it will not
be translated.

@(Text )@ Text) Yes Text @ Text In selected lan- None

guage
Note: @ by

1014
Chapter 36: Multi-Language Projects

Compiler Error
Scenario Translated Display as Language
message

itself is regarded
as a normal char-
acter, trans-
lation marker
requires @ to be
immediately fol-
lowed by ( and a
) to follow later.
The string will
appear in the
local language
DBFs as “Text
@Text”. Double
layers of trans-
lation markers
are invalid.

See Also
Defining the languages supported by a project

Defining the languages supported by a project

In version v7.40 to set up multi-language support in your project, complete the fol-
lowing:
1. Define the required languages in System -> Languages form for the main project e.g.
French(France) and Japanese(Japan).
2. Define the default language for your project in the System -> Parameter form e.g
French
3. In the include project (if any and not a standard Include project) define languages in
System ->Languages eg. French(France) and Japanese(Japan)
4. Compile and generate language DBFs
5. Open language DBFs and insert translation (for main and include projects)
6. Recompile to reflect new translations

Note: The language defined in the Citect.INI file will take precedence over the default
language defined in your project. For more information refer to Rules for using
parameters.

On defining your required languages in Vijeo Citect this will update the project database
LANG.dbf. This database is used to specify the local languages you would like a project
to support. It also determines if OEM conversion is required for a particular language.

1015
Chapter 36: Multi-Language Projects

Next define the default language to be used in your project. This needs to be one of the
languages you defined in the Lang.dbf.
During compilation, a local language database (eg. French.DBF) is generated for each lan-
guage defined in LANG.dbf. If the project, does not have an existing database for one of
the specified languages, one will be created with its native column populated with
native strings and local column empty.
Once this process is complete, an .rdb file is added to the master project for each defined
language to facilitate the operation of multi-language switching during runtime.
The following table provides an example of how LANG.dbf would impact the project
"MasterProject1" when compiled.

Existing .rdb files

and newly created
Lang.DBF lan- .dbf Files created
Project name defined lan- during
guages during compilation
guage data- com-
bases pilation

Runtime
Local Language Databases
Database

lanen.rdb
lanfr-fr.rdb

lanja-
JP.rdb
French(France)
French(France).dbf Plus RDBs
MasterProject1 English English.dbf
Japanese(Japan).dbf for lan-
Japanese(Japan)
guages
defined in
default
include
projects

If your master project includes an Include project (not one of the include projects
included with Vijeo Citect) you will need to define the supported languages within your
include project as well as in the master project.
The following table provides an example of how LANG.DBF would impact the project
“MasterProject1” when linked to "IncludeProject1" which has its own existing language
databases.

1016
Chapter 36: Multi-Language Projects

Existing .rdb files

and newly created
Lang.DBF lan- .dbf Files created
Project name defined lan- during
guages during compilation
guage data- com-
bases pilation

Runtime
Local Language Databases
Database

MasterProject1 French(France) English.dbf French(France).dbf lanen.rdb

English (1) lanfr-fr.rdb
Japanese(Japan) Japanese(Japan).dbf (1 & 2 are
merged)
lanja-
JP.rdb
lanko-
KR.rdb
Plus RDBs
for lan-
guages
defined in
default
include
projects

IncludeProject1 French (France) English.dbf

English French.dbf (2)
Korean(Korea) Korean(Korea).dbf

If a project and one of its included projects have variations of the same language data-
base, the translations will be merged into the ‘.rdb file’, in the table above the French
files (1 & 2) were merged.
You can also see that during compilation the Korean.dbf was created and added to the
"MasterProject". Once you have defined the required languages, and defined the default
language for your project you can open the language DBFs and insert translation (for
main and include projects).

Note: If you do not define any languages in LANG.dbf, CitectSCADA will create a
default file _lanEN.rdb The native text will be used for the associated translations.

To define the languages supported by a project:

1. In Project Editor, select Languages from the System menu. The Languages dialog box
appears.
2. In the Languages dialog, choose the required language from the drop down list and
enter the required language properties.
3. Click Add to append a new record, or Replace to modify an existing record.

1017
Chapter 36: Multi-Language Projects

Note: When setting the properties for you will be required to associate a setting for
the parameter [CTEDIT]ANSIToOEM for each language. This parameter defines
whether or not the language requires translation to OEM. See the topic OEM char-
acter sets for more information.

See Also
Languages Properties
Translating local language database
Defining CitectSCADA unsupported languages

Languages Properties
Languages have the following properties:
Language
Select the language from the drop down list provided.
Source File (Optional)
A file which contains translation for the chosen language. Enter the complete file name
(with extension) For example, Spanish.DBF.
The compiler raises an alert for any specified file names with the wrong extension or
without an extension.
If a file is specified but cannot be found, the compiler creates a DBF file in that name
with empty translations.
If this field is empty and “English(Australia)” has been chosen, the compiler will look
for “English(Australia).DBF” first, if not found, then “English.DBF”, if still not found, it
will create a file named “English(Australia).DBF” with empty translations.
ANSIToOEM
This field corresponds to the Citect.ini parameter [CTEDIT]ANSIToOEM, which deter-
mines if ANSI to OEM translation is required to support a language. Once you associate
a setting for this parameter with a language, the parameter will be adjusted accordingly
whenever the language is implemented. (See OEM character sets for more information.)
Comment
Any useful comment (optional).
See also
Defining the languages supported by a project

1018
Chapter 36: Multi-Language Projects

Defining CitectSCADA unsupported languages

If necessary you can specify (in System ->Language (LANG.DBF)), languages that are not
officially supported by CitectSCADA. The format for specifying a non-CitectSCADA-sup-
ported language needs to follow windows language and region definitions.
The format for specifying an unsupported language is: <LanguageName>(<Region-
Name>)
For example,
Hebrew(Israel),where the language name is “Hebrew”, and the region name is “Israel”.
Chinese (Traditional)(Taiwan), where the language name is “Chinese (Traditional)”, and
the region name is “Taiwan”.
When an unsupported language is specified in LANG.DBF and is used at login (i.e.
LoginForm(), Login() or UserLogin() cicode functions), the runtime will display the
prompt line “Unsupported language” and display the content in the specified language.
If the specified language is unsupported, some system texts are displayed in English
rather than the specified language, such as the Alarm SOE message field. It is possible
that the system may not be able to determine the character set of a non-CitectSCADA-sup-
ported language. In this case, you need to provide their desired character sets by:
l setting [Language]CharSet = <value>,
l calling ParameterPut(“Language”, “CharSet”, <value>)
Allowable values for <value> are:
l 0 - ANSI ASCII
l 1 - System Default Character Set
l 128 - Japanese - Shift JIS
l 129 - Korean - Hangul
l 130 - Korean - Johab
l 134 - Chinese - simplified GB2312
l 136 - Chinese - traditional Big5
l 161 - Greek
l 162 - Turkish
l 163 - Vietnamese
l 177 - Hebrew
l 178 - Arabic
l 186 - Baltic

1019
Chapter 36: Multi-Language Projects

l 204 - Russian
l 222 - Thai
l 238 - East European
See Also
Setting the local language used at runtime

Translating local language databases

The local language databases created during compilation are located in the project direc-
tory. Each consists of two fields: NATIVE and LOCAL.
Any text that is marked with a language change indicator is automatically entered in the
NATIVE field when a project is compiled. Text that has been marked since the last com-
pile is appended to the database; the rest of the database remains unchanged.
To include the required translations for a specific language, open the associated database
in a database editor (such as Microsoft Excel™ with DBF Add-in) ™) and enter the local-
ized translations in the LOCAL field.
For example, French.dbf may have the following translations added to it:

NATIVE LOCAL

Line Disconnected Alarm at Line Speed alarme "Ligne deconnectee" sur la vitesse de
la ligne

Main Menu page Page du menu principal

Conveyor Belt Trip Tapis roulant declenche

When the project is run, the French translations will display in place of the associated
native text.
If you do not enter a local equivalent for a native text string, the native text is displayed
by default. You can specify to display "#MESS" instead of the native text by setting the
[Language]DisplayError parameter to 1 (one); the default is 0 (zero).

Note: The [Language]DisplayError parameter does not apply to alarm strings.

A language database can contain entries which are not actually included in a project.
This means that a single language database can be developed that is applicable to many
projects.
Once you have completed adding translations to a database, you will need to recompile
the project to implement the changes.

1020
Chapter 36: Multi-Language Projects

Note: After translation, review the foreign language interface and verify that trans-
lated strings fit in their graphics elements correctly.

See Also
Setting the local language used at runtime

Setting the local language used at runtime

The default local language that gets displayed at runtime is determined by the Citect.ini
parameter [Language]LocalLanguage. However, the language entered in this parameter
should be pre-defined in the Lang.dbf file. Once this parameter is set (and the steps out-
lined in Preparing a project for multi-language support are complete), you can then con-
figure either the Login(), UserLogin() and LoginForm() functions to set the preferred
language for the project at runtime.
When the user logins to the project at runtime, any marked native text will be replaced
by the preferred language defined in the corresponding.dbf file.

Note: To use characters for Baltic, Central European, Cyrillic, Greek, Turkish, and
Asian languages, or right-to-left languages (Arabic, Hebrew, Farsi, and Urdu) the
operating system needs to have the corresponding language version of Windows, or
have installed system support for that language.

See Also
Logging data in different languages
Changing the local language at runtime

Logging data in different languages

Alarm and keyboard logs can be processed in both the native and the local language.
This means that both native and local users can read the historical logs. The logs can
employ the same device, or separate devices.
Logs in the local language are produced using the standard field names. For example, if
{NAME} {DESC} {COMMENT} is entered in the format field of an alarm category, the alarm
name, description and comment of alarms in that category will be logged in the local lan-
guage.
All fields which support the automatic language change facility can also be logged in
the native language. To do so, just precede the field name with NATIVE. For example, to
log the name, description and comment of a category of alarms, enter {NATIVE_NAME}
{NATIVE_DESCRIPTION} {NATIVE_COMMENT} in the format field for that category.

1021
Chapter 36: Multi-Language Projects

To log both native and local to the same device, just enter the standard fields, and the
native fields together in the format field. To log them to different devices, use a Group of
two devices, and enter the local fields as the format for one, and the native fields as the
format for the other.
See Also
ASCII and ANSI character sets

Changing the local language at runtime

The language of runtime display items such as alarm descriptions, button text, key-
board/alarm logs, graphic text, Cicode strings and so on can be changed using one of the
following functions: Login(), UserLogin() and LoginForm(). Normal operations of the
project continue unaffected.
Local translations that are missing from the specified language database are replaced by
the native equivalent. You can specify to display "#MESS", instead of the native text, by
setting the [Language]DisplayError parameter to 1 (one); the default is 0 (zero).

Note:
1. The [Language]DisplayError parameter does not apply to alarm strings.
2. : For alarm data where there are multiple clients and one user name, a scenario
may occur where the runtime display shows a variety of languages. For more infor-
mation refer to Alarm data localization.

See Also
Logging data in different languages

Alarm data localization

Alarm data localization is saved in user accounts on alarm servers. For each user
account, the last login action across the network determines the current language setting
of the user. If the same user account is used simultaneously with different languages on
each of the display clients the runtime display may show a mixture of languages.
For example: Client A , Client B, Client C all log in (different clients) with the user name
“Operator”:
1. Client A logs into “Operator” with French. Once login has been successful, the dis-
play contents in Client A are in French, including both UI and alarm data.
2. Client B then logs into “Operator” with English. Once login has been successful, the
display contents in Client B are in English, including both UI and alarm data. How-

1022
Chapter 36: Multi-Language Projects

ever, the alarm data in Client A is in English instead of French. Thus Client A would
display both French and English even though Client A has logged in with French.

3. Client C then logs into “Operator” with German. Once login has been successful, the
display contents in Client C are in German, including both UI and alarm data. How-
ever, the alarm data in Client A and Client B are in German instead of French or Eng-
lish. Thus Client A would display both French and German even though Client A
has logged in with French, and Client B would display both English and German.
In this scenaio allow Client A, Client B and Client C to use separate accounts, such as
“OperatorA”, “OperatorB”, “OperatorC”. This will then allow each user to view the run-
time display in their preferred language.
See Also
Setting the local language used at runtime

ASCII and ANSI character sets

Each screen character is defined by a code (number). Operating systems and appli-
cations need to know these codes to attach meaning to individual characters. A char-
acter set provides a code for every character. For your operating system/application to
interpret a character correctly, you need to use the correct character set.

Note: Character sets are distinct from fonts. A font defines the visual/appearance
properties of a character, not its meaning.

ASCII (American Standard Code for Information Interchange) is a widely adopted 7-bit
code specifying the basic alphanumeric character set of the English language. For exam-
ple, the character capital "A" has the ASCII value of 65, the character lowercase "a" a
value of 97.
The ASCII character set contains 96 characters and is commonly used as a standard for
protocols and files.
Much of CitectSCADA uses ANSI (American National Standards Institute) character sets.
ANSI character sets are language-based, with each different language version of Win-
dows (French, Korean and so on) requiring a specific ANSI character set. Codes 32 to
127 contain standard ASCII characters.
Windows uses Unicode, but still supports ANSI character sets. Several of CitectSCADA's
utilities have been created for Unicode, for instance Process Analyst. Unicode accom-
modates known character sets by having one 16-bit (worldwide) character encoding
standard.
See Also
OEM character sets

1023
Chapter 36: Multi-Language Projects

OEM character sets

OEM character sets are those which are used by MS-DOS or Console applications (they
are operating system dependent). Most OEM character sets do not match the ANSI char-
acter sets. For example, line drawing characters commonly used in MS-DOS character
sets were replaced with language characters in ANSI character sets.
As explained below, when building multiple language projects give adequate con-
sideration to the role that ANSI and OEM character sets play, in the way the language
strings are stored and interpreted.
Language configuration information is stored in dBASE files (a database standard
defined primarily for MS-DOS applications) where string information is customarily
stored as OEM characters. When using a Windows application (such as Excel) to edit
dBASE files, the characters on screen are in the ANSI character set. When you save this
information to the dBASE file, Excel converts it to an OEM equivalent. For this con-
version to work correctly the OEM character set needs to be compatible with the ANSI
character set used in Excel. For example, if you have prepared strings for a project in
Russian (using Excel), the OEM character set needs to support the Russian (Cyrillic) char-
acter set. The OEM character set used by Windows is primarily determined by your sys-
tem setup and cannot easily be changed. This presents a challenge for multi-language
projects.
For example, consider a project intended to support Russian, French, and English. Excel
is used to prepare the language dBASE files. When saving information from Excel, it is
translated from the respective ANSI character sets to the OEM equivalent. To display
this information, CitectSCADA will need to convert it from OEM back to ANSI. How-
ever, Russian requires a Cyrillic OEM character set and French and English requires a
Latin OEM character set. Because Windows can only use one OEM character set at a
time (which cannot be changed dynamically), only one of the three project languages can
be correctly supported during any given session.
The only way to support multiple languages with differing character sets within one
CitectSCADA project, is to verify that the language information you store in dBASE files
is stored in the ANSI (not the OEM) format. Further, the [CtEdit]ANSItoOEM parameter
needs to be set to 0 (zero) to prevent a conversion from occurring automatically. The chal-
lenge for the developer in preparing the project is in saving this information in the first
place, because most applications store the language information in OEM format.

Note: A multi-language project is included in the samples directory on your instal-

lation CD. This project allows you to enter information into the language dBASE files
in ANSI format.

1024
Chapter 37: Working with Multiple Monitors
Multiple monitors are now supported in the core product instead of within a set of tem-
plates. CitectSCADA runtime will display a new window on each of the multiple mon-
itors at start-up. Once the windows are displayed, the user can use the standard page
navigation functions to change pages on the individual window. The built-in page navi-
gation functions work under the multi-monitor environment. Several built-in Cicode
functions are made available for the user to query information for each of the monitors
installed on the machine for further customization.
Multiple monitors are configured by CitectSCADA at startup as follows:
l Reads [MultiMonitors] Monitors to determine which monitors will be shown with
CitectSCADA windows.
l Enumerates through the specified monitors and show a new CitectSCADA window
at the origin of each of the monitors. The page to be displayed on each monitor will
be determined by the parameter [MultiMonitors] StartupPage<n>.
l Once a CitectSCADA window is displayed on each of the specified monitors, you can
use the standard page navigation functions to display a page on each of the win-
dows independently.
If this conflicts with your own implementation of multiple monitors support, for exam-
ple if you are using CSV templates, you can disable the core support by setting param-
eter [MultiMonitors] DisableAutoStart to 1.
See Also
Configuring Startup Pages for Multiple Monitors
MultiMonitors Parameters in the Parameters documentation

Configuring Startup Pages for Multiple Monitors

You can display several graphics pages simultaneously across multiple computer
screens. If your hardware can run multiple monitors off a single computer, you can dis-
play a different page on up to eight screens at a time.
To successfully run your project across multiple monitors, adjust the following param-
eters:
l [MultiMonitors]Monitors. Adjust this parameter to indicate how many monitors your
project will be running on.

1025
Chapter 37: Working with Multiple Monitors

l [MultiMonitors]StartupPagen. This parameter determines which page will appear on

each monitor at startup. You have to duplicate this parameter for each monitor. For
example, StartupPage1 determines the page that appears on the first monitor at
startup, StartupPage2 determines what appears on the second monitor, and so on. If
you do not specify a startup page for a particular monitor, the page specified in
parameter [Page]Startup will be displayed.
Many types of hardware support multiple-monitor display. CitectSCADA has been
tested on a PC with multiple outputs from a single video card, but not on other archi-
tectures. The ability to display project pages on multiple screens might be affected by
hardware architectures that have not been tested.
See Also
MultiMonitors Parameters

Using an OPC DA Server

1026
Chapter 37: Working with Multiple Monitors

To determine which OPC DA interfaces are supported by the CitectSCADA OPC DA

Server, see the topic Supported OPC DA Server Interfaces in the reference section of this
chapter.
See also
Configuring the OPC DA Server
Operating the OPC DA Server at runtime
OPC DA Server diagnostics
Reference Information

Configuring an OPC DA Server

A CitectSCADA OPC DA Server is configured via the OPC DA Server Properties dialog
in Project Editor, which is accessible via the Servers menu.
You can configure as many OPC DA servers as required in a project, however you can
only have one per computer.

Note: To successfully operate an OPC DA Server, you will need to correctly configure
its DCOM settings based on your client requirements. See the topic OPC DA Server
DCOM settings.

OPC DA Server Properties

An OPC DA Server has the following properties:
Server Name
A unique name for the OPC DA server.
Network addresses
The IP address of the computer that will host the OPC DA server. You can only con-
figure one server per computer.
Browsing Hierarchy
The field allows you to select the type of hierarchy to use for OPC item browsing. The
options are:
l Flat
l Hierarchy

1027
Chapter 37: Working with Multiple Monitors

Selecting Flat will present tags at a single level represented by their tag names. Selecting
Hierarchy presents the tags in a directory structure that represents the clusters and equip-
ment definitions that are used.
No selection is the default, which is the equivalent of selecting Flat.
For more information, see OPC Item Browsing.
Comment
Any useful comment (optional).

Extended forms fields

The following fields are implemented with extended forms (press F2).
Additional OPC Item Vendor Properties:
Field
Selecting True will expose the Field tag extension as an OPC DA vendor-specific prop-
erty of the OPC item. No selection is the default, which is the equivalent of selecting
False.
Valid
Selecting True will expose the last valid value for the Valid tag extension as an OPC DA
vendor-specific property of the OPC item. No selection is the default, which is the equiv-
alent of selecting False.
OverrideMode
Selecting True will expose the OverrideMode tag extension as an OPC DA vendor-spe-
cific property of the OPC item. No selection is the default, which is the equivalent of
selecting False.
ControlMode
Selecting True will expose the ControlMode tag extension as an OPC DA vendor-specific
property of the OPC item. No selection is the default, which is the equivalent of selecting
False.
Status
Selecting True will expose the Status tag extension as an OPC DA vendor-specific prop-
erty of the OPC item. No selection is the default, which is the equivalent of selecting
False.
Override
Selecting True will expose the Override tag extension as an OPC DA vendor-specific
property of the OPC item. No selection is the default, which is the equivalent of selecting
False.

1028
Chapter 37: Working with Multiple Monitors

OPC DA Server DCOM settings

To manage user access to an OPC DA Server, it is recommended that you create a Win-
dows user group with appropriate DCOM settings on the host server rather than dealing
with Windows user identities individually. You can then just add users to this group as
required. In the case of Windows 2003 and Windows 7, you can make use of the built-in
system group "Distributed COM users". Otherwise, see the Windows documentation for
information on how to create a user group.
Once the required user group has been created, you need to configure the following:
l Configure the machine-wide user group DCOM settings
l Configure the OPC DA Server specific settings
l Configure the connectivity environment settings
To configure the machine-wide user group DCOM settings

1. Launch the Windows Component Services manager. To do this, go to Control Panel,

open Administrative Tools and then Component Services.
2. Expand the Component Services folder, and the Computers folder.
3. Right click on the My Computer folder, and select Properties.
4. Go to the COM Security tab.
5. In the Access Permissions section , click on the Edit Limits button. Make the fol-
lowing adjustments:
l add the OPC DA Server users group you have created
l allow both Local Access and Remote Access for the users group
l click OK
In the Access Permissions section, now click on the Edit Default... button. Make
the following adjustments:
l add the OPC DA Server users group you have created
l allow both Local Access and Remote Access for the users group
l click OK
6. In the Launch and Activation Permissions section, click on the Edit Limits button.
Make the following adjustments:
l add the OPC DA Server users group you have created
l allowLocal Launch, Remote Launch, Local Activation and Remote Activation
for the users group

1029
Chapter 37: Working with Multiple Monitors

l click OK
7. You can now exit the Properties dialog.
To configure the OPC DA Server specific settings

1. Launch the Windows Component Services manager. To do this, go to Control Panel,

open Administrative Tools and then Component Services.
2. Expand the Component Services folder, the Computers folder, the My Computer
folder, and the DCOM Config folder.
3. Locate the "Schneider Electric SCADA OPC DA Server" component and select Prop-
erties.
4. Go to the Security tab.
5. In the Launch and Activation Permissions section, select Customize and click on the
Edit button. Make the following adjustments:
l add the OPC DA Server users group you have created
l allow Local Launch, Remote Launch, Local Activation and Remote Activation
for the users group
l click OK
6. Go to the Identity tab. This is where you define which user accounts can run the
OPC DA Server. The setting you choose will have the following implications:
l The interactive user is the default option. This means the OPC DA Server will run
using the security context of the Windows user currently logged in to the local com-
puter. If there is no active Windows user logged in, or if the current user identity does-
n't have the launching and activation permissions for the OPC DA Server, a
connection will be unsuccessful.
l The launching user - a connection will not be successful on Windows XP or 2003 if
there is already an instance of the Runtime Manager running under the active Win-
dows session. Similarly, launching the Runtime Manager using a local Windows
login will be unsuccessful if an instance of the Runtime Manager has already been
launched by a DCOM connection.
This scenario will work on Windows Vista and Windows 7. In this case, a local
active Windows login is not required. However, each login session invisibly
spawns multiple instances of the Runtime Manager, the OPC DA Server and the
client if multiple users connect at the same time. This setting is considered a
resource consuming option.
l This user allows you to identify a specific user. A connection will not be successful if
there is already an instance of the Runtime Manager running under the active Win-
dows session. Similarly, launching the Runtime Manager using a local Windows
login will be unsuccessful if an instance of the Runtime Manager has already been
launched by a DCOM connection. However, this option does avoid the situation

1030
Chapter 37: Working with Multiple Monitors

where multiple instances of the Runtime Manager and the OPC DA Server are
launched.
7. Once you have selected an option, you can exit the Properties dialog.
To configure the connectivity environment settings
The way you configure a server's connectivity settings depends on whether it is on a
domain or part of a workgroup. The following points describe how you should set up dif-
ferent client/server combinations.
l If the server is on a domain and the client is on a domain:
On the server computer, add the domain login identity that the client uses to the
OPC DCOM users group you have created.
l If the server is on a domain and the client is part of a workgroup:
Create a matching Windows login identity on the server with the same password
as the Windows login identity on the client machine. Add this Windows login
identity to the OPC DCOM users group you have created.
l If the server is part of a workgroup and the client is on a domain:
Create a matching Windows login identity on the server with the same password
as the domain login identity on the client machine. Add this Windows logon iden-
tity to the OPC DCOM users group you have created.
l If the server is part of the same workgroup as the client:
Create a matching Windows login identity on the server with the same password
as the Windows login identity on the client machine. Add this Windows login
identity to the OPC DCOM users group you have created.

Note: The registry entry for OPC Client application needs to be configured to accept callbacks. An indication
that this is not being done as required, is that all synchronous OPC DA APIs work as expected but data updates
and other asynchronous operation never complete.

Operating the OPC DA Server at Runtime

An OPC DA Server operates as part of the CitectSCADA server management infra-
structure, which means it can be controlled and monitored by the Runtime Manager.
The Runtime Manager will display the operational status and messages for the OPC DA
Server as it does for other CitectSCADA processes. Be aware, however, that you will need
to run the Runtime Manager locally on the OPC DA Server.
You can also configure an OPC DA Server to start in response to a client connection. See
Starting the OPC DA Server on client connection.

1031
Chapter 37: Working with Multiple Monitors

Starting the OPC DA Server on a Client Connection

The OPC DA server can be configured to start when a request is received from a client.
When the parameter [OpcDaServer]AutoStartByClient is enabled, the Runtime Manager
will start the OPC DA server process when a client request is received.
See also
OPC DA Server Properties

OPC Item Browsing

When you create an OPC DA server in CitectSCADA, you can determine if it will present
items to a client application as a hierarchy (representing the clusters and equipment def-
initions used), or as a flat structure.
The ability to use a flat structure allows the server to comply with the item browsing def-
initions supported by version 2.x of the OPC DA standard.
You can set the type of browsing supported by an OPC DA server via the Browsing Hier-
archy field on the OPC DA Server Properties dialog. By default, the browsing hierarchy
will be set to flat.
The browse position will be initially set as the root of the address space. After the initial
call to browse items, the client will be able to continue browsing from the last browse
point.
In the case where a SCADA project is configured with a large number of tags it is rec-
ommended to test browsing of OPC DA items to establish if excessive memory con-
sumption occurs on IOServers or OpcDaServer processes running in the system. In
general you should attempt to browse tags using third party OPC DA Client installed on
the machine where the OPC DA Process is running.

Notes:

1. Data Type filtering is not supported in the browsing function. This is due to the
fact that CitectSCADA data types are not known until tags are subscribed to, if the
user interface and other clients are subscribed at different points in time, clients
could get a different list of tags for the same filter being applied. This is an accepted
relaxation of the OPC Foundation CTT rule.

2. The actual "fully qualified" subscription name for an OPC DA Item might differ to

1032
Chapter 37: Working with Multiple Monitors

the name returned by the OPC DA Browsing APIs, which is in accordance with OPC
DA v2.05 and 3.0 specification. For example, in a multiclustered system "Tag1"
might be defined in several clusters so its "fully qualified" item id might be
"Cluster1.Tag1". Subscription to "Tag1" might still work where there is no ambiguity.
In general it is recommended that OPC DA Clients obtain "fully qualified" ITEM ID
via GetItemID if OPC DA v2.05 is used, or from OPCITEMPROPERTY structure if
OPC DA v3.0 is used.

OPC DA Server Diagnostics

There are two ways you can monitor the performance of your OPC DA server:
l OPC DA Server Logging - you can send messages about an OPC DA server to a trace-
log.dat file
l OPC DA Server Kernel statistics - a Kernel page is available that displays low-level
runtime diagnostics

OPC DA Server Logging

Logging for the OPC DA Server is enabled through the Citect.ini parameter [Debug]Cat-
egoryFilter, which allows you to specify the messages that are sent to the tracelog.dat file.
In the case of an OPC DA server, the tracelog file will use a name based on the fol-
lowing:
tracelog.OpcServer.<OPC server name>.dat
[Debug]CategoryFilter will support the following category definitions:
l OpcDaServerComApi - enables traces on a COM API level. Only return status of each
OPC DA COM API if logged
l OpcDaBrowse205 - enables tracing related to OPC DA v2.05 item browsing
l OpcDaBrowse300 - enables tracing related to OPC DA v3.00 item browsing
l OpcDaServer - enables extensive tracing of OPC DA server object APIs
l OpcDaGroups - enables extensive tracing of OPC DA group object APIs
See also
OPC DA Server Kernel statistics

1033
Chapter 37: Working with Multiple Monitors

OPC DA Server Kernel statistics

A Kernel page is available that displays low-level diagnostic information about the run-
time status of the OPC DA server. It can be accessed from the main kernel window by
typing "Page Table OPCServerConnections".
The information available from this table includes the following:
l OPC Handle - the handle which the OPC server uses to reference a particular OPC
connection. This handle can be cross referenced with log file entries.
l Index - the server object index, which is incremented each time a new client connects.
l #Groups - the number of groups created within the OPC server instance (including
both active and inactive groups).
l #Items - the number of items created within OPC server instances (including all
active/inactive items in all groups).
l #Reads - the number of reads that have been requested for items.
l #Writes - the number of writes that have been request for items.
l #Updates - the number of updates that have been received for subscribed items.
For more information on using the Kernel's Table window, see the topic Page Table in
the Using The Kernel section of the main CitectSCADA help.
See also
OPC DA Server Logging

OPC DA Server reference information

The available reference information for an OPC DA Server includes the following topics:
l OPC DA interfaces
l Client request data type conversions
l OPC DA Server mandatory properties

Supported OPC DA Server Interfaces

The following table indicates which OPC DA interfaces are supported by the Citect-
SCADA OPC DA Server. A highlighted field indicates that the particular OPC API is sup-
ported by the server.

1034
Chapter 37: Working with Multiple Monitors

OPC DA Server
Version 1.0 Version 2.0 Version 3.0
required interfaces

OPC Server

IUnknown Required Required Required

IOPCServer Required Required Required

IOPCCommon N/A Required Required

IConnectionPointContainer N/A Required Required

IOPCItemProperties N/A Required N/A

IOPCBrowse N/A N/A Required

IOPCServerPublicGroups Optional Optional N/A

IOPCBrow- Optional Optional N/A

seServerAddressSpace

IOPCItemIO N/A N/A Required

OPC Group

IUnknown Required Required Required

IOPCItemMgt Required Required Required

IOPCGroupStateMgt Required Required Required

IOPCGroupStateMgt2 N/A N/A Required

IOPCPublicGroupStateMgt Optional Optional N/A

IOPCSyncIO Required Required Required

IOPCSyncIO2 N/A N/A Required

IOPCAsyncIO2 N/A Required Required

IOPCAsyncIO3 N/A N/A Required

IOPCItemDeadbandMgt N/A N/A Required

IOPCItemSamplingMgt N/A N/A Optional

IConnectionPointContainer N/A Required Required

IOPCAsyncIO Required Optional N/A

IDataObject Required Optional N/A

See also
OPC DA Server Reference Information

1035
Chapter 37: Working with Multiple Monitors

Client request data type conversions

The following topics describe the outcome of converting CitectSCADA and OPC data
types during read and write requests by an OPC client.
l OPC client read requests
l OPC client write requests
See also
OPC DA Server Reference Information

OPC client read request conversions

The following table describes the outcomes that can be expected when converting Citect-
SCADA data types to OPC data types during client read requests.

CitectSCADA Data Types (From)

OPC
Data ULON- STRIN-
Types UINT, G, G DIG-
BYTE INT LONG REAL
(To) BCD LONG- (256 ITAL
BCD bytes)

I1 Over- Over- Over- Over- Over- Over- Over- OK

flow flow flow flow flow flow flow
if out of if out of if out of if out of if out of if out of if out of
range range range range range range range

UI1 OK Over- Over- Over- Over- Over- Over- OK

flow flow flow flow flow flow
if out of if out of if out of if out of if out of if out of
range range range range range range

I2 OK OK Over- Over- Over- Over- Over- OK

flow flow flow flow flow
if out of if out of if out of if out of if out of
range range range range range

UI2 OK Over- OK Over- Over- Over- Over- OK

flow flow flow flow flow
if out of if out of if out of if out of if out of
range range range range range

I4 OK OK OK OK Over- Over- Over- OK

flow flow flow
if out of if out of if out of
range range range

UI4 OK Over- OK Over- OK Over- Over- OK

flow flow flow flow
if out of if out of if out of if out of
range range range range

1036
Chapter 37: Working with Multiple Monitors

CitectSCADA Data Types (From)

OPC
Data ULON- STRIN-
Types UINT, G, G DIG-
BYTE INT LONG REAL
(To) BCD LONG- (256 ITAL
BCD bytes)

R4 OK OK OK OK OK OK Over- OK
flow
if out of
range

R8 OK OK OK OK OK OK Over- OK
flow
if out of
range

CY OK OK OK OK OK OK Over- OK
flow
if out of
range

DATE OK OK OK OK OK OK Over- OK
flow
if out of
range

BSTR OK OK OK OK OK OK OK OK

BOOL OK OK OK OK OK OK Over-
flow
OK
if out of
range

Note: For read operations that result in an overflow, OPC E_FAIL will be returned
and read quality will be set to BAD.

See also
OPC client write request conversions
OPC DA Server reference information

OPC client write request conversions

The following table describes the outcomes that can be expected when converting Citect-
SCADA data types to OPC data types during client write requests.

1037
Chapter 37: Working with Multiple Monitors

CitectSCADA Data Types (To)

OPC
Data ULON- STRIN-
Types UINT, G, G DIG-
BYTE INT LONG REAL
(From) BCD LONG- (256 ITAL
BCD bytes)

I1 Over- OK Over- OK Over- OK OK Overflow

flow flow flow if out of
if out of if out of if out of range
range range range

UI1 OK Over- OK OK OK OK OK Overflow

flow if out of
if out of range
range

I2 Over- OK Over- OK Over- OK OK Overflow

flow flow flow if out of
if out of if out of if out of range
range range range

UI2 Over- Over- OK OK OK OK OK Overflow

flow flow if out of
if out of if out of range
range range

I4 Over- Over- Over- OK Over- OK OK Overflow

flow flow flow flow if out of
if out of if out of if out of if out of range
range range range range

UI4 Over- Over- Over- Over- OK OK OK Overflow

flow flow flow flow if out of
if out of if out of if out of if out of range
range range range range

R4 Over- Over- Over- Over- Over- OK OK Overflow

flow flow flow flow flow if out of
if out of if out of if out of if out of if out of range
range range range range range

R8 Over- Over- Over- Over- Over- Over- OK Overflow

flow flow flow flow flow flow if out of
if out of if out of if out of if out of if out of if out of range
range range range range range range

CY Over- Over- Over- Over- Over- OK OK Overflow

flow flow flow flow flow if out of
if out of if out of if out of if out of if out of range
range range range range range

DATE Over- Over- Over- Over- Over- Over- Over- Overflow

flow flow flow flow flow flow flow if out of
if out of if out of if out of if out of if out of if out of if out of range
range range range range range range range

BSTR Over- Over- Over- Over- Over- Over- Over- Overflow

1038
Chapter 37: Working with Multiple Monitors

CitectSCADA Data Types (To)

OPC
Data ULON- STRIN-
Types UINT, G, G DIG-
BYTE INT LONG REAL
(From) BCD LONG- (256 ITAL
BCD bytes)

flow flow flow flow flow flow flow if out of

if out of if out of if out of if out of if out of if out of if out of range
range range range range range range range

BOOL OK OK OK OK OK OK OK OK

Note: For write operations that result in an overflow, OPC E_FAIL will be returned
and the target SCADA value will not be changed.

See also
OPC client read request conversions
OPC DA Server reference information

OPC DA Server mandatory properties

These properties are mandatory and need to be implemented by all OPC DA Servers.

Note: The property IDs 2, 3 and 4 may not provide actual values in some cases.
Refer to the Note column below for more information.

Variant data
Property ID Description Note
type

1 "Item Canonical DataType" (VARTYPE VT_I2 Variant data type

stored in an I2) of the item.

2 "Item Value" (VARIANT) Depends on This value might

DATATYPE not be valid at the
Note the type of value returned is as
time the prop-
indicated by the "Item Canonical Data-
erties were
Type" above and depends on the item.
obtained and it
This will behave like a read from can only be con-
DEVICE. sidered if Property
ID 4 (Quality) is
set to GOOD.

3 "Item Quality" VT_I2 Quality of the

(OPCQUALITY stored in an I2). value.
This will behave like a read from In the majority of
DEVICE. cases it will be set
to BAD_WAITING_
FOR_INITIAL_

1039
Chapter 37: Working with Multiple Monitors

Variant data
Property ID Description Note
type

DATA and in that

case Property ID 2
(Value) should not
be considered as
useful.

4 "Item Timestamp" VT_DATE Timestamp of the

(will be converted from FILETIME). value.
This will behave like a read from If Property ID 2 is
DEVICE. set to BAD_WAIT-
ING_FOR_INI-
TIAL_DATA, this
value might rep-
resent the times-
tamp obtained by
the OPC DA Server
process and that
might be on fixed
offset to the actual
timestamp pro-
vided by the I/O
server.
Actual data pro-
vided by the Read
or OnDataChange
will bring correct
timestamp as
stamped by the
device.

5 "Item Access Rights" VT_I4 Access rights.

(OPCACCESSRIGHTS stored in an I4)

6 "Server Scan Rate" in milliseconds. VT_24

This represents the fastest rate at
which the server could obtain data
from the underlying data source. This
value generally represents the opti-
mum fastest RequestedUpdateRate Scan rate
which could be used if this item were
added to an OPCGroup.
The accuracy of this value can be
greatly affected by system load and
other factors.

See also
OPC DA Server Reference Information

1040
Chapter 37: Working with Multiple Monitors

Using an EcoStruxure Web Service Server

The EcoStruxure Web Service (EWS) Server architecture was developed by Schneider Elec-
tric to enable interoperability between the company's software applications.
In CitectSCADA EWS runs as a server process in runtime manager, using the CtAPI
server interface in the citect process to communicate with the IO Server to get variable
tag data, and set variable tag values. Data is formatted in SOAP envelope and trans-
mitted over HTTPs.

The following topics describe how the EWS server is implemented in CitectSCADA, and
the set of features it supports. The topics include:
l Supported EWS methods
l Configuring the EWS Server
l Operating the EWS at runtime
l Using HTTPS certificates

Note: The information included here is only intended to describe the variation of
EWS implemented in Product. If you would like more comprehensive information
about Schneider Electric's EWS platform, contact Technical Support.

See also
Configuring the EWS Server
Operating the EWS at runtime
Supported Methods

1041
Chapter 37: Working with Multiple Monitors

Configuring an EcoStruxure Web Services Server

Note: It is assumed you have some understanding of SSL. Please refer to http://t-
echnet.microsoft.com/en-us/library/bb727098.aspx for more information on how to
create your own certificate.

To configure the EWS Server complete the following:

1. Create SSL certificate

2. Install SSL Certificate on local machine
3. Complete the EWS properties form
4. Bind the port of the EWS server with an SSL certificate.
5. Register the URL in the Computer Setup Wizard (if you do not want to run as admin-
istrator)

Note: INI parameter [CtAPI]Remote should be set to 1:

• If running CitectSCADA in single process and multi-process mode,
• So the firewall will allow an EWS Server Port through. By default an EWS Server
uses Port 2086.

EcoStruxure Web Services Server Properties

An EcoStruxure Web Services Server Properties has the following properties:

Note: If more than one EWS server is configured for the same computer compilation
will be unsuccessful. The following compilation message will be generated "Multiple
EWS Servers cannot run on the same machine."

Server Name
The name of the server. The name needs to be unique to the project and any included
projects, and not contain spaces. If the name is not unique, compiler error 2082, "A
server with this name already exists" will be returned.
Network addresses

1042
Chapter 37: Working with Multiple Monitors

The network address of the server being configured. Use a configured network address
for EWS Server network address. If the network address is empty, then localhost
(127.0.0.1) will be used; if an invalid network address is provided, compiler error 2084,
"Network address not defined in 'Servers' > 'Network Address' Form" will be returned.
Port
The port this server will listen on. The port number needs to be unique amongst all
SCADA servers that share the same IP address. If the port field is empty, 2086 will be
used. If the port number is not unique, compiler error 2088 "Invalid port number" will be
returned.
Certificate Name
The 'subject' of a valid X.509 certificate that is used for secure transactions between EWS
server and client under Secure Socket Layer protocol. The certificate needs to be installed
on the EWS server manually.
Comment
Any useful comment (optional).
See Also
Configuring the EcoStruxure Web Services Server

EcoStruxure Web Services Server SSL Certificate

To install the certificate:

On the EWS Service Host machine install the certificate to "LocalMachine.My" certificate
Store
In the "Certificate Name" field on the EcoStruxure Web Services Servers form specify the
subject name of the certificate. When the EWS Server is launched, it will search for the
certificate in [\Certificates(Local Computer)\Personal] certificate store. If found, EWS
Service will use the certificate to authenticate a service to a client, and to provide encryp-
tion to the channel.

1043
Chapter 37: Working with Multiple Monitors

Note: EcoStruxure Web Services Servers in CitectSCADA require SSL. If the certificate
is not specified in the configuration, compiler throws error "Certificate must be con-
figured for EWS Server" and compilation fails. If certificate that user specified is not
found in LocalMachine.My certificate store on the host machine, EWS will not be
launched. Details of error will be logged to tracelog.EWSServer.dat under the logs
folder.

See also
Configuring the EcoStruxure Web Services Server

Operating the Ecostruxure Web Services Server at Runtime

The EcoStruxure Web Services Server operates as part of the CitectSCADA server man-
agement infrastructure, which means it can be controlled and monitored by Runtime
Manager. You can start a stopped EcoStruxure Web Services Server, shutdown or restart
a running EcoStruxure Web Services Server from the context menu of the process in Run-
time Manager.
The Runtime Manager displays the operational status and messages for the EcoStruxure
Web Services Server as it does for other CitectSCADA processes; however, you will need
to run the Runtime Manager locally on the EcoStruxure Web Services Server.
See also
EWS Server Properties

EcoStruxure Web Services Server Supported Methods

Listed below are the EWS methods implemented in CitectSCADA, compared against the
full set of methods described in Schneider Electric's EWS specification.

Note: To Invoke EWS Service Methods from EWS client requires certificate and user
credentials authentication. The X.509 certificate used for the EWS server needs to be
trusted by the client. More information on certificate management may be found at
http://msdn.microsoft.com/en-us/library/ms731899(v=vs.100).aspx.

Supported methods

1044
Chapter 37: Working with Multiple Monitors

l GetValues
l GetContainerItems
l SetValues
l GetItems
l GetWebServiceInformation
Unsupported methods
l GetAlarmEvents
l GetUpdatedAlarmEvents
l GetAlarmEventTypes
l AcknowledgeAlarmEvents
l GetHistory

Note: If Allow Anonymous Access is enabled, the SetValues method is not supported
for anonymous users.

See also
Configuring the EcoStruxure Web Services Server

1045
Chapter 37: Working with Multiple Monitors

1046
Chapter 38: Compiling and Running a Project
This section describes how to compile and run a CitectSCADA project, and the func-
tionality available to support these processes.
See Also
Compiling a Project
Running the System
Running Your System Over the Internet
Restarting the System Online
Software Protection

Compiling a Project
The CitectSCADA compiler brings together elements of your project - the configuration
databases, graphics and Cicode files - to create a runtime system.
Compilation checks the project for errors and optimizes your system for fast and efficient
operation. The time necessary to compile a project depends on its size and on the speed
of your computer. Typically, compiling only takes several minutes.
When the CitectSCADA compiler runs, it normally opens files in exclusive mode. In this
mode only CitectSCADA has access to the files (while the compiler is running). This
improves the performance of the compiler, but can also result in an incomplete com-
pilation if two people try to compile different projects at the same time, and these
projects have one or more Include projects in common. The [General] ShareFiles param-
eter tells the compiler to open files in shared mode. This option allows shared network
users to run the compiler at the same time, but it can increase the time necessary for the
compilation.

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.

1047
Chapter 38: Compiling and Running a Project

To compile a project:

1. Select the Project Editor.

2. Click Compile, or choose File | Compile.
The results will be displayed in a dialog when compilation is complete.
The Citect Compiler result dialog reports the number of errors and alerts separately to
avoid confusion. A CitectSCADA project can compile successfully even though the com-
pile may generate alerts; however, compile errors prevent a project from compiling suc-
cessfully.
If there are compile errors, you need to first fix the errors, and then recompile.
CitectSCADA automatically compiles the project (if uncompiled) when you try to run it.
Post Compilation
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. Examples of this would be:
l Launch an application or script to merge the language files that your project is using
into a single file in the root project to aid in localization.
You can also launch an optional command, script or batch file to execute after an unsuc-
cessful compile. Generally this would be used to create a log file to show warnings or
errors generated during a compile. To use either of these functions, add the command
line containing the command or script to either the [CtEdit]CompileSuccessfulCommand
or [CtEdit]CompileUnsuccessfulCommand parameter in the Citect.ini file.
See Also
Incremental compilation
Debugging the compilation
Compile Error Properties
Compile Error Messages
Setting the Project Editor options
Improved Client Side Online Changes

1048
Chapter 38: Compiling and Running a Project

Incremental compilation
You can compile the project incrementally. With incremental compilation, CitectSCADA
only compiles the database records that were added (or changed) since the last com-
pilation. The remainder of the project is not re-compiled.

Note: Some database records are dependent on other database records. If you change
a dependent record, CitectSCADA compiles the entire database.

Before you run a system on a live plant, perform a complete compilation (switch off
Incremental Compile) as the compilation will be more rigorous. Similarly, when you
restore a project from floppy disk, you need to perform a complete compilation the first
time (switch off Incremental Compile).
To switch to Incremental Compile:

1. Select the Project Editor.

2. Choose Tools | Options.
3. Select the Incremental Compile check box, and then click OK.
See Also
Debugging the compilation

Debugging the compilation

If the compiler detects any errors during compilation, the errors are written to an error
file. The compiler will notify you of any errors as it compiles, and you can opt to cancel
the compilation at any stage. If there are multiple or severe errors, the compiler might
automatically cancel. Once the compiler is finished, you can locate each compile error
and display information on it.
The compiler does not verify the operation of your project. Just because your project com-
piles does not mean it will work correctly at runtime. For example, the compiler checks
that the tags you use are defined correctly, and that your Cicode has acceptable syntax.
But, it does not check your tags for incorrect scaling, or that your Cicode has no potential
divide by zero errors.

1049
Chapter 38: Compiling and Running a Project

UNINTENDED EQUIPMENT OPERATION

l Do not attempt to run your system until you have resolved errors reported during
project compilation.
l Always perform a complete compilation before promoting your project to the test or
live environments.
Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

To view compilation errors:

l Select the Project Editor and choose File | Compile Errors.

To get more information on an error:

1. Click Help at the bottom of the Compile Errors dialog box.

2. Read the Help topic associated with the error.
To locate the error (in the project):

l Click Go To at the bottom of the Compile Errors dialog box.

Compile Error Properties

You might encounter errors when you compile your CitectSCADA project. Compile
errors can be viewed in Project Editor using the Compile Errors dialog.
Compiler errors have the following properties:

Property Description

Type The type of error. Three types can occur during compilation. These are:

ERROR - The compilation process continues, however the project will not com-
pile successfully until you have corrected the error.

FATAL - The severity of this error is such that it halts the compilation process.
The project cannot be compiled until you correct the error.

WARNING - The error was not serious enough to stop the project being com-
piled successfully, however investigate and correct the error.

Rec- The number of the database record where the error has occurred.
ord

Name The name of the graphics page, library, or report format file where the error
has been detected.

Field The database field where the error has been detected.

Table The database table where the error has been detected.

Error A brief description of the error.

Con- The location in the database field, report format file, or Cicode library where
text the error has been detected. The context of the error is enclosed in braces {. .
. }.

1051
Chapter 38: Compiling and Running a Project

Compile Error Messages

You might see the alert messages described below during project compilation.

Error Mes-
Description
sage

Address When reading a long or real from the memory of an I/O Device, addresses
on bad need to be on odd or even boundaries. Addresses cannot be mixed. You can
boundary disable checking with the [General]CheckAddressBoundary parameter.

Analog An INT or other analog tag is specified where a DIGITAL tag is expected.
address Check that the tag name is correct, or that a DIGITAL data type is specified
not sup- for the tag.
ported

Array size A tag is indexed but that tag is not declared as an array, or no index has
exceeded been specified when a tag is declared as an array, or the wrong number of
dimensions are specified for an array, or more than four dimensions are
specified for an array.

Bad The format is incorrectly specified for an analog variable. Check the Format
analog for- field in the Variable Tags form.
mat

Bad factor A Cicode expression that contains an invalid expression has been used.
spec- Check the syntax of the expression.
ification

Bad float- A floating-point number cannot be found where one is expected, or the
ing point floating-point value is out of range.
value

Bad I/O The variable tag address is not a valid format for the I/O Device protocol
Device you are using: check the address format. (See the Data Types topic in the
variable Help for each supported I/O Device for a list of appropriate address formats
for that device).

Bad An integer value cannot be found where one is expected, or the integer
integer value is out of range.
value

Bad point The incorrect point limit is specified in the Citect.ini file. The point limit
limit needs to correspond to your CitectSCADA license.

Bad raw An invalid raw data type or a mismatch of data types is specified, for exam-

1052
Chapter 38: Compiling and Running a Project

Error Mes-
Description
sage

data type ple, an attempt was made to convert an integer into a string.

This may be due to a variable address implying a data type that is not com-
patible with the data type specified.

Example 1

Protocol: S7NT or PSDIRECT

Tag Data Type: REAL

Address: DB101,54.3[32]

In this case, the address implies that the variable is an array of 32 DIG-
ITALs (via bit access) but the tag data type is REAL.

Example 2

Protocol: ABMLXEIP

Tag Data Type: INT

Address: T4:0/0

In this case, the address implies that the variable is a DIGITAL (via bit
access) but the tag data type is INT.

Bad An invalid format parameter is specified in a string conversion. Check the

string con- format specification of the variable in the Variable Tags form.
version
param-
eter

Cannot Error message(s) were detected while compiling the function library.
compile
every
function

Cannot The file cannot be opened. The file does not exist, or it has become corrupt,
open file or your system is out of file handles.

Cannot The file cannot be read. The end of file was found, or it has become cor-
read from rupt.
file

Cannot A RETURN statement cannot be used in a function that does not return a
return value. Remove the RETURN statement or declare a return data type for the
value function.
from void

1053
Chapter 38: Compiling and Running a Project

Error Mes-
Description
sage

function

Cannot You cannot declare an array within a function. Arrays can only be declared
use an as library variables, i.e. at the beginning of the library file.
array
inside
function

Cannot A RETURN statement can only be used within a function.

use
RETURN
outside of
functions

Cannot The file cannot accept a write operation. The file has become corrupt or the
write to disk is full.
file

Cicode An array in a Cicode module cannot exceed 60 KB. Reduce the size of the
data limit array.
reached

Close The Cicode statement has a different number of open and close brackets.
bracket Another close bracket ')' or ']' is expected in the statement.
expected

Close com- A comment opened with /* needs to be closed with the */ delimiter. Add
ment the */ delimiter or use a single line comment that starts with an excla-
delimiter mation mark (!) and has no end delimiter.
expected

Close quo- The Cicode statement has a different number of open and close quotation
tation marks. Another close quotation mark (") is expected in the statement.
mark
expected

Database The database does not contain any records.

is empty

Database The main project database cannot be found.

not found

Database The database is full. If the error persists, contact Technical Support for this
table full product.

Disk full The disk is full. Remove unwanted files from the disk, or replace the exist-

1054
Chapter 38: Compiling and Running a Project

Error Mes-
Description
sage

ing disk with a larger disk.

DO A DO statement needs to be used in a WHILE statement.

expected

END An END statement needs to be used at the end of a conditional statement or

expected function definition.

Equipment Indicates that the Item field on the Tag Form (Variable Tags, Trend Tags, and
not specified all Alarm Tags) was specified without an associated Equipment Name.
for tag item.
Please spec-
ify equip-
ment or
remove tag
item

Equipment Indicates the combination of “Equipment.Tag Item” is not unique within the
Name and cluster. Change the name of the Equipment and/or Tag Item.
Tag Item not
This message will also occur if on the same level within the equipment hier-
unique.
archy, the equipment object and the tag item object name are identical.
Specify or
change the
Tag Item
field

Error An include file specified in a database field cannot be found or cannot be

reading opened. Check that the file name is correct, and that the file has been spec-
file ified correctly, i.e. <@FILENAME>.

Expres- An expression is too large for the compiler. Reduce the length of the expres-
sion too sion by splitting the expression into two or more smaller expressions.
big

File The file has been opened by another user. Set the [General] ShareFiles
already parameter to 1 in the Citect.ini file to open files in shared mode.
opened in
SINGLE
mode

File does The file cannot be found. Check that the file name is correct.
not exist

File is An attempt was made to write to a read-only file. Check that the file name is
read only correct or change the attributes of the file.

File A file is in use by another network user.

locked

1055
Chapter 38: Compiling and Running a Project

Error Mes-
Description
sage

File not The database needs to be indexed, but the index file associated with the
indexed database cannot be found. Pack the database.

File size A Cicode functions file, or Report format file, or an include file is too big.
error The maximum file size is 1 MB.

FUNC- A function needs to be declared with the FUNCTION keyword.

TION
expected

GLOBAL You have declared a Global function within your Cicode. Global is not a valid
function function type. Instead, the type Public needs to be used.
is not
allowed,
use PUB-
LIC

Group not A group name was expected. Check that the group name is correct, or that
found the group has been specified correctly in the Groups form.

Include An included project (specified in the Included Projects database) does not
project exist. Check the name of the included project.
not found

Incom- There is a mismatch of data types in a statement. For example, a string is

patible specified where a number is expected.
types
This error can be generated when a variable tag is placed on a graphics
page and the name of the tag is identical to the name of a Cicode function in
the project or an included project.

Incorrect Too many or too few arguments have been passed to a Cicode function.
number
of argu-
ments for
function

Index key The database has a corrupted index. Pack the database.
has
changed

Invalid A non-integer value was found where a TRUE or FALSE value is expected.
BOOLEAN For example, the controlling expression in an IF, WHILE, or FOR statement
value needs to be an integer.

Invalid The font does not exist in the project. Check that the font name is correct,
font name or specify the font with the Fonts form.

1056
Chapter 38: Compiling and Running a Project

Error Mes-
Description
sage

Invalid A group does not exist in the project. Check that the group name is correct,
group def- or specify the group with the Groups form.
inition

Invalid The time is incorrectly specified in the Time, Period or Sample Period field
time for- of a Reports, Events, Trend Tags, SPC Trend Tags, or Devices form.
mat
Time formats needs to be in the format HH:MM:SS and needs to be in the
range of 0:00:00 - 23:59:59. Only the hour is necessary, for example a
value 16 means 16:00 (4:00 PM). Also 24:00:00 is accepted for historical
purposes, and maps directly to 0:00:00.

Period formats needs to be either a valid date or a time in the format

HH:MM:SS with the minutes and seconds in the range of 0 - 59. Only the
seconds are necessary, for example a value of 22 means 22 seconds.

Sample Period formats need to either be a milliseconds value (for example

0.200 for 200 milliseconds) or a time in the format HH:MM:SS with the min-
utes and seconds in the range of 0 - 59. Only the seconds are necessary,
for example a value of 22 means 22 seconds.

Label The syntax of the argument is incorrect, or the incorrect number of argu-
argument ments has been specified, or the number of characters in an argument is
error incorrect.

Label is Label names needs to be unique. Check the Labels form for duplicated
defined names.
twice

Label too The label is too big. The size of a label cannot exceed 8 kb.
big

Maximum The report file size needs to be less than 63 kb. Reduce the size of the
report report or configure two reports.
size
exceeded

MODULE You have declared a Module function within your Cicode. Module is not a
function valid function type. Instead, the type Private needs to be used.
is not
allowed,
use PRI-
VATE

Must If a Cicode function is declared to return a value, it needs to have a RETURN

return statement.
value
from func-

1057
Chapter 38: Compiling and Running a Project

Error Mes-
Description
sage

tion

No I/O No I/O Devices are defined in the project.

Devices
defined

No user A CitectSCADA system is read only until someone logs in. Therefore, before
defined compilation can occur, a user and role needs to be defined to allow someone to
log in. No User has been defined in the configuration for this project. At least
one user needs to be defined.

Not data- The database has become corrupt or the file format is unknown. Pack the
base for- database.
mat

Open You need to use parentheses () in Cicode functions, even when they have
bracket no parameters, for example MyFunction().
expected
This error can be generated when a variable tag is placed on a graphics
page and the name of the tag is identical to the name of a Cicode function in
the project or an included project.

Operand A Cicode operator needs to be followed by an operand.

expected

Out of file CitectSCADA uses a file handle to open each file. When you try to open too
handles many files or databases simultaneously, CitectSCADA can need more file
handles than are available.

You are likely to run out of file handles if you have many included projects.
When CitectSCADA compiles your project, it will open several files in each
include project at the same time, so each extra project you include will
increase the usage of file handles. If you get this alert message when you
have added another include project, you have run out of file handles. To
verify this, remove one of the included projects to see if CitectSCADA can
then compile your project.

With Windows running on a network, the setup of the number of file han-
dles is located in various places. To increase the number of file handles in
DOS, the setup is in the CONFIG.SYS file. If you are using Novell Netware
you need to also increase the file handles in the NET.CFG or SHELL.CFG file.
You need to also increase the number used by CitectSCADA with the [CtE-
dit]DbFiles parameter. Adjust the following settings the associated files:

CONFIG.SYS
FILES=120
NET.CFG or SHELL.CFG
file handles=120

1058
Chapter 38: Compiling and Running a Project

Error Mes-
Description
sage

Out of CitectSCADA has run out of memory. Increase the amount of memory in the
memory computer or use smaller databases.

Page A Page Name needs to start with an alphanumeric character (A - Z, a - z, or

Name can- 0 - 9).
not start
with
under-
score

Point limit The maximum number of points that can be referenced has been reached.
reached The maximum point limit is determined by your CitectSCADA license. Con-
tact Technical Support for this product.

PRIVATE You have declared a Private variable within your Cicode. Private is not a
variable is valid variable type. Instead, the type Module needs to be used.
not
allowed,
use MOD-
ULE

Protocol The protocol field in the I/O Devices database is blank. You need to select a
expected protocol for the I/O Device.

PUBLIC You have declared a Public variable within your Cicode. Public is not a valid
variable is variable type. Instead, the type Global needs to be used.
not
allowed,
use
GLOBAL

Reached The end of the database has been reached or the database has become cor-
the end of rupt. Pack the database. If the error persists, contact Technical Support for
table this product.

Read A mapped variable cannot be written when Remap Write is disabled, and
remap is cannot be read when Remap Read is disabled. Check the Remapping form.
not sup-
ported for
this var-
iable

Semicolon Cicode statements needs to be separated with semi-colons (;).

expected

Software An internal CitectSCADA software error has been detected. Contact Tech-
error nical Support for this product.

1059
Chapter 38: Compiling and Running a Project

Error Mes-
Description
sage

Spec- A system file has become corrupt, or been deleted. Re-install CitectSCADA
ification on your system. If the error persists, contact Technical Support for this
file invalid product.

Statement CitectSCADA is expecting a statement. Check the Cicode for syntax errors.
expected

String Only strings can be used in database fields.

expected

String too The string size has been exceeded. The maximum size of the string not to
big exceed 255 characters.

Super Super Genie syntax (?) can only be used on pages. You cannot use a Super
Genie Genie in a report or Cicode function library. Use the TagRead() and
must be TagWrite() functions instead.
on a page

Symbol A database record does not exist. Check that the record name is correct.
search
failed

Syntax A malformed Cicode expression has been specified. Check the structure of
error the expression.

Tag Tag names need to be unique. Check the Variable Tags form for duplicated
already names.
defined

Tag A tag name was not found where one was expected, or an expression has
expected been passed to a function that expects a tag. Check that the tag name is cor-
rect, or specify the tag with the Variables Tag form.

Tag not The tag does not exist. Check that the tag name (or the equipment.item ref-
found erence) is correct, or specify the tag (with the Variables Tag form). If the
tag does exist in the variables database, the index to the database might be
incorrect. This can occur if you have edited the variables database using
Excel or some other database editor. To re-index the database choose File |
Pack (in the Project Editor).

THEN A THEN statement needs to be used in an IF statement.

expected

Too many Too many arguments are specified in a Cicode function. The maximum
argu- number of arguments allowed is 32.
ments

1060
Chapter 38: Compiling and Running a Project

Error Mes-
Description
sage

Too many More than 4500 user functions have been defined. To increase the number
Cicode of functions allowed (up to 10000), use the CtEdit parameter Max-
functions CicodeFunctions This error is often due to Cicode functions being defined in
a number of included projects. Extending this parameter might affect sys-
tem performance. Only set it when advised by Citect Customer Service.

Too many Too many fields have been specified in the database. This error will only
fields in occur if the Citect.frm file has been changed or become corrupt.contact
database Technical.Support for this product.

Too many The maximum number of .DBF files that can be open simultaneously has
files open been exceeded. Increase the limit by changing the [CtEdit] DbFiles param-
eter.

Too many More than 240 Include projects have been defined.
Include
projects

Too many Too many records have been specified in the database. This error should
records in only occur if the Citect.frm file has been changed or become corrupt. Con-
database tact Technical Support for this product.

Trailing There are extra trailing characters in a Cicode statement, following the
char- semi-colon.
acters in
Cicode

Trailing The database record name contains invalid characters. Remove any invalid
char- characters from the record name.
acters in
Name

The beginning of the database has been reached or the database has
Unexpect- become corrupt. Pack the database. If the error persists, contact Technical
ed begin- Support for this product.
ning of
file

The end of the database has been reached or the database has become cor-
Unexpect- rupt. Pack the database. If the error persists, contact Technical Support for
ed end of this product.
file

Unknown An output file could not be opened during compilation. Pack the database. If
bin error the error persists, contact Technical Support for this product..

Unknown An internal CitectSCADA software error was detected. Contact Technical

1061
Chapter 38: Compiling and Running a Project

Error Mes-
Description
sage

DBA error Support of this product.

Unknown A field is being referenced that does not exist. The database has been mod-
field ified or has become corrupt. Pack the databases. If the error persists, con-
tact Technical Support of this product.

Unknown The include file cannot be found. Check the name of the include file, or that
file the included file is in the correct directory.

Unknown The I/O Device (unit) does not exist in the project. Check that the I/O
I/O Device name is correct.
Device

Unknown The protocol does not exist.

protocol

Distributing the Project

After compiling the project you will need to distribute (deploy) the runtime files to your
live system. A project can be distributed to a computer in various ways:
l Using the archive feature - See Archiving projects
l Using a manual file transfer - pushing the runtime files directly onto your live sys-
tem at the operating system level
l Using automatic file transfer - pulling runtime files from the configuration machine
to the live server using [CtEdit]Run and [CtEdit]Copy
l Using a shared folder on a network drive

Note: Shared folders are not recommended for servers or control computers.

Automatic file transfer

This is where runtime files are pulled down to the runtime system using the [CtEdit]Run
and [CtEdit]Copy parameters.
l [CtEdit]Runpoints to the location of the runtime files. To avoid running a system
over the network and potentially slowing down the system, it is recommended that
this is a local folder under the [user] directory.
l [CtEdit]Copypoints to a copy of the runtime files. This can be a remote shared loca-
tion (for example the [user] folder shared on another computer) or another local
folder. When CitectSCADA detects that the files in the RUN directory have a different

1062
Chapter 38: Compiling and Running a Project

timestamp to those in the COPY directory, the files are copied across to the RUN
directory.
By updating the runtime files in the COPY directory, they will be automatically copied to
the RUN directory whenever they are changed.
Shared Folders
This is where the runtime files are stored in a network shared location, with a backup
server specified in case the main files are not available.
l [CtEdit]Runpoints to the main remote shared location of the runtime files.
l [CtEdit]Backup points to the alternate remote shared location.

Note: Shared folders are not recommended for servers or control computers.

Example of Using Run/Copy to Distribute Project Runtime Files

File Server (PC1)
Consider the example project structure below. The overall system comprises four parts: a
main project which features two separate production line projects, each of which draws
on some common elements from a common project.

1063
Chapter 38: Compiling and Running a Project

Run/Copy can be used to update project files from the File Server (PC1) to the File Client
(PC2). Run/Copy does not support nested project folders, therefore project folders need to
be on the same level as shown below.

The [User] folder (or a parent of the [User] folder) needs to be shared on the network. The
shared folder needs to be accessible for machines to download the project runtime files.
In this example, [User] is shared.
File Client (PC2)
File Client (PC2) will use Run/Copy to get the latest updated projects from the File
Server.
The settings for Run/Copy on the client are:
[ctEdit]Copy = \\PC1\User\Main
[ctEdit]Run = C:\Documents and Settings\All Users\Application Data\Citect\Citec-
tSCADA 7.30\User\Main
The [Run] folder needs to be a child of the [User] folder on the target machine. The fol-
lowing pictures shows the project folders before and after the first project start-up with
Run/Copy.

1064
Chapter 38: Compiling and Running a Project

It can be seen that the project folders are automatically created by the Run/Copy process
if they don't exist. In this example, the basic runtime files are copied to the [Run] folder.
Any other files will be copied over on demand, such as page *.ctg and *.rdb files. After a
successful project start-up, it is also possible for the project to start up when the [Copy]
path is not available (if, for example, the File Server is uncontactable). In this case, only
pages that have been previously viewed (that have been copied over previously on
demand) are available.
If the target machine has the project development environment installed, do not launch
CitectSCADA Explorer after Run/Copy are set up. Doing so will override the [Run] path
setting and you may end up running the wrong project.
See Also
File server redundancy
Using the Web Client

Identifying external files for inclusion in a runtime deployment

If a CitectSCADA project relies on externally-created files that you need to incorporate
into a runtime deployment (such as DBF files, HTML files, or ActiveX objects), you will
need to identify these files in Project Editor using the Custom Files dialog.
When a project is compiled, any files you have identified in this way will be compressed
into one of the following zip files:
l custActiveX.zip - includes the associated ActiveX files
l custFiles.zip - includes other associated files
These zip files are then added to the project's deployment directory, ready for delivery
via a web server or server.
The identification of files for inclusion in custom files was previously limited to Web
Client deployment. However the same functionality is now extended to View-Only and
Control clients. For those client, after the project is compiled, custFiles.zip and cus-
tActiveX.zip are created under the project folder. Each time an operator starts Citect-
SCADA Runtime, the client process checks the project and its included projects
directories. If custFiles.zip or custActiveX.zip is found locally, the compressed archive is
unzipped. (If [CtEdit]Copy is specified, then the zip files may be copied from the copy
path first.)
Files in CustFiles.zip are unpacked to the project directory and its sub directories,
depending on the value of "Destination Location" property specified on the dialog. Acti-
veX control files in CustActiveX.zip are unpacked to the project directory and its sub
directories first, then moved to "C:\Program Files\Common Files\Citect" and, if the file
is a valid Activex control, it is registered.

1065
Chapter 38: Compiling and Running a Project

To include external or user-created files in a runtime deployment:

1. Determine the name and location of any files that you want to deploy with the
project.
These files could include CSV or DBF files associated with tables presented on
project pages, or HTML content. It should also include any required ActiveX
objects.

Note: The following files cannot be included into a Web Deployment as they are
used by the compiler when preparing the zip files:
• Changes.dbf
• Custfiles.dbf
• Errlog.dbf
• Custfiles.zip
• Custactivex.zip
• _library.rdb
• _project.rdb

2. In Project Editor, select Custom Files from the System menu. The Custom Files dialog
will display.
3. Enter the required Custom File Properties for each file you would like to include in a
deployment. The Add button appends a new file entry, or Replace modifies an exist-
ing entry.
4. If you are adding an ActiveX object, you need to specify this by setting the Is ActiveX
field on the extended form properties (accessible via the F2 key).
5. If you need the file to be placed in a particular directory on the destination server fol-
lowing extraction, specify the required location in the Destination location field (acces-
sible via the F2 key).
See Custom File Properties for more information.

Note: If an ActiveX object has an associated data source, verify that the data source
can be located by the computer hosting the client. See the topic Managing associated
data sources under the section on ActiveX objects in the CitectSCADA Help.

See Also
Running the Web Deployment Preparation tool

Custom Files Properties

Custom Files have the following properties:

1066
Chapter 38: Compiling and Running a Project

File Name
The name of a file you would like to incorporate into to a runtime deployment. For exam-
ple, a CSV or DBF file associated with a table presented on a project page, an HTML file,
or a required ActiveX object. You can use wild cards ('*' or '?') when specifying a file
name.
To identify a custom file, you need to precede the file name with:
l an absolute path
l the Windows relative path
l a CitectSCADA directory
A Windows relative path should navigate from the current project directory. A Citect-
SCADA directory path can be one of the following:
l [BIN] – where the CitectSCADA binary files are located
l [Config] – where the CitectSCADA configuration files are located
l [DATA] – where the CitectSCADA data files are located
l [USER] – where databases are located
l [COMMONFILES] – where CitectSCADA common files are located
The Browse button allows you to select a required file with the path included.

Note: The following files cannot be included as Web Client files as they are used by
the compiler when preparing the deployment zip files:
• Changes.dbf
• Custfiles.dbf
• Errlog.dbf
• Custfiles.zip
• Custactivex.zip
• _library.rdb
• _project.rdb

Comment
Any useful comment (optional).

Extended forms fields

The following fields are implemented with extended forms (press F2).
Is ActiveX
This field specifies if a file is an ActiveX object or not, which determines if it should be
included in custActivex.zip or custFiles.zip. If the value you select is False, the file will
be added to custFiles.zip; if you select True it will be added to custActiveX.zip.

1067
Chapter 38: Compiling and Running a Project

If you leave this field blank, any file with the extension ".ocx", will be automatically
added to custActiveX.zip by the compiler. This is because ActiveX objects typically use
this file extension. Similarly, any files that don't have this extension will be auto-
matically added to custFiles.zip
If you select False in this field where an .ocx file has been identified, it will force the .ocx
file to be included in custFiles.zip.
Destination location
This field specifies the folder structure that should be used to host the file when it is
extracted from the one of the delivered zip files. It should represent a directory path in
relation to the location where extraction occurs. For example: \Files\
The base folder for extraction is C:\ProgramData\Schneider Electric\CitectSCADA
7.30\User\Example

See also
Identifying user files for inclusion in a deployment

Running the System

This section of the help describes how to run a CitectSCADA project, the adjustments
that can be made to the runtime system, and the processes you can use to update and
test a system while it is operational.

Note: Before you attempt to run a project, check that the host computer has been
appropriately configured using the Computer Setup Wizard. See Configuring Your
System for more information.

See Also
Startup and runtime configuration
Running servers independently
Server redirection
System tuning
Restarting the System Online
Server Side Online Changes
Client Side Online Changes

1068
Chapter 38: Compiling and Running a Project

Startup and runtime configuration

You can specify a Cicode function to execute automatically when CitectSCADA starts up.
This Cicode gets executed as soon as the Cicode system comes online. use the Computer
Setup Wizard to specify the name of the startup function.
You can also run a report on startup. CitectSCADA searches for a default report called
"Startup" when it starts up. If you have configured a report called "Startup", it is run
automatically. You can change the name of the startup report (or disable it altogether) by
using the Computer Setup Wizard.
You can customize many elements of CitectSCADA's runtime and startup behavior.
Only The Computer Setup Wizard is necessary, but you can also use Parameters for
more control.
To start your runtime system:

l Click Run, or choose File | Run.

To compile and run CitectSCADA online:

l Click Run, or choose File | Run.

Note:CitectSCADA automatically compiles the project (if uncompiled) when you try
to run it.

If your operating system is Windows Vista, CitectSCADA runs a compatibility check at

runtime to see if drivers used by the running project are compatible with your operating
system.
l If an I/O Device uses a driver marked as compatible with Windows Vista, the project
proceeds as normal.
l If an I/O Device uses a driver marked as incompatible with Windows Vista, a dialog
box is displayed asking you to remove the I/O Device from the project configuration
or run the I/O Server on a compatible operating system.
l If an I/O Device uses a driver that hasn't been confirmed as either compatible or
incompatible, a dialog box is displayed asking if you want to proceed with running
the project.

Running servers independently

You can run individual processes in a multi-process system, allowing a particular
server or client to be launched independently. This can be useful for hardware testing
and system analysis.

1069
Chapter 38: Compiling and Running a Project

The Runtime Manager can be launched during the configuration of a project via the
Tools menu in Citect Explorer, Graphics Builder and Project Editor. Launching the Run-
time Manager this way presents it in an idle state, allowing you to start a particular proc-
ess by itself.
Once a process is started (by right-clicking on it and selecting Start), the Runtime Man-
ager's monitoring pane displays the startup log for the selected processes, and launches
Runtime.

Note: Only one instance of Runtime Manager can run on a machine at any time.

For more information on using Runtime Manager, click on its Help button.
See Also
Server Redirection

Server Redirection Using Address Forwarding

CitectSCADA allows you to temporarily transfer the communications of a server to
another computer to assist with hardware maintenance and system analysis.
By including an address forwarding section within a Citect.ini file, you can override a
server's project-configured address, redirecting network traffic to a different address and
port.
For example, if you would like to test a new server before adding it to a project con-
figuration, you could make the necessary address forwarding adjustments within the
citect.ini file of a single client to direct it to the new hardware. The server could be tested
within the context of a system without having to recompile the project.
You need to make the necessary adjustments within the citect.ini file for every computer
that is likely to be impacted by address forwarding.
For example, if you have a computer configured to run two I/O Servers, and you would
like to temporarily redirect one of them, then both server machines and every connecting
client need to have the necessary address forwarding adjustments made to their citect.ini
files, so that the servers are aware of each other.
Address forwarding is implemented using the following syntax within a citect.ini file:

[AddressForwarding]
<ClusterName>.<ServerName>=<ipaddress>:<port>

You can also redirect the Peer Port connection for an I/O Server using the following syn-
tax:

1070
Chapter 38: Compiling and Running a Project

[AddressForwarding]
<ClusterName>.<ServerName>_PeerPort=<ipaddress>:<port>

For Alarm Servers that have alarm properties enabled, you can redirect the alarm prop-
erties connector using the following:
[AddressForwarding]
<ClusterName>.<ServerName>_AlarmProps=<ipaddress>:<port>
Address forwarding is only interpreted and used during startup of Citect Runtime. It is
recommended (but not necessary) that the Computer Setup Wizard is run before running
up a project to confirm your changes.

UNINTENDED EQUIPMENT OPERATION

l Do not use address forwarding as the primary mechanism for specifying

client/server communications. It bypasses the normal configuration checks enforced
by the compiler.
l carefully track any adjustments you make to the citect.ini file, as they needs to be
manually corrected once redirection is no longer necessary.
Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

Note: The CitectSCADA Web Client uses address forwarding to manage com-
munication across corporate firewalls. Any manual adjustments may also impact the
ability to connect a Web Client to a deployment on a Web Server.

Using an Alternative INI File

When CitectSCADA starts up, it reads default values from citect.ini. From version 7.10,
CitectSCADA expects the Citect.ini file to exist in the config folder in the User and Data
directory selected during installation. If the file is not found in this location, it will not
search elsewhere and will instead display an error.
If you need to store your INI file elsewhere, specify the path to it on the command line
when starting citect32.exe and ctexplor.exe. If you are running multiple projects, you can
specify an alternative ini file for each project. The new ini file name needs to be passed
to the CitectSCADA system applications; i.e., to CtExlplor.exe and Citect32.exe as a com-
mand line argument.
To specify an alternative INI file for CitectSCADA :

1071
Chapter 38: Compiling and Running a Project

1. Click the icon that you use to start Citect Explorer or Runtime.
2. Right-click to display the shortcut menu and select Properties.
3. Click the Shortcut tab.
4. Add the name of the INI file to the command line property of the appropriate icon
using the -i option. For example, to start CitectSCADA v 7.30 using the initialization
file my.ini, enter the following line:

C:\Program files\Citect\CitectSCADA 7.30\bin\C:\Program files\Schneider Elec-

tric\PowerSCADA Expert 7.10\bin\citect32.exe -ic:\citect\user\myproj\MY.INI

Note: The Computer Setup Wizard uses the same .ini as specified for Citect Explorer.
You can specify different .ini files for both the Runtime and Explorer programs. How-
ever, if you initiate Runtime from the Explorer, it uses the ini that is specified for the
Explorer.

System tuning
CitectSCADA is designed for optimal performance, so it is not necessary for most users
to tune their system. However, special circumstances might require that you adjust your
system for optimal performance. The Kernel allows you to locate areas that need tuning,
and the tuning itself is usually done through parameters. For example, you can improve
performance of the client by using the [Page]ScanTime and [Alarm]ScanTime parameters.

Cache tuning
Tune the cache large enough so that unnecessary reads are not generated, and small
enough that old data is not returned while keeping the communication channel busy. If
the cache is too large, the communication channel might become idle for a while and so
waste its bandwidth. Also if the cache is too large, a CitectSCADA client might start to
short cycle on reads request, which will generate unnecessary network or internal traffic
load.
Read short cycling occurs when a client requests data from the I/O Server, and the data
is returned from the cache, so it is returned quickly. The client will process the data (dis-
play it on screen) then ask for the same data again. If the I/O Server again returns the
same data from the cache, the client will process the same data again which is redun-
dant and a waste of CPU and the network (to transmit the request and response). When
short cycling starts to occur, the CPU and network loading will rise while the PLC com-
munication traffic will start to fall.

1072
Chapter 38: Compiling and Running a Project

To tune the cache you need to balance the cache time between unnecessary reads and
short cycling. The method described below assumes you know how to use the Citect-
SCADA debugging Kernel.
1. Turn off unit caching, use the CACHE command in the Kernel so you don't have to
re-compile your project.
2. Run one CitectSCADA client only on the network, use the Client in the I/O Server for
the test.
3. Display a typical page to generate normal PLC loading for your system.
4. In the Kernel use the STATS command to reset the CitectSCADA statistics.
5. In the Kernel display the page 'PAGE TABLE STATS'. This page shows the cycle and
execution time of various CitectSCADA tasks, some of which consume PLC data. The
tasks called 'Citect n' where n is a number are the tasks which get data from the PLC
and display on screen. Look at the Avg Cycle time, this is the third column from the
left. Assume that the Avg cycle time is 1200 ms. T his will mean that the current
page is gathering PLC data and displaying its data on the screen in 1200 ms.
6. Always set the cache time below this average cycle time to minimize short cycling.
On average set it to less than half this time, that is 600 ms.
7. Set the cache time to half the cycle time (600 ms). You might not see any improve-
ment in performance with a single client, as caching will only improve performance
with multi clients. You might see improvements if you are also running trends,
alarms or reports which are requesting the same data.
8. Add another CitectSCADA client that is displaying the same data. Reset the STATS
and check the Average cycle time. Each new client will not increase the cycle time, it
will drop slightly. Also look at PAGE GENERAL, to see that each new client services
its reads from the cache; i.e., the % cache reads increases.
9. If the average cycle time drops to less than half the original time then short cycling is
occurring and you need to decrease the cache time until this stops.
Tuning the cache is a trial and error process - as you change it, the read cycle time
will also change. The cache time will also depend on what the current PLC traffic is.
The current traffic is dynamic as CitectSCADA will only read what is needed depend-
ing on the current page, trend, alarm and reports running. Monitor the average cycle
time under lower loading conditions and set the cache as low as necessary to stop or
help prevent short cycling.

1073
Chapter 38: Compiling and Running a Project

Client Side Online Changes

You can now reload a page when the Cicode library has changed.When you attempt to
open a page the system locates the necessary runtime database file on the local disk (or a
server location in the Run/copy setup). If the file timestamp is different to the one in the
memory then it will try to reload the new page file. On page load the system compares
the version of the Cicode library with which the page was created to the one in memory.
If the Cicode library mismatches then a hardware alarm of "Cicode library timestamp
differs" is raised. The page is displayed and any Cicode function that is executed will be
from the memory version of the Cicode library and not the latest compiled version.

Note: It is recommended that the ServerGetProperty Cicode function be used with the
LibRDBMemTime and LibRDBDiskTime properties to check if there is a change to the
Cicode library before attempting a reload. Following a reload please check the cor-
responding server's syslog.dat file for any reload messages. The Cicode changes will
not be reloaded.

A restart of the client is needed to update the Cicode library version to the latest com-
piled version.

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.

See Also
Client Side Online Changes
Compiling the Project
Linking Projects
PageDisplay in the Cicode Reference Guide

1074
Chapter 38: Compiling and Running a Project

PageGoTo in the Cicode Reference Guide

Server Side Online Changes

Previously in CitectSCADA 7.0 the display client supported online changes for graphic
pages and tags, but the servers needed to be restarted if any changes were made to the
configuration. This meant that simple changes such as removing an alarm or trend rec-
ord necessary the large change of restarting the server. With CitectSCADAv7.40, records
can be modified during runtime using the project editor, recompiled and the resulting
database files updated. You can initiate a configuration reload for each server using the
Runtime Manager or using Cicode functions.

UNINTENDED EQUIPMENT OPERATION

Restart the server process if a "Cicode library timestamp differs" error is detected. The
library mismatch is indicated on the server in either the hardware alarm or the server's sys-
log.dat file.

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

Note: A message in the Syslog.dat file and hardware alarm of "Cicode library times-
tamp differs" (error code 454) will be raised if the Cicode library used by one or more
server runtime databases is different from the one in memory. The timestamps will
be different if the project has been fully recompiled (with or without Cicode mod-
ification), or if the project has been incrementally recompiled after any Cicode has
been modified.

The following fields are reloaded on their respective servers:

Alarms
l Digital Alarms
l Time Stamped Alarms
l Analog Alarms

1075
Chapter 38: Compiling and Running a Project

l Advanced Alarms
l Multi-Digital Alarms
l Time Stamped Digital Alarms
l Time Stamped Analog Alarms
l Alarm Categories - The Alarm Category is not reloaded on the client side.
The following Alarm Category fields are used by the server and will be reloaded:
l ON Action
l OFF Action
l ACK Action
l Summary Device
l Log Device, ON, OFF and ACK log devices
The numbers of added, modified and deleted categories are recorded in the system log.
Alarm categories are identified by their category numbers. Two category records with the
same category number are treated as one category in runtime, and the later one would be
loaded.
The number of added categories indicates how many categories with new category
numbers have been added to the alarm server.
The number of modified categories indicates how many categories, of which the category
number existed in the runtime before reloading, have been modified in the alarm server.
If a user has defined a new category record, but its category number was used by an
existing category, the category reload will count this situation as a modification of the
category with this category number, rather than an addition. A category is shown as
modified if any content in the category record is modified, including the case that only
client side settings are modified. In this case, the reload does not change the state of this
category in the memory, but it is still counted as one modified category.
The number of deleted categories indicates how many categories have been deleted from
the alarm server. A category is defined as deleted if none of the other categories has the
same category number as this category. In the case that two category records have the
same category number, deleting the latter one in the table will instead increment the
modify count, while delete the former one would not increment any count.
When [Alarm]EnableErrorLogging is set to 1, an alarm server adds a syslog entry for
errors from adding, modifying or deleting an alarm record or a category record. The
errors can be due to category number out of range or category priority number out of
range. Two new hardware alarms (520 and 523) have been introduced for those errors.
See Cicode and General Errors for more details.
Reloading an alarm server will affect alarm property tags and may make them invalid
(when alarm is deleted) or make them available (when adding alarms).

1076
Chapter 38: Compiling and Running a Project

Refer to the topic Alarm Reload Behavior for more information.

Trends
The following data will be reloaded on a Trend Server when adding, removing and mod-
ifying the records of:
l Trend Tags
l SPC Tags
Modifying a record’s archive properties:
l Sample Period
l Type (from Periodic to non Periodic or vice versa)
l Filename
l Storage Method
l No. Files
l Time
l Period
will put the record in an error state and no acquisition will be done for corresponding
records. A hardware alarm, a syslog entry and a reload error message will be raised. The
history files will not be deleted. For periodic to periodic Type changes, reload will not
generate an error.
If you want to have a valid archive for the modified record, you need to delete the old
history files (after archiving manually) and then trigger the reload again after forcibly
compiling the Trend configuration. This is necessary because the trend system doesn’t
reload the trend rdb file if the compile time of in-memory file is same to the on disk file.
Therefore changes to an existing trend record’s archive properties is a two staged reload.
Due to reload the display clients will need to request the latest configuration data for
trend records. The Process Analyst will periodically refresh configuration data from the
trend server. The Trend server tag browsing is optimized to handle the more frequent
requests.
For legacy trends including SPC, configuration data will be refreshed from the trend
server when a page update is triggered.
Reports
Changes to devices will not be reloaded because the devices may be in use by other
Cicode tasks. The following fields will be reloaded on a Report Server:
l Reports
l Accumulators
See Reference for more information.

1077
Chapter 38: Compiling and Running a Project

See Also
ServerReload in the Cicode Reference Guide

Effects of Server Reload on Servers

The following sections detail the effects on the history of reloaded Alarm, Trend and
Report records. This is dependent on which fields have changed.
A ‘Yes’ in the New Alarm column indicates changes to that field will make a new alarm
and delete the old one and therefore the history is not kept.
A ‘Yes’ in the Invalid History column means changes to that field will make the history
of that record invalid.
Alarm Servers
Common Alarm fields

Field Name New Alarm Invalid History

Alarm Tag Yes No

Cluster Name Yes No

Alarm Description No No

Alarm Category No No

Help No No

Delay No No

Comment No No

Privilege No No

Area No No

Custom 1..8 No No

Paging No No

Paging Group No No

Analog and Time Stamped Analog Alarm fields

Field Name NewAlarm Invalid History

Variable Tag No Yes

High High No Yes

High No Yes

Low Low No Yes

1078
Chapter 38: Compiling and Running a Project

Field Name NewAlarm Invalid History

Low No Yes

SetPoint No Yes

Deviation No Yes

High High Delay No No

High Delay No No

Low Low Delay No No

Low Delay No No

DEviation Delay No No

Rate No Yes

Deadband No Yes

Format No No

Digital and Time Stamped Digital Alarm fields

Field Name New Alarm Invalid History

Variable Tag A No Yes

Variable Tag B No Yes

Time Stamped Alarm fields

Field Name New Alarm Invalid History

Variable Tag No Yes

Timer No Yes

Advanced Alarm fields

Field Name New Alarm Invalid History

Expression No Yes

Multi-Digital Alarm fields

Field Name New Alarm Invalid History

Variable Tag A No Yes

Variable Tag B No Yes

Variable Tag C No Yes

Realarm No Yes

On Function No No

1079
Chapter 38: Compiling and Running a Project

Field Name New Alarm Invalid History

Off Function No No

State No Yes

State Description No No

Trend Servers
Changes to the following properties of trends make existing trend files invalid and result
in the creation of a new trend file (renaming the old one for backup):
l Sample Period
l Type
l Storage Method
l No of Files
l Time (File)
l Period (File)
Changing the scale of a tag will make the trend history invalid.
Effect of reload on a modified Trend:

Field Name New Trend Invalid History

Trend Tag Name Yes No

Cluster Name Yes No

Expression No Yes

Trigger No Yes

Comment No No

Privilege No No

Area No No

Eng Units No No

Format No No

Report Servers
Effect of reload on a modified Report:

Field Name New Reports Invalid History

Report Name Yes No

Cluster Name Yes No

1080
Chapter 38: Compiling and Running a Project

Field Name New Reports Invalid History

Time No Yes

Period No Yes

Trigger No No

Report File Format No No

Output Device No No

Privilege No No

Area No No

Effect of reload on a modified Accumulator:

Field Name New Accumulators Invalid History

Name Yes No

Cluster Name Yes No

Trigger No Yes

Run Time No Yes

No. of Starts No No

Totaliser Inc No No

Totaliser No No

Comment No No

Privilege No No

Area No No

Alarm Reload Behavior

In v7.30 reload occurs on the standby (non-main) server first. The standby server loads
the new RDB and indicates that the server is in “Prepared” state for synchronization.
The database is not updated at this stage.

Note: Reload will not occur if the standby alarm server is not in “prepared” state.

Reload then occurs on the main alarm server, where it compares the RDBs in memory
and then updates the configuration data in the database. The database on the main
alarm server then synchronizes with the database on the standby server.

1081
Chapter 38: Compiling and Running a Project

Use the [Alarm]UseConfigLimits INI parameter to set whether on reload or restart the
alarm property values are retrieved from the RDB or the alarm server side database.
See Also
Server Side Online Changes

Restarting the System Online

With the online restart facility, you can change your project configuration and examine
the results in the runtime system without having to shut down CitectSCADA. You can
update your system while it is running.

Note: If you’ve configured CitectSCADA to use multiprocessor support, it is rec-

ommended that you use the Runtime Manager instead of the restart facility. The run-
time manager allows you to restart different processes individually, whereas the
restart facility will restart every CitectSCADA processe on the machine.

The time taken for the system changeover depends on the size of the project and the
extent of the changes to the project:
l If you only change graphics pages, CitectSCADA does a partial restart (changing only
the pages in the runtime system). Changeover is instantaneous.
l If you change any databases (for example, add a new alarm tag, trend tag, or Cicode
function), CitectSCADA does a full restart to run the updated project.
See Also
Restarting a networked system online

Restarting a networked system online

If you are using CitectSCADA on a network, and would like to restart CitectSCADA with-
out undue impact on the control of the plant, use a structured restart procedure. You can
use any CitectSCADA computer on the network to initiate the online restart.
To phase shutdowns:

1. Set the citect.ini parameter [Shutdown]Phase on each client to either 1 or 2 to identify

the phase of the client.
2. Issue a Shutdown() command from the server.
When the Shutdown() command is issued, clients with phase set to "1" are shut-
down first. When the first phase 1 client has reconnected to the server, clients with
phase set to "2" are shutdown.
CitectSCADA automatically manages the online restart in the following sequence:

1082
Chapter 38: Compiling and Running a Project

1. The Originator issues the Shutdown("Everybody") command.

2. The Alarm Server that the originator is connected to shuts down its first phase
clients.
3. The Alarm Server that the originator is connected to advises the other Alarm Server
then shuts itself down.
4. The second Alarm Server shuts down its first phase clients and waits for the other
Alarm Server to restart (running the new project).
5. When the first Alarm Server is back on line, the second Alarm Server shuts down its
second phase clients and then shuts itself down.
6. The first Alarm Server restarts its first phase clients and shuts down and restarts its
second phase clients.

1083
Chapter 38: Compiling and Running a Project

Note: If you’ve configured CitectSCADA to use multiprocessor support, it is rec-

[Shutdown]Phase, [Shutdown]NetworkIgnore, Shutdown()

Using multiple projects

The most effective method of using the online restart facility is to use two projects. The
first project becomes the current runtime system while the second project is in the devel-
opment stage. You can manage both projects as follows:

Project A is currently the runtime system while Project B is under development.

When Project B is complete , you can use the online restart facility to change the runtime
system to Project B.

You can then copy Project B to Project A for further development.

Note: If you’ve configured CitectSCADA to use multiprocessor support, it is rec-

Initiating the online restart

To initiate the online restart, the originator (any CitectSCADA computer on the network)
issues a shutdown command with the Shutdown function, for example:

1084
Chapter 38: Compiling and Running a Project

Shutdown("Everybody", "MyProject", 2);

Where possible, balance clients across both phases of the shutdown. The [Shutdown]Phase
parameter defines the phase to which each CitectSCADA computer responds.
You can exclude selected computers (for example I/O Servers) from the online restart pro-
cedure with the [Shutdown]NetworkIgnore parameter.
For security, you can prevent selected computers from initiating the online restart pro-
cedure with the [Shutdown]NetworkStart parameter.

Note: If you’ve configured CitectSCADA to use multiprocessor support, it is rec-

Using a Callback function

You can use a callback function (with the OnEvent function) to perform housekeeping
tasks before the system shuts down. You would normally call OnEvent() in the main
startup function (defined with the [Code]Startup parameter). Each time a Shutdown() call
is made, the callback function is run.

/* A user shutdown procedure. */

INT
FUNCTION
MyStartupFunction()
...
OnEvent(25, MyShutdown);
...
END

INT
FUNCTION
MyShutdown()
STRING sPath;
// Perform housekeeping tasks
...
sPath = ProjectCurrentGet();
If sPath = "ProjectA" Then
ProjectSet("ProjectB");
Else
ProjectSet("ProjectA");
END
Shutdown("Everybody", sPath, 2);
END

1085
Chapter 38: Compiling and Running a Project

Running Your System Over the Internet

If you have a computer with Internet access, you can use it to run your project over the
Internet from a remote location. Your computer would then be called an Internet Display
Client. This is basically a runtime-only version of CitectSCADA; you can run your
project from that computer, just as you would from any normal client. However, an Inter-
net Display Client cannot be a server, and it cannot be used to make configuration
changes - you can only run your project.
The Internet Display Client is not supported on Windows Vista. It will still operate cor-
rectly on earlier Operating Systems, however there are no plans to provide support for
IDC on Vista and above in the future.

Note: CitectSCADA also allows you to run your projects in a standard Web browser
across a network of LAN-connected computers. See the CitectSCADA Web Client.

See Also
CitectSCADA Internet Display Client
CitectSCADA Internet server
Startup and runtime configuration
Server - client file updates

The Internet Display Client

The Internet Display Client is a runtime-only version of CitectSCADA. An Internet Dis-
play Client cannot be a server, and it cannot be used to make configuration changes -
you can only run your project.
A computer can have a normal CitectSCADA installation as well as the Internet Display
Client. Before you can run a project over the Internet, you need to switch the [Internet]
Client parameter on.
You can also run multiple instances of the Internet Display Client at the same time. This
allows you to work with more than one project, in runtime-only mode, on the remote
computer.
Notes:
l The Internet Display Client is not supported on Windows Vista. It will still operate
correctly on earlier Operating Systems, however there are no plans to provide support
for IDC on Vista and above in the future.

1086
Chapter 38: Compiling and Running a Project

l If an ActiveX object has an associated data source, you need to verify the data source
can be located by the computer hosting the Internet Display Client. See the topic Man-
aging associated data sources.
l If you want to use the Process Analyst via the IDC, you need to copy the Process
Analyst view (.pav) files to the IDC in order to do so.
See Also
CitectSCADA Internet server

The Internet server

Any I/O Server can be a CitectSCADA Internet Server: you just need to use the Computer
Setup Wizard. (A special protection key is necessary for the Internet Server. Please con-
tact Technical Support for this product for protection key details.)

Note: The Internet Display Client is not supported on Windows Vista. It will still
operate correctly on earlier Operating Systems, however there are no plans to provide
support for IDC on Vista and above in the future.

See Also
Startup and runtime configuration

Startup and runtime configuration

You can customize many elements of CitectSCADA's runtime and startup behavior via
the Computer Setup Wizard.
You can also configure an IDC installation to automatically connect to a CitectSCADA
Internet Server at startup. To do this, you need to adjust the parameters [Internet]
IPAddress, [Internet]Password and [Internet]ShowSetupDlg within the citect.ini file of the
IDC computer.
The citect.ini file is stored in the bin directory of the Internet Display Client installation.

Server - client file updates

When you log on to the CitectSCADA Internet Server, the files needed to run the project
are downloaded to your computer. Because these files needs to be up to date, Citect-
SCADA periodically compares the files on the Internet Server with the downloaded files
on the Internet Display Client. (This period is defined using the [Internet]UpdateTime
parameter.) If a file has been changed since the last update, it is copied to the Internet
Display Client.

To set up your CitectSCADA Internet Server:

1. Run the Computer Setup Wizard and select Custom Setup.

2. Select Server and Control Client from Network Computer section.
3. Once you reach the Internet Server screen, select Internet Server.
4. Enter the TCP/IP address of your Internet server computer (for example 10.5.6.7 or
plant.yourdomain.com). This information is downloaded and stored in the Internet
Display Client's citect.ini file when a connection is made.
5. To determine the TCP/IP address of the Internet server computer:
l For Windows NT4 or 2000, go to the Command Prompt, type IPCONFIG, and
press Enter.
l For Windows 95, select Start | Run, type WINIPCFG, and press Enter.
6. After completing the Computer Setup Wizard, define the passwords necessary by
users of your Internet Display Clients using the [Internet]Manager and/or [Internet]
Display parameters.

7. If the Runtime project on the Internet Server has links to any included projects, the
Internet Display Client can only access the included project files if they are stored on
the same directory level as the Runtime project. For example, if the current project is
located at:
C:\Documents and Settings/All Users/Application Data/Schneider Electric/CitectSCADA
v7.40/User
(Vista and later C:\ProgramData/Schneider Electric/CitectSCADA v7.40/User<current
project>)
then any included projects needs to be located on the same level:

1088
Chapter 38: Compiling and Running a Project

C:\Documents and Settings/All Users/Application Data/Schneider Electric/CitectSCADA

v7.40/User
(Vista and later C:\ProgramData/Schneider Electric/CitectSCADA v7.40/User<included
project>)
8. Any files you want to make accessible to an anonymous FTP user have to be placed
in the Internet Server's\Internet directory, located at C:\Citect\User\Internet by
default. This is where CitectSCADA stores the idc.exe file to allow remote installation
of the Internet Display Client.
TheInternet directory on the Internet Server is only accessible to anonymous FTP users if
it shares the same directory level as the current Runtime project. For example, if you use
CitectSCADA's default settings, the current project folder will be located at:
C:\Documents and Settings/All Users/Application Data/Schneider Electric/CitectSCADA
v7.40/Data
(Vista and later C:\ProgramData/Schneider Electric/CitectSCADA v7.40/Data).

and the Internet directory will be located on the same level at:
C:\Documents and Settings/All Users/Application Data/Schneider Electric/CitectSCADA v7.-
40/Internet
(Vista and later C:\ProgramData/Schneider Electric/CitectSCADA v7.40/Internet).

If the runtime project on the Internet server is stored elsewhere, an appropriately located
Internet directory needs to be created.
To install the Internet Display Client:

1. On the remote computer, start your Internet browser.

2. Type in the FTP address of your CitectSCADA Internet Server (for example, ftp://s-
anctus.citect.com.au/idc.exe).

3. Save the file (IDC.exe) to a temporary folder.

4. Go to this temporary folder and double-click IDC.exe.
5. Follow the prompts to complete the installation.
To run your project over the Internet:

1. Verify that you have installed the Internet Display Client and set up your Internet
server.
2. At the Internet Display Client, double-click the Citect Runtime icon in the Citect-
SCADA IDC program group.
3. In the Citect Internet Client Setup dialog, type the TCP/IP address of your Citect-
SCADA Internet Server (for example 10.5.6.7 or plant.yourdomain.com). You can also
optionally enter a port number separated by a colon ":". If you do not enter a port
number the port number specified in the [Internet]Port parameter in the Citect.ini file
will be used, the default is 21.
4. Type your password

1089
Chapter 38: Compiling and Running a Project

5. Click OK. The relevant data will be downloaded to your computer and your project
will run (if the CitectSCADA Internet Server is running).
To connect to a different CitectSCADA Internet Server once your project is running on the Internet
Display Client:

1. Click Client Setup from the runtime Control menu.

In the Citect Internet Client Setup dialog box, complete the following properties:

Option Description

Addres- Enter the TCP/IP address of the CitectSCADA Internet Server (for example
s 10.5.6.7 or plant.yourdomain.com). You can also optionally enter a port
number separated by a colon ":". If you do not enter a port number the port
number specified in the [Internet]Port parameter in the Citect.ini file will be
used, the default is 21. The address of the last Internet Server used will be
automatically entered here. The addresses of every Internet Server previously
used are retained in the menu (with the most recently used at the top).

Pass- Enter the password supplied to you by the CitectSCADA Internet Server admin-
word istrator. Your password will be encrypted before it is sent across the Internet.

If you enter an incorrect password, the connection attempt will not succeed.

3. Click OK. The relevant data is downloaded to your computer and your project will
run.

Monitoring and Debugging the Runtime System

Debugging CitectSCADA runtime system involves two processes:
l gathering information about Runtime
l analyzing logged data to identify problems
The information gathered from your system will include:
l hardware alarm
l log files
This information can be analyzed directly to identify problems, or you can use the Citect-
SCADA Kernel to perform advanced debugging.
The Kernel can perform low-level diagnostic and debugging operations, and runtime
analysis of your CitectSCADA system. Use it to display low-level data structures, run-
time databases, statistics, debug traces, network traffic, I/O Device traffic and so on.
You can also call built-in Cicode function or user-written Cicode functions.

1090
Chapter 38: Compiling and Running a Project

Note: The process involved in debugging device communications is described in the

'Communicating With I/O Devices' section of the help. See Debugging I/O Devices
and Protocols.

See Also
Gathering Runtime Information
Using the Kernel

Gathering Runtime Information

There are two types of Runtime information you can use to identify and resolve oper-
ational problems:
l hardware alarms
l log files
Hardware alarms are typically displayed on a dedicated alarm page to alert operators to
current problems.
Log files are a record of time-stamped system data that can be analyzed to determine the
cause of a problem.
See Also
Hardware Alarms
Log Files

Hardware alarms
When an error is detected that affects CitectSCADA's operation, a hardware alarm is gen-
erated. Hardware alarms are usually displayed on a dedicated Hardware Alarm page,
available as a standard template.
The hardware alarm page indicates what is happening in your CitectSCADA system. If
loss of communication occurs, if Cicode can't execute, if a graphics page is not updating
correctly, or if a server becomes inoperative, this page shows you. Hardware alarms con-
sist of a unique description and error code.
The hardware alarms do not have detailed information, but serve to point you in the
right direction. For example, if you have a Conflicting Animation alarm, CitectSCADA
will not tell you the cause. You need to observe which page causes the hardware alarm,
and locate the animations yourself.

Note: Do not allow your system to have any recurring hardware alarms.

1091
Chapter 38: Compiling and Running a Project

There are two hardware alarm fields that are not always shown on the hardware alarms
pages. ERRPAGE will display the name of the page that was displayed when the error
was detected. This is useful for finding errors caused by improperly programmed
animations. ERRDESC provides information that is specific to the type of the alarm. For
example, if the alarm is an I/O Device error, ERRDESC shows the name of the device.
See Also
Log files

Log Files
CitectSCADA supports the following log files.

Log file Description

syslog.dat The syslog.dat file is the primary log file for CitectSCADA. It
contains useful system information, from low-level driver traf-
fic and Kernel messages, to user defined messages. Trace
options (except some CTAPI traces) are sent to this file. See
SysLog Format for more information.
CitectSCADA locks syslog.dat while running. However, you
can still view it by using the 'SysLog' command in the Kernel.
There is a single SysLog file per IOServer process for both
the Drivers and the IOServer (in earlier versions of Citect-
SCADA there was 1 file for the IOServer and 1 file for the Driv-
ers).

tracelog.dat The tracelog.dat file contains managed code logging, mainly

in relation to data subscriptions and updates. Field traces
and requests to native drivers go to the syslog.dat or a spe-
cific driver log file.

debug.log This file contains information about a crash or other serious

internal issues. If a crash occurs, it will identify the version
and path of each DLL being used at the time. It can be used to
confirm you have the right version of files.

kernel.dat Kernel.dat contains a copy of the kernel screens. It has the

"dumpkernel(0x8000)" mode added to it on a crash, and is
also available via Cicode calls to "dumpkernel".

ipc.log This log is used for CTAPI communication traffic.

<driver>.dat Driver logs relating to the operation of a particular driver and

are named accordingly. For example, the OPC driver is logged
in 'OPC.dat'.

Params.dat The Params.dat file is an historical record of non default

SCADA parameters. For example, 2010/12/01-14:42:07.847
[Code] Threads= 128 Default= 64.

tracelog.RuntimeManager.dat This file contains logs relating to the operation of the Runtime
Manager.

1092
Chapter 38: Compiling and Running a Project

Log files may have additional suffixes included in their name, for example, an archived
log file will include a timestamp.
If a system uses separate processes, a log file is appended with the component name. An
example of this could be:

syslog.IOServer.Cluster1.dat

Note: If CitectSCADA suffers an unexpected shut down, the Crash Handler will
create a compressed file containing a number of log and data files that may be useful
in determining the cause. See The Crash Handler.

Note: Time-stamps are always in local time.

With the release of CitectSCADA 7.20, log file entries use the following timestamp for-
mat:

yyyy-mm-dd<SPACE>HH:mm:ss.fff<TAB>TZD

where:
yyyy = year (e.g. 2008, 2009)
mm = month (e.g. 01, 05, 12)
dd = date (e.g. 01, 02, 31)
HH = hour of the day (24 hour format)
mm = minute (e.g. 00, 02, 59)
ss = seconds (e.g. 00, 02, 20, 59)
fff = milliseconds (e.g. 000, 123, 999)
TZD = local time offset from the UTC (e.g. +10:00, -09.00)
For example:
2009-06-03 11:19:33.249 +01:00
See Also
Configuring Logging

File locations

1093
Chapter 38: Compiling and Running a Project

The CitectSCADA log files are located in the following directory in versions of Windows
prior to Vista.

C:\Documents and Settings\All Users\Application Data\Citect\CitectSCADA x.xx\Logs

In Windows Vista, the files are located in the Program Data directory:

C:\ProgramData\Citect\CitectSCADA x.xx\Logs

In both cases, driver log files will appear in the Logs directory in a folder named after
the particular driver.
See Also
Configuring Logging

Performing Calculations

If you wish to perform calculations on the time and dates recorded in the log files, this
can be accomplished by opening the files in Microsoft Excel. Open the file in Excel by
selecting settings in the Text Import wizard such that the date and time fields are NOT
split into separate cells. Once opened in Excel, select the column containing the date and
time and format the cells in the column with a custom format of yyyy-mm-dd
hh:mm:ss.000. This will allow Excel to correctly parse the date/time, and store the value
in days, as the number of days (and fractions of a day) since 1900-01-01 00:00:00.000
(this date/time has a value of 1).
Calculations between date/time values can be simply performed. However, it needs to be
remembered that, since Excel treats times as days, if the difference in milliseconds
between two date/times is necessary, the result of the difference calculation needs to be
multiplied by (24*60*60*1000).
Parsing the UTC offset

Using the UTC offset in Excel is a little more complicated, as Excel will not accept neg-
ative times. Therefore format the UTC offset cell/s as a text string, and write a formula to
convert it into a fraction of a day. For example, if the UTC offset is held in cell B4, the for-
mula is:
=LEFT(B4,1)&TIME(MID(B4,2,2),RIGHT(B4,2),0)
This will convert the UTC offset into a correctly signed numerical value expressed as a
fraction of one day.
For example:
l "+09:00" is converted to "+0.375"
l "-04:30" is converted to "-0.1875"
This UTC offset value can be subtracted from the local time to derive the UTC time.
UTC offset could be used with merge logs from two different time zones. In this case you
may wish to make both logs based on UTC time.

1094
Chapter 38: Compiling and Running a Project

e.g. 11:00:00.000 +01:00 is 10:00:00.000 in UTC (minus 1 hour)

09:01:00.000 -01:00 is 10:01:00.000 in UTC (plus 1 hour)
See Also
Configuring Logging

SysLog Format
The SysLog file is a tab-delimited file with each field having a minimum width. This
enables the file to be easily viewed in a text editor or imported into an application such
as Excel. The file has the following format:
l Level – 5 chars
l Category – 11 chars
l Thread Id – 4 byte hex
l Driver Name – 16 chars
l Unit – 16 chars
l Function – 50 chars
l File – 30 chars
l Line – 4 byte decimal
l Message – 1024 chars
See Also
SysLog
Log Files

Tracelog Format

In traces in the PSIClient and CSAToPSI categories, Sent and Received Notations will be
indicated with "<=" and "=>" will be added to indicate tag data flow on the client side.
l "=>" indicates that the log entry is tracing a message that the client has sent to
clusters.
l "<=" indicates that the log entry is trace a message that the client has received from
an IO Server.
In addition, the session name will be appended in the message to identify the IO Server
which handled the tag request.
See Also
Configuring Logging

1095
Chapter 38: Compiling and Running a Project

Configuring Logging
You can make adjustments to the way CitectSCADA logs data using Citect.ini param-
eters. This includes the ability to filter logs according to priority, category or severity.
The available parameters are listed within the Logging Settings page of the Computer
Setup Editor. From here, you can learn how each parameter will impact system logging,
and make adjustments directly into the local Citect.ini file.
The Logging Settings page is accessible from the home page of the Computer Setup
Editor. For more information, see Using the Computer Setup Editor.
Some of the available logging parameters can be updated while your CitectSCADA sys-
tem is running. For more information, see Adjusting logging during runtime.

Note: Logging can cause a strain on system resources. When configuring logging, be
aware of the potential impact on normal operation. For example, a large number of
traces can affect CPU performance, while log file archiving may use up disk space.

Archiving syslog.dat

The syslog.dat file is restricted in size (to 2000 kb by default). When it reaches its size
limit, CitectSCADA renames it syslog.bak, and starts a new syslog.dat.
You can make this size restriction larger or smaller by using the [Debug]SysLogSize
parameter. For example, the following lines in the Citect.ini will set the syslog.dat size
to 30 Mb:

[DEBUG]
SysLogSize=30000

If you want to archive more than one system log file, you can set [Debug]SysLogArchive to
1. This adds a timestamp to the filename.
See Also
Log files
SysLog file

Adjusting Logging During Runtime

You can modify and query logging settings during runtime using the following Cicode
functions:
l SetLogging() - allows you to make changes to the current logging configuration with-
out the need to restart a system that is already running. An optional parameter can

1096
Chapter 38: Compiling and Running a Project

be used to persist the settings to the INI file.

l GetLogging() - allows you to view current logging settings.
The parameters you can modify and query include the following:
l [CtApi]Debug
l [Debug]DriverTrace
l [Debug]SysLogSize
l [Debug]EnableLogging
l [Debug]Priority
l [Debug]CategoryFilterMode
l [Debug]CategoryFilter
l [Debug]SeverityFilterMode
l [Debug]SeverityFilter
l [Debug]LogShutdown
l [Debug]DebugAllTrans
l [IOServer]RedundancyDebug
l [General]Verbose
l [General]VerboseToSysLog
l [Trend]DebugClient
There is also a subset of the logging related INI parameters that can be modified online
within the Citect.ini file, as the system will read their values periodically or on demand.
The parameters you can modify in this way include the following:
l TranDebug <name>
l [PubSub]LogLevel
l [PubSub]LogDevice
l [General]ShowDriverError
l [Debug]SysLogArchive
l [Dial]DebugLevel
l [Trend]TrendDebug
The parameters that support this functionality are identified on the Logging Settings
page of the Computer Setup Editor.
See Also
Log files
The Crash Handler

The Crash Handler

The Crash Handler can be used to help determine the cause of an unexpected program
shut down.

1097
Chapter 38: Compiling and Running a Project

If CitectSCADA suffers an unexpected shut down, the Crash Handler will create a com-
pressed file containing a number of log and data files that may be useful in determining
the cause. These files include:
l syslog.dat
l Citect.ini
l tracelog.dat
l kernel.dat
l debug.log
l user.dmp (see below)
In a multi-process system, these files may use extended names, for example:
syslog.IOServer.Cluster1.dat

You can configure CitectSCADA to save the Crash Handler zip file to the local Logs
directory. If an unexpected shut down occurs, the path to the saved zip file will be
recorded in the syslog.dat. The compressed file can be also emailed to Schneider Electric
(Australia) Pty. Ltd. for analysis, or to a specified email address.
These features are not enabled by default; to enabled and configure the Crash Handler
you need to set the [CrashHandler] parameters

Note: Schneider Electric (Australia) Pty. Ltd. may use the information included in an
unexpected shutdown email to help resolve problems in future releases, but it cannot
reply or follow up a problem with users directly. To discuss these, contact Technical
Support.

Configuring user.dmp

User.dmp is a configurable file that logs exception details. When an unexpected shut
down occurs, it captures objects and their variables in memory in a process referred to
as a "mini-dump". This dump file can be analyzed by Technical Support.
The information included in this process is adjustable via the parameter [Debug]Mini-
DumpType It supports a "light" mini-dump with local stack information for unmanaged
code, through to a "heavy" dump (the default setting) including accessible memory for a
process and thread information. You can also switch the mini-dump off.
To reduce the amount of disk space used by a heavy dump, it is compressed after it is
created (along with other log files) into a file called "Citect32Exception_[timestamp].zip".

1098
Chapter 38: Compiling and Running a Project

To help manage the amount of disk space used by this process, you can adjust the
number of Citect32Exception_[timestamp].zip files that are stored using [Debug]Max-
MiniDumps. You can also raise a hardware alarm to warn when disk space on the
drive where these files are stored falls below a specified minimum amount using
[Debug]LogsDriveMinimumFreeSpace.
See Also
Log Files

Using the Kernel

You use the CitectSCADA kernel to perform low-level diagnostic and debugging oper-
ations, and for runtime analysis of your CitectSCADA system. Use it to display low-level
data structures, runtime databases, statistics, debug traces, network traffic, I/O Device
traffic and so on. You can also call built-in Cicode function or user-written Cicode func-
tions.
The Kernel includes the following areas:
l General - presents statistics and information on the overall performance of Citect-
SCADA. For example, this page shows memory usage, summaries of protocol and I/O
Device statistics, as well as CPU usage. Access this by using the Page General com-
mand.
l Table - displays information about CitectSCADA runtime data structures. This area
is extensive and is initially difficult to navigate. However, Page Table Stats is insight-
ful. Access this by using the Page Table command.
l Driver - displays statistics and information about the individual protocols running
on the I/O Server. Each individual port has its own page of information. Access this
by using the Page Driver command.
l Unit - similar to the driver information, this shows specific statistics and information
about each I/O Device. Access this by using the Page Unit command.

Note: restrict access to the Kernel: anyone using the Kernel has total control of Citect-
SCADA (and subsequently your plant and equipment).

1099
Chapter 38: Compiling and Running a Project

UNINTENDED EQUIPMENT OPERATION

l Do not use the kernel for normal CitectSCADA operation. The kernel is only for diag-
nostics and debugging purposes.
l Configure your security so that only approved personnel can view or use the kernel.
l Do not view or use the kernel unless you are an expert user of CitectSCADA and
Cicode, or are under the direct guidance of Technical Support for this product.
Failure to follow these instructions can result in death, serious injury, or equip-
ment damage.

Access to Cicode and Cache commands

So that there is no unauthorized use of Cicode and Cache commands in the Kernel, only
Kernel users have access to these commands. The Kernel user needs to be defined in the
User database (with the username 'kernel' and a non-blank password) for the Citect-
SCADA project in which they want to access the commands. The Kernel user does not
need to have any areas or privileges defined.
During runtime if the Kernel user attempts to access Cicode or Cache Kernel commands,
the Kernel will ask for the Kernel user password. If the Kernel user is not defined in the
User database for that project (or if the user provides the incorrect password), access to
the Cicode (or Cache) commands is denied.
See Also
Displaying the kernel window
Inside the kernel
Using Kernel Commands
Kernel commands

Displaying the kernel window

You can display the kernel window in several ways. CitectSCADA can open the window
automatically at startup, provide a command option on the Control menu, or you can
define a runtime command to display the Kernel window when necessary.
l Displaying the kernel from the control menu
l Displaying the kernel at startup
l Defining a runtime command
l Closing the kernel window

1100
Chapter 38: Compiling and Running a Project

Displaying the kernel from the control menu

To add a Kernel option to the Control menu of the runtime system, use the Computer
Setup Wizard. Run the wizard, select Custom mode, and select the Kernel on menu
option on the Security Setup | Control Menu page.
You can then display the Kernel window by selecting the Kernel option from the Control
Menu (top-left corner) at runtime. If you do not have a title bar displayed, you can access
the Control Menu by pressing ALT-SPACE (verify that the Alt-Space enabled option is
selected on the Security Setup - Keyboard page).

Note: Clear these options (the default) after commissioning so that there is no acci-
dental or unauthorized use of the Kernel.

Displaying the kernel at startup

To display the Kernel window automatically when CitectSCADA starts up, set the
[Debug]Kernel parameter to 1. The Kernel window is opened at startup and closed at shut-
down. The display is off (0) by default.

Note: Reset this parameter after commissioning so that there is no accidental or

unauthorized use of the Kernel.

Defining a runtime command

To display the Kernel window, define a runtime command that calls the DspKernel()
function, passing 1 in the iMode argument:

Command DspKernel(1);

Comment Displays (opens) the Kernel window

To close the Kernel window, call the DspKernel() function again, passing 0 in the iMode
argument:

Command DspKernel(0);

Comment Closes the Kernel window

Note: put the highest privilege level on the DspKernel command to prevent your

1101
Chapter 38: Compiling and Running a Project

operators from opening the Kernel window.

Closing the kernel window

You can close the Kernel window by choosing Close from the Control menu of the main
Kernel window.
See Also
Inside the kernel

Inside the kernel

When displayed, the CitectSCADA Kernel consists of an application (client) window
called Main and one or more child windows. At startup, the Kernel window displays
information about your CitectSCADA startup processes. The Kernel window also dis-
plays runtime system messages, providing a continuous operational history of your
CitectSCADA system.
The Kernel window contains a command line interface (similar to the Command
prompt) where you can type in Kernel commands to perform a Kernel operation or to
display other child windows.

Note: Access to the Cache and Cicode Kernel commands is password-protected for
security. For details, see Access to Cicode and Cache commands.

By default, CitectSCADA runs in one instance on a single processor. With this con-
figuration, a single Kernel window reports on every processe.
If CitectSCADA runtime is configured to run in multiple instances, each instance has a
separate Kernel window that displays instance-specific system messages; for example,
trend-related system messages appear in the Trend window in the Kernel. You can
switch between Kernel windows by using the Kernel menu on the Kernel window menu
bar.
For a default configuration, the Kernel window displays the following messages:
l Initializing Sub Systems - The primary parts of CitectSCADA are getting started.
l Initializing Font System - Creating fonts that have been defined within CitectSCADA.
These are fonts used for displaying items such as alarms, and pre-V5.0 dynamic text.
l Initializing Client System.
l Starting IO Server - Only visible if the CitectSCADA computer is an I/O Server. If the
computer is an I/O Server and this message does not display, the computer is improp-

1102
Chapter 38: Compiling and Running a Project

erly set up: run the Computer Setup Wizard to check your configuration. IO Server
Started - The server has started and is functioning correctly.

l Initializing I/O Server - Starting to check what is necessary for the I/O Server
to work, and initializing any cards that are necessary.
l On a Client, these messages will be replaced with Calling '<I/O Server>' Con-
nected.
l Initializing Cicode System - Cicode has been loaded into memory, and is prepared to
run.
l Initializing com System - Checking that ports and hardware are responding and
functioning correctly.
l Initializing Request System - The system that handles requests from the Client part
of CitectSCADA to the Server parts of CitectSCADA.
l Initializing Trend Client System - The Trend Client is slightly different than the nor-
mal client, so it needs separate initialization.
l Starting Trends Server - You will only see these messages if the CitectSCADA com-
puter is a Trends Server. If the computer is a Trends Server, and these messages do
not display, most likely the computer is improperly set up. run the Computer Setup
Wizard to check your configuration.
l Trend Startup - CitectSCADA is checking for the trend files, and making new
ones if they can't be found.
l Initializing Trend Acq System - Every trend you define has its own sample
rate. Here CitectSCADA is setting up the system so it can poll the data at the cor-
rect rate for each trend pen.
On a Client, these messages will be replaced with Calling '<Trends Server>' Connected.
l Initializing Alarm System.
l Loading Alarm Databases - You will only see these messages if the CitectSCADA
computer is an alarms server. This is loading alarm data into memory. If the com-
puter is an alarms server, and these messages do not display, most likely the com-
puter is improperly set up. run the Computer Setup Wizard to check your
configuration.
l Open Alarm Save File
Loading Alarm Save File
Alarm Save File Loaded - CitectSCADA gets the alarm save file (that was created in
the specified directory), and examines it in order to see the status of existing alarms.
If you have a redundant alarms server, then this alarms server will interrogate the
other instead of using the alarm save file - since the information on the other server
will be newer than any file.
Starting Alarm Processing- The server is now processing (and serving) alarm data.

1103
Chapter 38: Compiling and Running a Project

On a Client, these messages will be replaced with Calling '<Alarm Server>' Con-
nected.

l Initializing Report System.

l Starting Reports Server - You will only see this message if the CitectSCADA com-
puter is a reports server. If the computer is a reports server, and this message does
not display, most likely the computer is improperly set up. run the Computer Setup
Wizard to check your configuration. On a Client, this message will be replaced with
Calling '<Reports Server>' Connected.
l Initializing Page System - CitectSCADA will now display the Startup Page. At this
time CitectSCADA will cover up the Kernel if it is displayed.
l Initializing Functions - Executing any Cicode functions that have been defined as run-
ning at start up.
The next line of information is the start up time and CitectSCADA version number.
l Channel PORT# is Online
Channel PORT# is Online
Channel PORT# is Online - You will only see these messages if the CitectSCADA
computer is an I/O Server. These are messages telling you that any ports you have
defined in the I/O Server have come online. If you get a messages saying that the port
is not online, or could not be opened, check the configuration of your project. PORT#
is the Port Name specified in the Ports form.
l Unit 'UNIT#' Port PORT# is Online
Unit 'UNIT#' Port PORT# is Online
Unit 'UNIT#' Port PORT# is Online - Only visible if the CitectSCADA computer is an
I/O Server. This indicates that the I/O Device with the Unit Number of UNIT# (as
defined in the I/O Devices form), is connected to port PORT# .
l Communication System Online - CitectSCADA has completed startup operations
and is now fully operational (running).

What to look for

All systems in CitectSCADA start smoothly. When commissioning a system, check the
Kernel. If any element does not initialize properly or reports errors at startup, your Citect-
SCADA system is not working correctly and investigate.
Common causes of startup errors are:
l Incorrect computer setup (usually solved by the Computer Setup Wizard).
l Networking errors or bad hardware.
l Communication errors (usually just a configuration issue).

1104
Chapter 38: Compiling and Running a Project

Use the Main window to check that your I/O Devices come online correctly when start-
ing. First the ports need to initialize, then the I/O Device itself will come online. When a
device does not initialize as expected, CitectSCADA displays a message such as "PLC
not responding", "I/O Device Offline" or similar.
Some I/O Devices might take two attempts to come online. If so, CitectSCADA waits
(usually 30 seconds) and tries again. If the I/O Device does not come online after the sec-
ond attempt, check your configuration (at both ends) and cabling.

Note: The Kernel continues to report changes in the status of I/O Devices to the Main
window. This information might also be reported as alarms to the Hardware Alarms
page.

Using Kernel Commands

Commands are issued at a command line interface (similar to the DOS prompt), usually
from the Main Kernel window. Some commands display their results in the Main Ker-
nel window; others open a child window for information display (or for further com-
mands). You can open a maximum of five windows at once.
You can use several keyboard keys to scan and reuse commands from the command his-
tory, to speed up the issuing of Kernel commands. (The command history is a list of
commands that you have previously issued). These keyboard keys are listed below:

Key Description

Up Scans backward through the command history. (Commands are displayed in

arrow the command line.)

Down Scans forward through the command history. (Commands are displayed in
arrow the command line.)

F3 Puts the last command you issued in the command line.

Left Moves the cursor back one character at a time (in the command line).
arrow

Right Moves the cursor forward one character at a time (in the command line).
arrow

Delete Deletes the character to the right of the cursor (in the command line).

1105
Chapter 38: Compiling and Running a Project

Back- Deletes the character to the left of the cursor (in the command line).
space

Insert Switches from over-strike mode to insert character mode (in the command
line).

Note: When typing a command in the Main window, if a message appears in the
middle of your command, you can still execute the command normally. Use theShell
command to open a new command window.

Cache Changes the cache timeout for each I/O Device.

Cicode Opens a child window that you can use to call Cicode functions.

Cls Clears text from the Main or Cicode windows.

Debug Enables the debugging of raw data transfer between CitectSCADA and a
driver.

DriverTrace Lists the driver control blocks (DCBs) on the I/O Server awaiting delivery
to a driver.

Exit Closes a Cicode or Shell window.

Help Displays a list of some of the commands available in the Kernel.

INI Displays the local citect.ini file

Kernel Deprecated from Version 7.0

Alarm

Kernel Deprecated from Version 7.0

Trend

1106
Chapter 38: Compiling and Running a Project

Kernel Deprecated from Version 7.0

Report

Kernel Deprecated from Version 7.0

IOServer

Kernel Deprecated from Version 7.0

Client

Log Enables or disables the logging of I/O Device reads and writes.

NetBIOS Obsolete in v7.40.

Page Gen- Displays general statistics information.

eral

Page Driver Displays information about each driver in the CitectSCADA system.

Page Mem- Displays the memory debug heap.

ory

Page Net- Obsolete from Version 7.0

stat

Page Table Displays information about CitectSCADA's internal data structures.

Page RDB Displays information about CitectSCADA's Runtime Databases.

Page Unit Displays information about each I/O Device in the CitectSCADA system.

Pause Pause debug output.

Probe Obsolete from Version 7.0

Shell Opens a new command (shell) window.

Stats Resets system statistics.

SysLog Displays the syslog.dat file.

Cache
Changes the cache timeout for each I/O Device with which CitectSCADA is com-
municating.

Syntax

1107
Chapter 38: Compiling and Running a Project

Cache <I/O Device name> <Timeout>

Where:
<I/O Device name>

Any valid I/O Device defined in the project (using the I/O Devices form), or * for I/O Devices.

Timeout in milliseconds, or 0 (zero) to disable timeout.

This command allows you to tune the cache timeout while the I/O Server is com-
municating with the I/O Devices. If you set the timeout to 0 (zero), the cache is disabled.
If you specify a cache timeout for an I/O Device that has the cache disabled, the cache is
enabled.
Any changes made to an I/O Device only apply while the I/O Server is running. If you
restart the I/O Server, the cache timeout reverts to the value configured in the project.
Once you have determined the optimum cache timeout, make the change persistent by
setting the value in the I/O Devices form (for the particular I/O Device).
See Also
Kernel commands
Displaying the kernel window

Cicode
Opens a child window that you can use to call Cicode functions, on either a local or
remote computer. Any built-in or user-written function can be called from this window.
You do not need to specify all the optional arguments, as the optional arguments will be
given runtime defaults (not compiler defaults) as follows:
Data type INT = 0
Data type REAL = 0.0
Data type STRING = ""

Syntax

Cicode [<Name>]
Where:
<Name>

Optionally the name of a Citect Server (for example, Alarms, Reports, Trends) or a client computer
name.

If you enter the Cicode command with no Name argument, a local Cicode window is
created.Cicode commands are executed on the local computer.

1108
Chapter 38: Compiling and Running a Project

In a multi-cluster systems when connecting to a server, the following syntax needs to be

specified:

For example, to connect to the Alarm Server on Cluster1, use:

Cicode Cluster1.Alarm

If you enter a server or computer name as the Name argument, you can create a Cicode
window to the remote server or computer. Cicode commands entered in a remote Cicode
window are executed on the remote computer. For example, to create a Cicode window
where commands execute on the Alarm Server, use:

Cicode Alarm

If you issue the command from a server, you can create a window to the "MyComputer"
computer:

Cicode MyComputer

If the remote computer can be found, its name is displayed in the title of the Cicode win-
dow, otherwise a local window is created.

Note: You can only specify a computer name if you are issuing the command on a
server. This function only supports Client to Server or Server to Client connection.

Each Cicode command is executed with its own Cicode task, so you can start tasks that
take a long time to complete. The Cicode prompt returns immediately after the Cicode
task has started and the task continues to run in the background. If the function is com-
pleted immediately, the return result of the function is displayed. If the function con-
tinues to run, the result is not displayed and cannot be returned - the message "Task still
running" and the task handle is returned instead.

Note: Remember that there is no Privilege check on any command issued from this
window, so you have full access to the system.

The Cicode prompt 0:> shows the current window number with which any object is asso-
ciated. To change the current window, use the WinGoto() function (or any other Cicode
function that affects the current window).
The Cicode window does not recognize any variable names, so when you call a Cicode
function, you can only pass constants (for example numbers or strings). When you call a
function that expects a string, pass a string constant, for example Prompt("Hello from
the Kernel"). If the string is only a single word, you do not have to use delimiters, for
example Prompt(Hello). The Cicode window tries to convert whatever you enter (as argu-

1109
Chapter 38: Compiling and Running a Project

ments) into the correct data type. If it cannot convert the arguments, it passes either 0
(zero) or an empty string to the function.

Note: Some Cicode functions are implemented as label macros by the compiler.
These macros allow backward compatibility when the number of arguments to a
function has been changed. Because the Cicode window does not expand macros,
you cannot call these functions directly. You need to use the macro expansion. If the
function you are trying to use cannot be found, try again by adding an underscore (_)
to the front of the function name, for example _DevClose(1).
You can also shut down the Citect system from this window by using the Shutdown
() function.

See Also
Kernel commands
Displaying the kernel window

Cls
Clears text from the Main or Cicode windows, and moves the cursor to the top left-hand
corner.

Syntax

Cls
Use this command to clear the current window when it has become cluttered (from dis-
playing debug data or too many commands).
See Also
Kernel commands
Displaying the kernel window

Debug
Enables the debugging of raw data that is transferred between Citect and a selected
driver. Protocol traffic is displayed in the Kernel window and logged to the SysLog.DAT
file.

Syntax

Debug<Port> <Mode> [<Display>]

Where:
<Port>

A port name configured in the project (using the Ports form)

<Mode>

1110
Chapter 38: Compiling and Running a Project

The mode:

ALL - Trace low-level communication traffic to the Kernel window.

READ - Trace the low-level communication traffic of read commands to the
Kernel window.
WRITE - Trace the low-level communication traffic of write commands to the
Kernel window.
ERROR - Trace any low-level communication traffic that contains a protocol
error. This mode only generates traces when an error is detected, so you
can leave this option on for long periods of time (to find difficult prob-
lems).
OFF - Stop the debug trace of any type of command.

Note: The TO and FROM modes are now obsolete.

Optionally the display scenario:

MONO - Send the debug to a monochrome monitor (if one is attached) as well
as the Kernel.
MONOONLY - Send the debug to the monochrome monitor only.
To place a port in debug mode, enter DEBUG followed by the port name and the mode
you require. If you do not know the name of the port, enter DEBUG (without any argu-
ments), and Citect displays a list of available ports.
Only the I/O Server communicates with the I/O Devices, so this command is generally
used only on the I/O Server.
When you enable a debug trace mode, Citect displays protocol traffic in the Kernel win-
dow and logs it to the SysLog.DAT file. This tends to reduce Citect's performance (as
there may be a lot of data), and therefore not enable debug trace on an I/O Server that is
important to your current operation. Use this command only during commissioning or
on a non-vital section. Excessive use of this command may cause the I/O Device to go
offline.

UNINTENDED EQUIPMENT OPERATION

Do not enable or use the Debug Trace mode in an operational environment. This mode is
only for use during commissioning.

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

1111
Chapter 38: Compiling and Running a Project

When the debug trace is sent to a Monochrome monitor, it is displayed directly from the
interrupt routine of the driver and therefore at a much faster rate. This trace (if MONO-
ONLY is used) causes less CPU overload of Citect while the trace is active, and provides
instantaneous output. This method is useful if you are developing your own driver and
your driver crashes before the debug trace is displayed in the Kernel.
You can use the Shell command to create an extra command window while the trace is
active. This allows you to enter more commands (in the new window).
You can use the Pause command to stop the debug output (to view the data).
See Also
Kernel commands
Displaying the kernel window

DriverTrace
Lists the commands and information issued to a driver by CitectSCADA. It can be useful
in debugging a driver, for example, it can help determine why a driver is unable to fully
initialize.

Note: Running syslog traces can draw heavily on a CPU usage. monitor the impact
on CPU performance when implementing a large number of traces.

Syntax

Returns the current DriverTrace settings. This can be useful to determine the current mask or port
settings before implementing a new trace. Just key DriverTrace into the Kernel and hit the return key
to view the current settings.

OFF

Turns the DriverTrace off.

CMDS

Turns the DriverTrace on, but does not display the contents of the data buffer.

Note: Specific driver commands need to be enabled with the Kernel command Driv-
erTrace[Mask], or the DriverTraceMask INI parameter.

VER[BOSE]

1112
Chapter 38: Compiling and Running a Project

Turns the DriverTrace on, and displays the contents of the data buffer.

Note: Specific driver commands need to be enabled with the Kernel command Driv-
erTrace[Mask], or the DriverTraceMask INI parameter.

ERR[OR]

Turns the DriverTrace on, but only traces DCBs with errors (DCBs are the internal data structures
used for communication between the I/O server and a driver).

PORT

Allows traces to be limited to a particular driver port, by defining a port name. The default setting,
PORT=*, will trace all ports.

MASK

A 4-byte hexadecimal number that represents a bit mask used to either include or exclude driver
commands from the DriverTrace. The driver commands and their values are as follows:

Command Bit Position

CTDRV_INIT 00000001

CTDRV_OPEN 00000002

CTDRV_INIT_CHANNEL 00000004

CTDRV_INIT_UNIT 00000008

CTDRV_READ 00000010

CTDRV_WRITE 00000020

CTDRV_CONVERT 00000040

CTDRV_CANCEL 00000080

CTDRV_CPU 00000100

CTDRV_DATABASE 00000200

CTDRV_STOP_UNIT 00000400

CTDRV_STOP_CHANNEL 00000800

1113
Chapter 38: Compiling and Running a Project

CTDRV_CLOSE 00001000

CTDRV_FORMAT 00002000

CTDRV_STATS 00004000

CTDRV_DEBUG 00008000

CTDRV_INFO 00010000

CTDRV_STATUS_UNIT 00020000

CTDRV_INIT_CARD 00040000

CTDRV_UPDATE_INFO 00080000

CTDRV_UI_READ 00100000

CTDRV_UI_WRITE 00200000

CTDRV_EXIT 00400000

CTDRV_UNITACTIVATES 01000000

CTDRV_SUBSCRIPTIONS 02000000

CTDRV_EVENTUPDATES 04000000

CTDRV_STATUS_DISCONNECT 40000000

For example, the value you would use to include only the CTDRV_OPEN, CTDRV_INIT_UNIT
and CTDRV_READ commands would be: 0000001A.

Most users will want to exclude the CPU function call, as this happens often. Do this by setting a
mask of 7ffffeff.

The default <mask> is 7FFFFFFF.

DUMP

Lists the driver control blocks (DCBs) on the I/O Server awaiting delivery to a driver and actioning
from the driver.

Examples

-> 07f96fdc Cmd: 03 CTDRV_INIT_UNIT ,MOCKOPC, Port: PORT1, Unit: IODev1

(UR0,N1)
| 07f96fdc UnitType: 0 (0x0), UnitAddr: 0 (0x0), BitWidth: 1, UnitCount: 16

1114
Chapter 38: Compiling and Running a Project

<-07f96fdc Cmd: 03 CTDRV_INIT_UNIT ErrDriver 23 (0x17) and took 0ms

-> 07ff1584 Cmd: 04 CTDRV_READ ,DISKDRV, Port: DISKDRV, Unit: IODevDisk
(UR1,N2)
| 07ff1584 UnitType: 1 (0x1), UnitAddr: 1 (0x1), BitWidth: 16, UnitCount: 5,
RawType: INTEGER
<+07ff1584 Cmd: 04 CTDRV_READ ErrDriver 0 (0x0) and took 0ms
<+07ff1584 UnitType: 1 (0x1), UnitAddr: 1 (0x1), BitWidth: 16, UnitCount: 5,
RawType: INTEGER
<+07ff1584 000: 1 0 0 0 5
~> 00000000 Cmd: 25 CTDRV_SUBSCRIBE ,MOCKOPC, Port: PORT1, Unit: IODev1
(UR0,N1)
>-00000000 SUBSCRIBE Tag=Tag4 UpdateRate=500ms
~< 000003e9 Cmd: 26 CTDRV_EVENTUPDATES,MOCKOPC, Port: PORT1, Unit: IODev1
(UR0,N1)
<-000003e9 DS Event UPDATE_MODE=ALL Tag=Tag4 RawValue=0x00
Timestamp=<time_not_set> RawQual=0x0000 DSError=0 (0x0)

Explanation of arrows used above

-> Flags information going down to the driver
|
<- Flags information back from the driver straight away
<+ Flags information back from the driver asynchronously (i.e. after some
small time delay)
~> Flags subscription based calls into the driver
>-
~< Flags subscription based updated from the driver
<-
(URx,Ny) addition to UNIT and Data driver traces
UR stands for Unit Record number and is 0 based, so a value of 3 would be the 4th
device in the IODevice form. N stands for the (Network) Number in the IODevice form.
The use of this is to distinguish between redundant units which may use the same unit
name. Thus the trace will positively confirm which unit is in use.
See Also
Kernel commands
Displaying the kernel window

Exit
Closes the Cicode or Shell windows.

Syntax

Exit

1115
Chapter 38: Compiling and Running a Project

Note: You cannot use this command to close the Main window. See Closing the ker-
nel window.

To close every other window, select Close from the window's control-menu box, or press
Esc, or double click the control-menu box.
See Also
Kernel commands
Displaying the kernel window

Help
Displays a list of some of the commands that are available in the Kernel.

Syntax

Help
See Also
Kernel commands
Displaying the kernel window

INI
Displays local citect.ini file. (If you are using a Citect Internet Display Client to run a
project over the internet, the .ini file in the bin directory will display). You can use the
Page Up, Page Down, and arrow keys to move through the file, but you cannot edit or
save it.

Syntax

INI

Note: This window is the same that is used to display the syslog.dat file. You can
display either the citect.ini or syslog.dat in this window, but you cannot display both
at the same time.

See Also
Kernel commands
Displaying the kernel window

Log
Enables or disables the logging of I/O DEVICE reads and writes to the syslog.dat file.

Syntax

1116
Chapter 38: Compiling and Running a Project

Log<I/O Device> <Mode>

Where:
<I/O Device>

The name of the I/O Device to log

<Mode>

Either: READ, WRITE, or OFF

See Also
Kernel commands
Displaying the kernel window

Page General
Displays general statistics information on the overall performance of Citect.

Syntax

Page General
General Statistics

Server The server name of this computer or, if it is a client, the name of the primary
Name server this client talks to.

Node The computer name of this computer. You can set this through the Computer
Name Setup Wizard. This is only used if you have Citect in a networking con-
figuration.

Time The (current) time of day and the date.

CPU An indication of the performance of the Computer. This number provides a

Index rough indication of the performance of the computer. On a Compaq 486/25M
it will be 25.

Run- The total time Citect has been running

ning

Stat The time since the Cicode command to reset the statistics was run.
Reset

Mem- The total amount of free memory (including virtual memory).

ory
Total

Mem- The total amount of free physical memory. The physical RAM that is free on the

1117
Chapter 38: Compiling and Running a Project

ory computer (not including virtual memory).

Phys-
ical

Mem- The % of free Windows system resources.

ory
Resour-
ces

Sched- The number of times that the Citect scheduler is looking for a task to execute.
uler A good indication of how fast the computer can respond to an event. This
Cycles number depends on the speed of the computer and the CPU resources that
Citect is using.

This value is completely different depending on whether you are running 32-
bit or 16-bit Citect. This is because Citect can use the 32-bit operating system
to perform process scheduling, an operation that Citect needs to perform
itself in the 16-bit environment.

16-bit: The busier Citect is, the lower the number. Typical values of 10,000 to
50,000; a highly loaded system may drop to below 1000.

32-bit: The busier Citect is, the higher the number. Typical values of 100 to
1000; a highly loaded system may rise above 5000.

CPU The percentage of the total available computer processing power that is being
Usage used on this computer.

As the percentage increases to a high level, the performance of Citect may

level off or become sluggish. If the CPU usage is consistently very high
(greater than 70%), there could be a problem with your system or you may be
overloading the CPU. For best performance, run your system between 0% and
40%.

Tasks The number of tasks per second that the Citect scheduler is executing, to
Per Sec show how busy Citect is. This number will be between 30 and 200 tasks per
second. If the computer is an I/O Server, the task number is higher (because
each protocol uses many tasks).

Lost Citect keeps track of internal errors in its local error buffers. The Lost Errors
Errors counter is incremented when an error is detected and there is no buffer in
which to put the alert message. This number should normally be 0 (zero). If
this field is incrementing, you may have a problem with your system.

I/O Server Statistics

The following statistics are only incremented if the computer is configured as an I/O
Server:

Read The first number is the total number of read requests sent to the I/O Server

1118
Chapter 38: Compiling and Running a Project

Reque- from client Citect computers, including the local Citect client. This number con-
sts tinues to increment from 0 (to billions) depending on how fast clients are
requesting data and how long the server has been running.

The second number is more useful - it records the read requests per second.
This value also depends on how fast the clients are requesting data from the
I/O Server, and should be between 5 and 400 requests per second

Phys- The first number is the total number of physical reads made to the I/O Devices.
ical Because the I/O Server can optimize the number of read requests made to the
Reads I/O Devices, this number is usually smaller than the number of read requests.
This number is similar to the read requests and increments forever.

The second number is the number of physical reads per second (that the I/O
Server is performing). The rate depends on the clients and how fast the server
can communicate to the I/O Devices (typically 5 to 200).

The total number of times a request was made for the same I/O Device address
Blocke- while the I/O Server was already reading that address. The server blocks the
d two requests together as an optimization.
Reads

Digital The total number of digital points that the I/O Server has read from I/O
Reads Devices.

Digital The number of digital reads per second that the I/O Server is processing. This
Reads provides a general indication of performance. It is dependent on the protocol.
per
Sec

Write The first number is the total number of write requests sent to the I/O Server
Reque- from client Citect computers, including the local Citect client. The second
sts number is the write requests per second (that the I/O Server is performing).

The number of requests depends on the rate at which clients are sending write
requests to the I/O Server (typically 0 to 20). If the number of requests con-
tinually exceeds 10, then this may be causing performance to decline (usually
caused by Cicode performing too many writes to the I/O Devices).

Phys- The first number is the total number of physical writes made to the I/O
ical Devices. Because the I/O Server can optimize the number of write requests
Writes made to the I/O Devices, this number is usually smaller than the number of
write requests. The second number is the number of physical writes per sec-
ond (that the I/O Server is performing).

The number of writes depends on the rate at which clients are sending write
requests to the I/O Server (typically 0 to 20). If the number of requests con-
tinually exceeds 10, then this may be causing performance to decline (usually
caused by Cicode performing too many writes to the I/O Devices).

The total number of times a request was made for the same I/O Device address

1119
Chapter 38: Compiling and Running a Project

Blocke- while the I/O Server was already writing that address. The server blocks the
d two requests together as an optimization.
Writes

Reg- The total number of register points that the I/O Server has read from I/O
ister Devices.
Reads

Reg- The number of register reads per second that the I/O Server is processing.
ister This provides a general indication of performance. It is dependent on the pro-
Reads tocol.
per
Sec

Cache The number of read requests serviced from the read cache.
Reads

Cache The percentage of reads serviced from the cache. If the cache read % is large,
Reads (for example greater than 40%), the I/O Device cache timeout could be set too
(%) high. Try reducing the I/O Device cache time to bring the % cache below 40%.

The % of read cache depends on the configuration of your Citect system and
the number of clients connected. If you have many clients looking at the same
I/O Device data, the cache % may be very high, however this does not usually
impact performance. For example, if you have 10 Citect clients viewing the
same page, a cache read of 90% would be acceptable.

Cache The number of times a cache buffer was flushed because a write request was
Flush directed to the same location. When you write to the I/O Device and that
address is in the read cache, Citect flushes the data from the cache. The next
time the data is read, it is reloaded from the I/O Device to reflect the new value.

Cache The number of read-ahead updates made to the cache buffer. When read
RD ahead caching is enabled, the I/O Server will try to read any I/O Device data
Ahead which is coming close to cache 'timeout' time. The I/O Server will only read this
data if the communication channel to the I/O Device is idle - to give higher
priority to other read requests.

Cache The number of active cache buffers allocated. Each block of data that is read
Buff- from the I/O Device requires a cache buffer when stored in the cache. The
ers number of cache buffers active at once depends on the dynamic operation of
the Citect computers and their project configurations (typically 0 to 100).

Cache The number of times the cache needed to allocate additional buffers but no
Short buffers were available. When this happens the server cannot cache the data.
This does not generate errors but it does lower performance. If this field incre-
ments too quickly, increase the available memory.

The time taken by the I/O Server to process read and write requests (i.e. the
Respo- time from when a request arrives at the server to when it is sent back to the

1120
Chapter 38: Compiling and Running a Project

nse client). This time depends on the physical response time of the I/O Device and
Times how long the request had to wait in a queue for other requests to be com-
pleted. This time increases as the server's loading increases, and is a good
indication of the total system response.

The average, minimum, and maximum times are displayed. Typical values
depend on the I/O Device protocol, however Citect should have an average
response of 500 to 2000 ms. Slower protocols or a heavily loaded system may
make the response time higher, but be able to get response times of less than
two seconds even for very large systems.

Points The maximum number of I/O points that can exist in your Citect system. The
combined Static and Dynamic count cannot exceed this number. The point
limit is part of the Citect software protection, and is programmed into your
hardware key.

Max The maximum number of fully functional Citect computers (Full Licenses) that
Full can exist in your Citect system. This number is part of the Citect software pro-
tection, and is programmed into your hardware key.

Cur- The current number of fully functional Citect computers (Full Licenses) that
rent are running in your Citect system.
Full

Peak The peak number of fully functional Citect computers (Full Licenses) that your
Full Citect system has experienced since it was re-started.

Static The number of static I/O points.

Max The maximum number of View-only Clients that can exist in your Citect system.
Mngr This number is part of the Citect software protection, and is programmed into
your hardware key.

Cur- The current number of View-only Clients that are running in your Citect sys-
rent tem.
Mngr

Peak The peak number of View-only Clients that your Citect system has experienced
Mngr since it was re-started.

The number of dynamic I/O points.

Dyna-
mic

Max The maximum number of Display-only Clients that can exist in your Citect sys-
Dsp tem. This number is part of the Citect software protection, and is programmed
into your hardware key.

Cur- The current number of Display-only Clients that are running in your Citect sys-

1121
Chapter 38: Compiling and Running a Project

rent tem.
Dsp

Peak The peak number of Display-only Clients that your Citect system has expe-
Dsp rienced since it was re-started.

See Also
Kernel commands
Displaying the kernel window

Page Driver
Displays information about each driver in the Citect system. This window is only dis-
played if the Citect computer is configured as an I/O Server with physical I/O Devices
attached.

Syntax

Page Driver
Use Page Up and Page Down keys to scan the driver list.
Driver Statistics

Port The name of the physical port the driver is using for communication.
Name

Protocol The name of the protocol.

Title The protocol title and version string. Protocol drivers for Citect Versions 3.xx,
4.xx, and 5.xx, are Version 2.0 type drivers.

Read The first number is the total number of read requests sent to the driver from
Request- every client Citect computer, including the local Citect client.
s
The second number is the read requests per second (that the I/O Server is
performing).

Physical The first number is the total number of physical reads made to the I/O
Reads Devices. Because the I/O Server can optimize the number of read requests
made to the I/O Devices, this number is usually smaller than the number of
read requests.

The second number is the number of physical reads per second (that the I/O
Server is performing).

Blocked The total number of times a request was made for the same I/O Device
Reads address while the driver was already reading or about to read that address.

1122
Chapter 38: Compiling and Running a Project

The driver blocks the two requests together as an optimization.

Digital The total number of digital points that the I/O Server has read from every I/O
Reads Device.

Digital The number of digital reads per second that the I/O Server is processing.
Reads This provides a general indication of performance. It is dependent on the pro-
per Sec tocol.

Write The first number is the total number of write requests sent to the driver from
Request- every client Citect computer, including the local Citect client.
s
The second number is the write requests per second (that the I/O Server is
performing).

Physical The first number is the total number of physical writes made to the I/O
Writes Devices. Because the I/O Server can optimize the number of write requests
made to the I/O Devices, this number is usually smaller than the number of
write requests.

The second number is the number of physical writes per second (that the I/O
Server is performing).

Blocked The total number of times a request was made for the same I/O Device
Writes address while the driver was already writing that address. The driver blocks
the two requests together as an optimization.

Register The number of register reads per second that the I/O Server is processing.
Reads This provides a general indication of performance. It is dependent on the pro-
per Sec tocol.

Cache The number of read requests serviced from the read cache.
Reads

Cache The percentage of reads serviced from the cache. If the cache read % is large
Reads (for example greater than 40%), the I/O Device cache timeout could be set
(%) too high. Try reducing the I/O Device cache time to bring the % cache below
40%.

The % of read cache depends on the configuration of your Citect system and
the number of clients connected. If you have many clients looking at the same
I/O Device data, the cache % may be very high, however this does not cause
a problem. For example, if you have 10 Citect clients viewing the same page,
a cache read of 90% would be acceptable.

Error The total number of errors encountered by the driver.

Count

1123
Chapter 38: Compiling and Running a Project

Short The number of times the server needed a buffer for the driver but none were
buffers available. This can reduce communication performance and result in loss of
requests. Increase available memory if this field increments too quickly (that
is, more than 10 per minute).

Driver The number of low-level driver errors encountered before retries were per-
Errors formed. This field may continue to increment even if no errors are reported
because the driver retries and it may complete the command on the second
attempt. If this field increments quickly (i.e. 10 or more per minute) without
other errors being reported, you may have a low-level error that affects per-
formance.

Out of The number of times the driver requires a buffer but none were available.
Buffers The driver needs to discard the data. If this field increments too quickly,
increase the number of pending commands the driver can process. This field
only increments with client drivers. I/O Device drivers do not require pend-
ing buffers.

Time The number of timeouts encountered by the driver during operations. This
Outs field may continue to increment with no visual errors as the driver retries the
operation. If this field increments excessively, there may be a communication
problem.

Retries The number of retries executed by the driver. If this field is incrementing,
there may be a communication problem.

Max- This is the number of requests that are kept in a buffer waiting to be serviced
imum by the protocol. There is a pre defined default value for this for every pro-
Pending tocol. If a protocol is capable of handling multiple requests or commands at a
Com- time then this number may be high. If the protocol is capable of only handling
mands 1 command at a time then this will probably be 1 or 2.

Block- This is the range that the I/O Driver will use when blocking read or write
ing Size requests together at runtime. The default value for this is typically set after
(Bytes) quite a lot of experimentation. The value is calculated as the optimum range
of data that the I/O Device can respond to, to get the fastest response times
from your I/O Device.

For example, if the Blocking Size is 100 and you have a graphics page that
has Address1 and Address 99 on it, Citect will read both of these addresses
in one request. If you have Address 1 and Address 101 on the page Citect will
issue 2 separate read requests. The block size may not be the maximum
packet size for the protocol, since a particular type of I/O Device may respond
faster to smaller requests of data than larger requests.

There is one important consideration when using this method; many I/O
Devices need to have their Memory tables created by the user. If the user
does not define every memory address in a range, then Citect may try and
read a block of memory from the I/O Device that does not exist (giving a hard-
ware alarm). This is because Citect will ask for the whole range of addresses
between the starting address and the ending address. So, if in our previous

1124
Chapter 38: Compiling and Running a Project

example the I/O Device did not have address 76, it would report back to
Citect that it could not read address 76. The I/O Driver does not know that it
doesn't need this address and will retry the command, and in some cases will
eventually put the I/O Device offline.

Confirm that you always have defined the memory addresses that Citect will
need to read.

Timeout This is the period of time that the I/O Driver will wait before re-requesting
Period data, if no answer comes from the I/O Device.
(ms)

Max- The number of times the I/O Driver will attempt to get data from the I/O
imum Device.
Retries
Combining this with Timeout gives you the total period before Citect will put
an I/O Device offline.

If the Timeout=2000 and Retry=2 then Citect will wait 2 seconds for a
response, then retry, wait 2 seconds, retry, wait 2 seconds, Offline. Total
time between losing communications and deciding it is offline is now 6 sec-
onds. You can modify these parameters, but if you set them too low you will
generate unneeded retries and possibly get I/O Device Offline messages.

Poll This is the time in milliseconds that Citect will check the port for data or write
Time data to the port. If this is 0 then the protocol is operating in Interrupt mode.
(ms)

Trans- This is the time that Citect will hold a packet of data between receiving a
mit response from the last request and sending the new request. This is usually
Delay 0, however some protocols can become saturated and start to misbehave. In
(ms) these cases the default value has been calculated while the protocol was
being tested, and modifying this value to something smaller will cause prob-
lems. However, making it bigger will only have a very slight impact on the
overall response times in your system, but may make the communications
more stable.

Watch- This is the period of time that Citect will wait after deciding an I/O Device is
time offline before trying to re-establish communications. This is typically 30 sec-
(seconds. It can be made smaller but not be made smaller than the period that
onds) Timeout and Retry will be - otherwise you will not be able to re-establish com-
munications with an I/O Device.

The time taken by the driver to process read and write requests (i.e. the time
Respon- taken to process a single read or write operation to the I/O Device). This time
se depends only on the physical response time of the I/O Device, because no
Times queue waiting time is included. This field reflects any tuning of the com-
munication channel (for example increasing the baud rate will reduce the
response time).

The average, minimum and maximum times are displayed.

1125
Chapter 38: Compiling and Running a Project

Channel This field displays the percentage of the total capacity of the hardware chan-
Usage nel that is currently being used. The I/O Server tries to keep the utilization as
high as possible, however if the client Citect computers are requesting data
slower than the channel can supply, the total will be below 100%. It is pos-
sible for the channel usage to rise above 100% as some I/O Device drivers
can process more than one command at the same time (having two or more
commands using the channel at the same time).

Bytes The number of bytes transferred (each second) by the driver. This number
Per Sec- provides a simple performance indication that is useful when tuning the
ond driver.

Special By enabling verbose mode (press V) or by pressing the down arrow, twenty
Var- special variables are displayed. The meaning of these variables is driver-spe-
iables cific.

See Also
Kernel commands
Displaying the kernel window

Page Memory
Displays memory debugging information. This window is designed for use by Citect spe-
cialists, and requires a high degree of expertise to use.

Syntax

Page Memory
See Also
Kernel commands
Displaying the kernel window

Page Queue
Queues are the main data structure used in CitectSCADA, and this allows the various
queues active on the system to be displayed. To view the different queues, press the page
up and page down keys.
On each page, the handle of the queue being viewed, its name, and its length is dis-
played. The number of queues and entries within these depends entirely on the custom
configuration of Citect32 and the individual project.
Queue formats can vary but several common formats exist.
Example
Queue Sleep
Handle 5 Length 49

1126
Chapter 38: Compiling and Running a Project

Name Hnd State Prty Cpu Min Max Avg Count

U Anm.Animate 9 sleep user 0.4 0.000 0.003 0.000 1134

U Tran.Task.Delay 15 sleep user 0.0 0.000 0.000 0.000 2231

U DISKDRV\WatchDog 22 sleep user 0.0 0.000 0.000 0.000 7

U Alarm.Heart 57 sleep user 0.0 0.000 0.000 0.000 1

U Alarm.ServerMoni 69 sleep user 0.0 0.000 0.000 0.000 3

U Report.Heart 72 sleep user 0.0 0.000 0.000 0.000 1

U Alarm.HardRelease 70 sleep user 0.0 0.000 0.000 0.000 3

U Trend.Client 55 sleep user 0.0 0.000 0.000 0.000 95

U Spl.Task 45 sleep user 0.0 0.000 0.000 0.000 96

This is the most common queue type. Column meanings are as follows :
Mode (Name hidden): U for user-space task, and S for system tasks.
Name: The name of the task.
Hnd : The internal handle for the task.
State: The state of the task, it can be one of: Free, Curr, Ready, Sleep, Wait, Susp and
Dodgy.
Prty: The priority of the item in the queue. It can be one of; Low, User and High.
CPU: Shows the percentage of CPU time used by this task.
Min: Minimum response time for the task (from statistics).
Max: Maximum response time for the task (from statistics).
Avg: Average response time.
Count: The number of times this task has been run.
See Also
Kernel commands
Displaying the kernel window

Page RDB
Displays information about each of Citect's runtime databases (RDBs).

Syntax

Page RDB
Use the Page Up and Page Down keys to move between the tables.

1127
Chapter 38: Compiling and Running a Project

The runtime databases contain your compiled project configuration information. There
are two types of RDB; resident and non-resident.
Resident databases are loaded at Citect startup and remain in memory. Examples of res-
ident databases are Alarms, Trends, Reports, and Functions. The names of resident data-
bases start with the underscore character (_).
Non-resident databases are those that are associated with pages. These databases are
loaded (and unloaded) as necessary - when the page is displayed.
Each database is divided into 10 (or so) tables; <name>, TEXT, REQUEST, PIECE, CODE,
SCALE, RUN, WRITE, FUNC, SYMB, and <name>.
See Also
Kernel commands
Displaying the kernel window

Page Table
Contains information about CitectSCADA's runtime data structures. Currently there are
about 50 tables of information, most of which are only relevant in specific cir-
cumstances.

Syntax

Page Table [<Name>]

Where:
<Name>

The name of a specific table to display (optional).

The Table window that appears hosts a number of tables. Use the Page Up and Page
Down keys to navigate through the table list. Use Up Arrow and Down Arrow keys to
scroll the data for the table that is currently displayed.
The table MASTER_TABLE displays a list of every table. The following tables are par-
ticularly useful:
l Page Table Accum.ReloadError
l Page Table Alarm.ReloadError
l Page Table Broadcast
l Page Table Cicode
l Page Table CSAtoPSI.Subs
l Page Table Data.Connection
l Page Table Data.Recordset
l Page Table OPCServerConnections

1128
Chapter 38: Compiling and Running a Project

l Page Table PerformanceCounter

l Page Table Report.ReloadError
l Page Table SQL
l Page Table Stats
l Page Table Tran
l Page Table Trend.ReloadError
l Page Table Users
See Also
Kernel commands
Displaying the kernel window

Page Table Accum.ReloadError

Displays the accumulator records in the runtime system that did not reload properly
with the latest server online change.

Field Description

Name Record name, truncated after 32 characters

Status Showing the nature and the status of the record update in the format of
"[Add | Modify | Delete] ( [succeeded |failed] )"

Time The time when the record was updated.

Error code The error code of the record update.

A positive value indicates that an issue was detected when updating the
record during the latest server online change.

See Also
Page Table

Page Table Alarm.ReloadError

Displays the alarm records in the runtime system that did not reload properly with the
latest server online change.

Field Description

Name Alarm record name, truncated after 32 characters.

Type Alarm type, i.e. Digital, Analog, Advanced, Multi-Digital, Time Stamped,
TS-Digital or TS-Analog.

Status Showing the nature and the status of the record update in the format of
"[Add | Modify | Delete] ( [succeeded |failed] )"

Time The time when the record was updated.

1129
Chapter 38: Compiling and Running a Project

Field Description

Error code The error code of the record update.

A positive value indicates that an issue was detected when updating the
record during the latest server online change.

AcqError The acquisition error code.

A positive value indicates that there is an issue with acquiring the alarm
tag value from I/O Server.

State The current state of the alarm.

See Also
Page Table

Page Table Broadcast

Displays the number of broadcasts on a running instance of a client or server.

Field Description

MsgType The broadcast message type

Broadcasts The number of broadcasts from when the instance started.

BroadcastsLast5Mins The number of broadcasts in the last 5 minutes.

See Also
Page Table

Page Table Cicode

This table contains a list of Cicode tasks currently running. It contains the task name,
handle and running state, as well as some statistics. CPU_Time is the total time that the
task has run for - it is incremented each time the task runs. The CPU is the percentage of
total available CPU that the task is using (fast tasks often have 00 CPU).
See Also
Page Table

Page Table CSAtoPSI.Subs

Displays a list of client tag subscriptions. The Page table CSAtoPSI.Subs contains the fol-
lowing columns:

Field Description

TagName String representing the tag or tag element.

Handle The handle for the subscription.

Value The current value of the tag.

1130
Chapter 38: Compiling and Running a Project

Field Description

Timestamp The timestamp of the last change for the tag.

Quality The quality of the tag value.

ValueChanges The number of value changes the tag has had.

See Also
Page Table

Page Table Data.Connection

This table displays a list of current database connections. The Page table users contains
the following columns:

Field Description

Dbc The handle to the connection

St The connection state

Rn The number of recordsets

Qn The number of executed queries.

Min The min execution time(s).

Avg The average execution time(s).

Max The max execution time(s).

Connect The connection string (shown only in verbose mode)

Select The last executed query (shown only in verbose mode).

See Also
Page Table

Page Table Data.Recordset

This table displays a list of recordsets. The Page table users contains the following col-
umns:

Field Description

Rs The handle to the recordset.

Dbc The handle to the DB connection object.

IsDev "is device" flag.

IsDef "is default" flag.

Col The number of columns.

Row The number of rows.

1131
Chapter 38: Compiling and Running a Project

Field Description

Connect The connection string (shown only in verbose mode).

Select The executed query (shown only in verbose mode).

See Also
Page Table

Page Table OPCServerConnections

Displays information about the OPC DA Server.

Field Description

OPC Handle This is the handle the OPC server uses to reference a particular OPC con-
nection. This handle can be cross referenced with log file entries.

Index This is the server object index, which is

incremented each time a new client con-
nects.

#Groups The number of groups created within the OPC server instance. This
number includes both active and inactive groups.

#Items The number of items creates within the OPC server instances. This
number is the total of all active/inactive items in all groups.

#Reads The number of reads that have been requested for items.

#Writes The number of writes that have been request for items.

#Updates The number of updates that have been received for subscribed items.

See Also
Page Table

Page Table PerformanceCounter

Displays the performance counters that are holding an instance in the current Citect run-
time process.

Field Description

Category The performance counter category name (omitting the “Citect.Platform.”

prefix to save space)

Counter The performance counter name.

Instance The performance counter instance name (omitting the process signature,
i.e. procid: ####).

Value The current value of the performance counter.

The current state of the performance counter, either “Enabled” or “Dis-

State
abled”.

1132
Chapter 38: Compiling and Running a Project

See Also
Page Table

Page Table Report.ReloadError

Displays the report records in the runtime system that did not reload properly with the
latest server online change.

Field Description

Name Record name, truncated after 32 characters

Status Showing the nature and the status of the record update in the format of
"[Add | Modify | Delete] ( [succeeded |failed] )"

Time The time when the record was updated.

Error code The error code of the record update.

A positive value indicates that an issue was detected when updating the
record during the latest server online change.

See Also
Page Table

Page Table SQL

This table shows the following details for each SQL connection:

Field Description

Dbc The handle to the DB connection object.

Stmt The handle to the statement.

Fmt The handle to the format definition.

Connect The connection string.

Select The last executed query.

QryActv Indication that the query is active (set to TRUE between SQLExec and
SQLEnd).

TrnActv Indication that the transaction is active (shown only in verbose mode).

See Also
Page Table

Page Table Stats

This very useful table contains the cycle and execution times of every task that is run-
ning in Citect. The Execution time is the time taken for the entire task to run. The Cycle
time is the time between when a task starts and when it starts again. The CPU is the per-
centage of total available CPU that the task is using (fast tasks often have 00 CPU).

1133
Chapter 38: Compiling and Running a Project

The Citect 0 entry is the display task (graphics page updates) for the main window. That
is, the total time taken for the Client to request data from the I/O Server, the I/O Server to
get the data and send it back to the Client, and the Client to update the display.

Note: Citect 0 corresponds to the display task for the main window. Citect 1 for the
first child window, Citect 2 for the third, and so on.

The CodeX entries correspond to Cicode tasks, where X is the handle of the task. You
can find out which task corresponds to which handle by viewing Cicode table.

Note: There will be a Trend Acq entry for every different trend sampling period you
have defined in your project.

See Also
Page Table

Page Table Tran

This table shows a list of channels of communication between CitectSCADA com-

ponents. A tran exists between exactly two separate components. A client tran initiates a
connection, a server tran waits for a connection. Client and server in this context bears
no relation to the type of component that owns the tran.
There are two modes for viewing the tran table: Standard and Verbose. The Standard
mode shows information for every tran in a tabular format. It can be scrolled using the
up/down arrow keys, the top row indicates the currently selected tran. Extended infor-
mation for the selected tran can be viewed by toggling to Verbose mode by pressing the
"v" key. Once in Verbose mode, the tran to display can be changed using the Page
Up/Page Down keys.
In standard mode the tran table contains the following columns:

Field Description

Name The name and type of communication channel truncated to 20 char-

acters:

l Client
Format: <cluster name><service name>
Examples: Cluster1Alarm, Cluster1Report, Cluster1Trend
l Server
Format: <server name><cluster name>
Examples: AlarmServer1Cluster1, ReportServer1Cluster1, Trend-
Server1Cluster1

1134
Chapter 38: Compiling and Running a Project

Field Description

l Dedicated (Client and Server)

Format: @@<cluster name><server name>
Examples: @@Cluster1.AlarmServer1, @@Cluster1.ReportServer1,
@@Cluster1.TrendServer1
l Platform (Client and Server)
Format: <server name><cluster name>
Examples: AlarmServer1Cluster1, IOServerCluster1

Node Either the node to which the tran is connected, or the status of the con-
nection:

l <call>
The client tran is attempting to connect.
l <listen>
The server tran is waiting to be connected.
l <disabled>
The tran is currently disabled.
l node name
The tran has connected and is online. The value is the name of
the node/computer to which the tran is connected. This could be
the current computer or a different computer depending on the
TCP/ IP configuration of the project.

Type This is either:

l Client - indicates a client tran. This tran actively attempts to con-

nect to a server tran.
l Server - indicates a server tran. This tran passively waits for a
connection attempt from a client tran.
l SerRnd - indicates a server-to-server redundant tran. This is the
connection between the primary and standby servers when a
project is configured for server redundancy.

Mode This is either:

l Local
This tran connects two components which exist in the same proc-
ess. For instance, when CitectSCADA is run in single process
mode, every server component runs in the same process as the
client. In this case, the connections between these components
would be marked as Local.

1135
Chapter 38: Compiling and Running a Project

Field Description

l OutPro (Out of Process)

This tran either has an established connection or is attempting to
establish a connection between two components via TCP/IP. The
components exist in different processes. They may exist on the
same computer or on different computers.
l OutPrD (Out of Process Dedicated)
A dedicated connection exists between the client and each server
process on a single machine when CitectSCADA is run in multi-
process mode. These trans use named pipe connections to verify
that a communication path exists between every CitectSCADA
component running on one computer regardless of the project's
TCP/IP configuration. Dedicated connections do not exist between
different computers.
l Platfo (Platform Tran)
This tran uses the Platform networking module as the transport
layer between components. For version 7.0, it is only used to con-
nect to the I/O Server.
Note: There are client-side Alarm Server platform trans which
will show up in the Tran Table. The server-side Alarm Server
platform trans were not necessary or implemented for version 7.0
so these client-side trans will remain in a state of Connecting.
They can be ignored.
l Remote
This server tran is waiting for a connection attempt via TCP/IP.
Upon connection, this mode changes to OutPro.

Hnd This value represents the handle number in the tran table of the record.

Cnt This value indicates the number of times the tran has established a con-
nection. Specifically it counts the number of times the tran receives the
MSG_OPEN message. This value has no meaning for local trans for which
it remains 0.
If the number is high, it can indicate that your network is dropping and
then re-establishing connections. However, it could also mean that the
server has been running for a long time and many clients have started
and stopped, thereby closing and opening sessions.

Send This value displays the number of messages that have been sent by the
tran.

Rec This value displays the number of messages that have been received by
the tran.

Wait This value represents the number of times the tran had to wait to get a

1136
Chapter 38: Compiling and Running a Project

Field Description

buffer in order to send a message.

Stack This value indicates the protocol number. Historically, this incorporated
the NetBIOS LanA numbers with the TCP/IP protocol stacks. However, Net-
BIOS support was removed for version 7.0 while TCP/IP support was
enhanced to include redundant Network Interface Cards (NIC).
The Stack value displays an index (1-based) which indicates on which
redundant IP address the server tran is listening or connected. Its value
is only used for out-of-process TCP/IP server trans; it has no meaning for
every other tran.

Service This column displays the type of the service used by the tran (regardless
of the tran mode). The valid services are Alarm, IO, Report and Trend.

State This is the current state of the tran. Valid states are Online, Offline, Con-
necting (client trans only), Disconnecting, Listening (server trans only)
and Disabled.

Login The user login name for remote Tran connection.

See Also
Page Table

Page Table Trend.ReloadError

Displays the alarm records in the runtime system that did not reload properly with the
latest server online change.

Field Description

Name Trend record name, truncated after 32 characters.

Type Trend type, i.e. Periodic, Event or Periodic Event.

Status Showing the nature and the status of the record update in the format of
"[Add | Modify | Delete] ( [succeeded |failed] )"

Time The time when the record was updated.

Error code The error code of the record update.

A positive value indicates that an issue was detected when updating the
record during the latest server online change.

AcqError The acquisition error code.

A positive value indicates that there is an issue with acquiring the trend
tag value from I/O Server or reading from trend archive.

Archive The trend archive file name.

See Also
Page Table

Page Table Users

1137
Chapter 38: Compiling and Running a Project

This table displays a list of users currently logged into the system either locally or
remotely.The Page table users contains the following columns:

Field Description

Name The user name for a particular user

Last Login Time at which user last logged in

Last Logout Time at which user last logged out

Num con- Number of references, both internal and external.

nected

Default Indicates whether user is the default user for the Citect process. Only one user
can be a default user.

Logged In Indicates if user is currently logged in.

Indicates if user is the local user of the current process. Only one user can be
Local User
the current processes local user.

See Also
Page Table

Page Unit
Displays information about each I/O Device in the Citect system. This information is dis-
played if the Citect computer is configured as an I/O Server or simply as a client. If the
computer is a client, then every I/O Device for every I/O Server is displayed. If the com-
puter is an I/O Server, then only the I/O Devices for that I/O Server are displayed. You
can display I/O Devices from other I/O Servers by using the Verbose mode (press V to
enable Verbose mode). If the computer is a client, then not every one of the I/O Device
Information is updated (because only the I/O Server has this information).

Syntax

Page Unit
If the Citect computer is a client, the status and error codes are only local to the com-
puter and do not reflect the true status of the I/O Device on the I/O Server. Be aware that
every configured I/O Device is displayed in this window, not just the I/O Devices for the
particular I/O Server. (Any remote I/O Devices do not reflect the true status of the I/O
Device).
Use the Page Up and Page Down keys to scan the I/O Device list.
I/O Device Information

I/O The name of the I/O Device defined in the project (with the I/O Devices
Device form).

1138
Chapter 38: Compiling and Running a Project

I/O The name of the I/O Server that is servicing this I/O Device.
Server

Com- A description of the I/O Device defined in the project (with the I/O Devices
ment form).

I/O The I/O Device number defined in the project (with the I/O Devices form).
Device
No

PLC The physical I/O Device address defined in the project (with the I/O Devices
Number form).

Port The communication port to which the I/O Device is connected.

Name

Protocol The protocol used for communication with the I/O Device.

Server The status of the I/O Device. The Server Status is only valid if the computer is
Status an I/O Server and it is servicing this I/O Device. The Client Status field is
and valid for Clients only, and indicates the status of the I/O Device that is
Client attached to the I/O Server. The I/O Device status can be one of the following:
Status
RUNNING - Indicates that the communication link with the I/O Device is good.

STANDBY - Indicates that the communication link with the I/O Device is good,
but communication with that I/O Device is currently being performed by
another port. This port is in standby mode.

STARTING - Indicates that the server is currently establishing a com-

munication link (with the I/O Device).

STOPPING - Indicates that the server is currently relinquishing control of the

communication link (with the I/O Device).

OFFLINE - Indicates that the server cannot establish a communication chan-

nel with the I/O Device. If a standby port or server is available, Citect tries to
communicate to the I/O Device using that port.

REMOTE - Indicates that the status of the I/O Device is OK, but it is not cur-
rently connected.

Primary Indicates if the I/O Device is in primary mode; Yes = Primary, No = Standby.
If the I/O Device is in primary mode, the server starts a communication chan-
nel with the I/O Device as soon as the server is activated. If an I/O Device is
in standby mode, the I/O Device remains inactive when the server starts
(until a primary I/O Device becomes inoperative).

Client The name of the I/O Server that this client is using. This allows you to identify
Using the primary and standby I/O Servers.

1139
Chapter 38: Compiling and Running a Project

Generic The last generic error code returned by the driver. Because most protocol
Error drivers have their own special errors, they cannot be recognized by the I/O
Server. The drivers convert their special errors into generic errors that can
be identified by the server.

Error The error handle that is assigned by the I/O Server to each error. This handle
Handle is not used by Citect (at this time).

Driver The driver-specific error code. Each driver has its own special error codes.
Error Refer to the driver specific errors (for the particular protocol) for an expla-
nation of each of the error codes.

Error The alert message associated with the generic error code.
Mes-
sage

Error The total number of errors from the I/O Device.

Count

Restarts The number of times the server has tried to establish a connection with the
I/O Device. This number is normally 1, because the server establishes a con-
nection at startup. If this field displays a number greater than 1, there is a
problem with the communication channel.

The time taken by the driver to process read and write requests (i.e. the time
Respon- taken to process a single read or write operation to the I/O Device). This time
se depends only on the physical response time of the I/O Device, because no
Times queue waiting time is included. This field reflects any tuning of the com-
munication channel (for example doubling the baud rate will half the
response time). The average, minimum, and maximum times are displayed.

Note: One I/O Device with a slow response can slow down your entire sys-
tem. For example, if you have an I/O Device with a response of 2000 ms, any
pages in your system that use data from that device, will have a minimum
update time of 2000 ms.

Cached This field indicates if the I/O Device data is cached.

Cache If the I/O Device is cached, this field displays the cache timeout value. Data is
Timeout held in the cache for this timeout period before being discarded and re-read
from the I/O Device. Only read data is cached.

Block- The current blocking constant value for this I/O Device, as specified in the
ing Con- protocol.
stant

Dial-up The status and history of the dial-up connection.

Con-
nection SUCCESS - The number of successful dial-up attempts.

1140
Chapter 38: Compiling and Running a Project

FAIL - The number of unsuccessful dial-up attempts.

TOTAL - The total number of dial-up attempts.

NEXT - The time of the next scheduled dial-up attempt.

See Also
Kernel commands
Displaying the kernel window

Pause
Pauses debug output in the Kernel window.

Syntax

Pause
See Also
Kernel commands
Displaying the kernel window

Shell
Opens a new command (shell) window.

Syntax

Shell
You can use shell windows in a similar manner to a Main window. Shell windows are
useful for displaying debugging information, or entering commands when the Main win-
dow is displaying debug trace data. You can close the shell windows by selecting Close
from the window's system icon or with the Exit command.
See Also
Kernel commands
Displaying the kernel window

Stats
Resets system statistics (used in the page general, page drivers, page table (stats), and
page I/O Device windows) to 0 (zero).

Syntax

Stats

1141
Chapter 38: Compiling and Running a Project

This command allows you to reset the statistics after Citect has been running for a long
time, and therefore provides an indication of the statistics now (instead of an average
over the total time that Citect has been running).

Note: Some I/O Server statistics are automatically reset every few minutes.

See Also
Kernel commands
Displaying the kernel window

SysLog
Displays local SysLog.DAT file. The SysLog.DAT is read from disk before being dis-
played, but is not updated once it is displayed. You need to close and re-open the win-
dow to force it to update. You can use the Page Up, Page Down, and arrow keys to move
through the file, but you cannot edit or save it.

Syntax

SysLog [Delete]
Use the optional Delete keyword to clear (purge) the contents of the SysLog.DAT file.

Note: This window is the same that is used to display the Citect.INI file. You can dis-
play either the Citect.INI or Syslog.DAT in this window, but you cannot display both
at the same time.

See Also
SysLog Format
Kernel commands
Displaying the kernel window

Integration with Historian

CitectSCADA supports the ability to automatically historize and publish variables
within Schneider Electric's CitectHistorian. This capability offers a tightly integrated solu-
tion for collecting historical data, as variables can be passed to the Historian envi-
ronment with minimal configuration. It is a particularly useful feature if your SCADA
project has a large number of variabes that need to be chronicled.
When a CitectSCADA project is added to Historian as a control system data source, the
Use SCADA Configuration To Historize and Publish feature allows tags, trends and
alarms to be imported and automatically configured within the Historian environment.

1142
Chapter 38: Compiling and Running a Project

The automated configuration process will implement any equipment hierarchies defined
in the source SCADA system, and apply the data acquisition method appropriate to the
source variable type.
To prepare variables for automated configuration within Historian, you need to initially
identify them within your CitectSCADA project. For more information, see Preparing var-
iables for Historian integration.

Note: CitectHistorian requires a valid license. Contact your local Schneider Electric
sales representative for more information on the licensing options that are available.

Preparing variables for Historian integration

To allow variables to be automatically configured in Historian, you initially need to iden-
tify the variables you would like included in this process within CitectSCADA. This
involves adjusting the Historize property for each required variable to "true".
The following variable types are supported:
l Variable tags
l Trend tags
l Digital alarms
l Time-stamped alarms
l Analog alarms
l Advanced alarms
l Multi-digital alarms
l Time-stamped digital alarms
l Time-stamped analog alarms
For each variable you would like to be automatically configured in Historian, you need
to set the Historize field on the associated properties dialog to "true". This field is acces-
sible on the extended part of the properties form (use the F2 key for access).

Note: If a variable has the Historian field set to "false", it will still be added to the
Historian data sources directory when an import schema is run. You will still be
able to manually historize and publish the variable within the Historian envi-
ronment.

For more information, see the topic Automating the configuration of SCADA attributes in the
CitectHistorian user documentation.

1143
Chapter 38: Compiling and Running a Project

1144
Scheduler

The information presented in the help is designed for two types of

user, Engineers and Scheduler Users:
l Engineers – An Engineer is experienced in CitectSCADA and
Cicode and understands how these components interact.The Engi-
neer has access to the configuration environment in CitectSCADA
and defines the Equipment, Equipment states and configures the
Scheduler ActiveX control, which the Scheduler user then uses
when adding a new calendar entry. See Scheduler for Engineers.
l Scheduler user – Scheduler users set schedules and have access to
the runtime system only. Have no prior experience with Citect-
SCADA. See Scheduler for Operators.
The Scheduler control has been developed based on a component
from Telerik controls.

1145
1146
Chapter 39: Scheduler for Operators
This section contains information for Operators using Scheduler during runtime. It
describes the following:
1. Scheduler - an overview
2. Understanding the tree-view
3. Adding new Schedules
4. Understanding Schedule Inheritance
5. Overlapping rules

Scheduler - an Overview
The Scheduler control gives you the ability to schedule equipment operations around
peak and non-peak work hours within a business. You can create recurring schedules,
and configure and view schedule entries on a daily, weekly and monthly basis.
You can drag and drop schedule entries, override existing schedules and delete entries
from the calendar view. You can also quickly review scheduled states that are set to
occur.
The Scheduler control has been developed based on a component from Telerik controls.

The Scheduler Interface

The interface is divided into the following areas:
Equipment Tree - On the left of the Scheduler control the Equipment tree is a list of equip-
ment (displayed in a hierarchy) included in the Scheduler project. It is referred to as a
tree as each node is a branch that is dependent on the one above it.
Calendar - Selecting an item of equipment from the equipment tree will determine what
is displayed in the Calendar, as only schedule entries for the selected equipment will be
displayed.There are two views available in the calendar - Configuration and Runtime. In
each view schedule entries can be displayed in a Daily, Weekly or Yearly Calendar.

1147
Chapter 39: Scheduler for Operators

Views within Scheduler

There are two views available in Scheduler. The views are selected using the tabs at the
top of the calendar display.
Configuration - In this view you can add, modify or delete schedule entries for the
selected equipment in the equipment tree.
Runtime - This view is read-only. This view shows the resolved schedules that are to
occur on a daily, weekly or yearly basis.

Understanding the Equipment Tree

The equipment tree lists equipment that was defined as being part of the system's oper-
ations. Equipment is a group of items in the system that you can schedule to operate,
such as a set of lights, a single light in a room, heating or even a motor.
The terms parent and child are used to illustrate the branches in the hierarchy and what
relationship each has to the branch either above or below.

In the diagram above the branch defined as 'Factory' is the parent with the item 'Floor'
as the child. 'Floor' has the item 'Line1' as a child, and 'Line1' has the items Lights 1 to 6
as children.
The tree-view
In the tree-view nodes can be expanded and collapsed to display their children. A con-
text menu is available and its contents are based on the equipment state and current
mode of the equipment. The 'tooltip' indicates the current state of an equipment item.

Context
Icon Equipment Mode
Menu

Automatic mode. The state is either the equipment’s default state, or is set Override
by any active schedules.

1148
Chapter 39: Scheduler for Operators

Context
Icon Equipment Mode
Menu

A piece of virtual equipment. This equipment has NO states defined, how- No con-
ever can have children. A virtual equipment t item does not have a current text
state. menu

Manual override. The state is defined by a value set by using the “Set to Remove
state” menu item. Override
Set to
State

Inherited override. The state is defined by a value set on a parent item of

Override
equipment.

You should understand the relationship of each branch in the equipment tree, as sched-
uled actions on one branch can affect the behavior of branches underneath.
See Also
Schedule Inheritance
Override and Normal Mode

Scheduling entries on Daylight Saving

Twice a year the time is put forward or back one hour in response to the start and end of
daylight saving. In the calendar the period when this transition takes place is grayed out
and you are unable to add a single schedule entry that starts or ends in the transition
period. At the start of daylight saving a message dialog will display if you try and
attempt to schedule equipment with a start or end time in the transition period.
When you schedule entries that include the transition period, the schedule will run
according to the rules below:
For the start of daylight saving:
For single and recurring schedule entries that include the transition to daylight saving,
the entries will run an hour less due to the time going forward one hour. For example, if
the schedule entry is from 1.30 to 3.30 am, and the time is set to switch at 2.00 am (for-
ward to 3.00 am) for the start of daylight saving, then the schedule will run from 1.30 to
2.00 am, and then from 3.00 am to 3.30 am.
For recurring schedule entries set to end during the transition to daylight saving, the
entry will run from start time up to 1:59am (before the transition time). For example if
the schedule entry is set from 1:30 am to 2:30 am, and the time is set to switch at 2am
(forward to 3.00 am) for the start of daylight saving, the schedule will run from 1:30 am

1149
Chapter 39: Scheduler for Operators

to 1:59 am, and on switching to daylight saving time will skip to 3.00 am thus passing
the end time of 2:30 am.
For recurring schedule entries set to start during the transition to daylight saving, the
entry will run from 3.00 am to the end time. For example if the schedule entry is set from
2.30 am to 4.00 am, the schedule will skip to 3.0 am and start from 3.00 am to 4.00 am.
For the end of daylight saving:
For single schedule entries, that includes the transition to daylight saving, the entries
will run for an additional hour due to the time going backwards for one hour. For exam-
ple, if the schedule entry is from 1.30 to 3.30 am, and the time is set to switch at 3.00 am
(back to 2.00 am) for the end of daylight saving, then the schedule will run from 1.30 to
3.00 am, and then after the switch to daylight saving, will run from 2.00 am to 3.30 am.
For single schedule entries that are set to end during the transition to daylight saving,
the entry will run for an additional period from end time to 3.00 am (2.00 am). For exam-
ple, if the schedule entry is set from 1:30 to 2:30, the schedule will run from 1:30 am to
3.00 am (2.00 am), then from 2.00 am to 2:30 am for a total of 2 hours.
For recurring schedule entries that are set to end during the transition to daylight saving,
the entry will run before the switch to daylight saving. For example, if the schedule entry
is set from 1.30 am to 2.30 am, the schedule will run from 1.30 am to 2.30 am for one
hour only.
For single and recurring schedule entries that are set to start during the transition to day-
light saving, the entry will run after the switch to daylight saving. For example, if the
schedule entry is set from 2:30 to 3:30, the schedule will run from 2:30 am to 3:30 am for
1 hour only.
Knowing the rules above for the end of daylight saving you can decide to schedule a
recurring event or a single entry depending on how you want the equipment to behave.

Note: To see resolved schedule entries and how the scheduler is set to behave during
the transition to and from daylight saving, refer to the Runtime View in the Cal-
endar, to view every action set to be executed.

Adding a new Schedule entry

Schedules can be defined for any equipment that has valid states. Schedule entries have
a start and end date and time. You can also make the schedule entry recurring and can
choose from the following recurrence patterns:
l Daily - every day or weekdays,
l Weekly - some or every day of the week,

1150
Chapter 39: Scheduler for Operators

l Monthly - day 15 or 3rd day of the month

l Yearly
To add a new schedule entry:

1. Select the equipment you want to schedule from the equipment tree.
2. In the calendar double-click on the required time slot to create a new appointment.
3. The Appointment dialog will open
4. From the State drop-down menu select the relevant 'State' to schedule for the equip-
ment
5. Add a Description (optional) of the schedule entry
6. Select the Start and End time of the State
7. For single schedule entries select OK to save the entry.

Note: If daylight savings is set to start or end, the time frame (e.g. 2 am to 3 am) is
read-only and schedules cannot be added. Refer to Scheduling entries on Daylight
Saving for more information.

Setting up a recurring schedule

Select the button Edit Recurrence
Use this dialog if the schedule entry needs to occur regularly at the same time, on a
daily, weekly, monthly basis, including on special days.
In the Edit Recurrence dialog:

1. Confirm the Start and End time of the entry.A recurring entry cannot have a duration
of more than 24 hours.
2. In Recurrence Pattern, select either Daily, Weekly, Monthly, Yearly, or Special days.
l Daily - daily occurrence of schedule entry at same start and end time. You can then
select how regularly the schedule will occur, for example every 2 days would mean
the schedule would occur every second day.
l Weekly - occur on the same day every week at the same time
l Monthly - the dialog will refresh. For monthly there are two types of recurrence you
can choose:
The same day of every month . E.g. day 3 of every month or every other month
The day, of a certain week in each month. E.g. first Thursday of every month or
every other month
l Yearly - the dialog will refresh. For yearly there are two types of recurrence you can
choose:
The same day, same month , every year. E.g. Every January 9

1151
Chapter 39: Scheduler for Operators

The day, of a certain week in a certain month. E.g. The third Wednesday of
March.
l Special days - if selected the schedule entry will occur only on special days, that fall
on the selected weekday. To enable "Special days"the radio button "Special Days
Included" needs to be set to something other than "None".
3. In Special days Included Select whether the schedule entry will run on every special
day or selected special days (within a group) or none. If select:
l All Occurrences - the schedule entry will occur on every special day regardless of
group.
l Selected Categories - the schedule entry will occur on the special days within that
group. You can select more than one group.
l None - schedule entry will not occur on special days
4. In the Range of recurrence select the start date and end date (if needed).
l No end date - scheduler entry will occur indefinitely when specified
l End After - select number of occurrences. E.g. 9 occurrences. Schedule entry will
occur 9 times.
l End by - select end date of schedule entry.
5. Click OK to close the Edit Recurrence dialog.
6. Click OK to save the schedule entry.

Note: The schedule entry may disappear from the current configuration view depending on the recurrence
pattern defined for the schedule and when the schedule entry was set to start.

Maintaining Schedule Entries

Editing a Schedule Entry

To modify a Scheduler Entry:

1. Select the relevant Equipment from the Equipment tree-view.

2. Double-click on an existing entry and edit the values in the Edit recurrence dialog.
3. When finished click OK to save the changes.
You can also position the schedule entry box onto a new time slot, or remove recur-
rences by clicking on the Remove Recurrence button in the edit recurrence window.

Deleting a Schedule Entry

1152
Chapter 39: Scheduler for Operators

1. In configuration view select the equipment from the Equipment tree-view.

2. Select the relevant schedule entry and click delete on your keyboard, or select the
delete icon on the entry.
3. Click Ok to confirm deletion.

Overlapping schedule entries

Schedule entries can overlap due to schedule inheritance, or when schedule entries are
created and or modified causing an overlap with one that already exists.
When there is no 'state priority' configured the following rules apply:
l Inherited schedule entries have the lowest priority
l For schedule entries on the same branch, a recurring schedule entry will have a
lower priority than a schedule entry set to run just once.
l For equipment with two or more schedule entries with the same start time, the sched-
ule entry that was accessed last takes precedence.
In configuration view schedule entries that overlap are displayed side by side.
The following example demonstrates the outcome of overlapping schedule entries for the
equipment defined in the table below.

States Schedule Schedule

Equipment What this means
defined entry 1 entry 2

Floor ON and Not sched- Will not be ON. Will resolve to default
OFF uled state OFF

Line1 ON and 1 pm to Will be ON from 1 pm to 4 pm

OFF 4.00 pm in
State ON

Light1 ON and 2.15 pm to 2.30 to 3 Will be ON from 1 pm to 2.30 pm.

OFF 5 pm in pm in State From 2.30 to 3 pm will be OFF. From 3
State ON OFF to 5 pm will be ON.

Light4 ON and 5 pm to 7 5 pm to
OFF pm in State 5.30 pm in Will be in State OFF from 5 pm to 5.30
ON State OFF pm as the second schedule entry was
(accessed (accessed at accessed last and takes precedence.
at 8.30 10.30 am) Will be ON from 5.30 pm to 7.pm.
am)

If State has a priority set, the state with the highest priority defined will take precedence
regardless of recurrence. And if two (or more) schedule entries have the same state prior-
ity the schedule entry with the latest start time will take precedence.

1153
Chapter 39: Scheduler for Operators

States Schedule Schedule

Equipment Priority What this means
defined entry 1 entry 2

Light1 ON and ON = 1 12.30 to 1 to 2.30 Will be ON from 12.30 to 1 pm.

OFF 5.30 pm pm State Will OFF from 1 to 2.30. Will
OFF = 3
State ON OFF return to ON state from 2.30 to
5.30 pm.

Light3 ON and ON = 3 2.30 pm 1.30 pm Will be in State ON from 2.30 to

OFF to 4.30 to 5 pm 4.30 pm and in State OFF from
OFF = 3
pm State OFF 4.30 to 5 pm, as - if two (or
ON more) schedule entries have
the same state priority the
schedule entry with the later
start time takes precedence.

Note: To see how the scheduler is set to behave in regards to over-

lapping schedule entries, refer to the Runtime View in the cal-
endar, to view every action, and order of each set to be executed.

Schedule Inheritance
Schedule Inheritance is where the child branch or branches inherit the schedule entries
from the parent, when the 'state' of the schedule entry is also defined for the child. If the
current parent 'state' is not defined for the child equipment, the child will ignore the
schedule entry of the parent equipment.
Using the tree-view from the previous example,

States
Equipment Scheduled What this means
defined

Floor ON and 3 pm to 6 pm Will be ON from 3 to 6 pm

OFF in State ON

Line1 ON and 1 pm to 3 pm Will be ON from 1 pm to 6 pm as it inherits the

OFF in State ON schedule entry for 'Floor' and 'Line1'

Light1 ON and Not scheduled Will be ON from 1 pm to 6 pm as it inherits the

OFF schedule entry for 'Floor' and 'Line1'

Light2 OFF Not scheduled Will not be ON as not a valid state for Light2

Light3 ON and Not scheduled Will be ON from 1 pm to 6 pm as it inherits the

OFF schedule entry for 'Floor' and 'Line1'

Light4 ON Not scheduled Will be ON from 1 pm to 6 pm as it inherits the

schedule entry for 'Floor' and 'Line1'

To check what schedule entries exist for the equipment, select the item in the tree-view to
refresh the Calendar.

1154
Chapter 39: Scheduler for Operators

l Inherited schedule entries are shaded in dark gray

l Schedule entries belonging to the item are shaded in a gradient light gray

Override and Normal mode

Equipment can be in normal or override mode.
Normal Mode: Every schedule entry for the equipment will run. If no schedule entry
exists for the equipment, it will resolve to its default state.
Override Mode: When enabled, schedule entries belonging to that equipment are
ignored. You can then manually execute 'state' changes on that equipment.
When equipment is in Override mode the following rules apply:

l When override mode is enabled on equipment that is classed as a parent, itself and
child equipment will inherit the override mode and any state changes from the par-
ent.
l If the child is set to override mode, the child will not inherit the schedule entry from
the parent. When override mode on the child is disabled, it will go into inherited over-
ride mode and will inherit any schedule entries from the parent.
The following tables outline both rules:

States
Equipment Mode Scheduled What this means
defined

Floor ON and OFF Override No schedule entry 'State' can be manually

changed

Line1 ON and OFF Inherited 1.30 to 2.30 pm in Will be ON from 1.30 to

override ON State 2.30 pm

Light1 ON and OFF Inherited 3.30 to 5.30 pm ON Will be On from 3.30 to

override State 5.30 pm

Light2 OFF Inherited No schedule entry Will be in default state

override OFF

Inherited 2.30 to 5.30 pm Will be On from 2.30 to

Light3 ON and OFF
override State ON 5.30 pm

States
Equipment Mode Scheduled What this means
defined

Floor ON and Override 7 am to 11 am Will be ON from 7 to

OFF in State ON 11 am

1155
Chapter 39: Scheduler for Operators

States
Equipment Mode Scheduled What this means
defined

Line1 ON and Inherited override 1.30 to 2.30 Will be ON from 7 to

OFF pm in State 11 am (Inherited)
ON and ON from 1.30
to 2.30 pm (as
scheduled)

Light1 ON and Override 10 am to 12 Will not inherit

OFF pm in State schedule entry from
ON 'Floor' as in Over-
ride mode.Will be
ON from 10 to 12
pm as scheduled.

Light2 OFF Inherited override no entry Will not go into

State ON at 7 am as
'ON' is not a valid
state for this equip-
ment

To enable override mode:

From the Equipment tree-view right click on the equipment branch
Select Override. Branch is now in Override mode.
To manually set state changes:

1. Right click on the branch and select Set to State

2. In the Set to State dialog box, select the new state of the equipment and click OK to
apply the change.
To disable override mode:
From the Equipment tree-view right click on the equipment branch and Select Remove
Override

Special Days
Special days are days where the normal daily or weekly schedule of equipment does not
apply. In the Edit Recurrence dialog you can select the group or type of special day, and
when each day will occur.
When adding a new schedule the following rules apply:
l Daily, weekly, monthly and yearly schedule entries will not occur on a special days,
unless specified using the options in the Special Days Included area.
l For schedule entries you want to occur only on 'special days' and not on normal
days then select in the Recurrence area, 'special days' and select the day you want

1156
Chapter 39: Scheduler for Operators

the schedule to run. If the special day falls on the selected weekday, the schedule
entry will run.

1157
Chapter 39: Scheduler for Operators

1158
Chapter 40: Scheduler for Engineers
This section describes the following:
1. Understanding Scheduler
2. Defining Equipment for inclusion into Scheduler
3. Define States belonging to Equipment
4. Add and configure the CitectSCADA ActiveX control onto a graphics page
5. Configuring Special days

Understanding Scheduler
Scheduler is a component of the Report server with an ActiveX control that enables you
to link your CitectSCADA system to a calendar. When configured you can schedule your
systems operations, for example, schedule operations around peak and non-peak periods
with lighting, heating and other equipment within your system set to turn on and off
depending on when people will be there, thus optimizing energy efficiency.You can also
use Scheduler to plan maintenance days whereby any equipment that is not required
can be turned off.

The Scheduler Engine

Scheduler has been designed to be a core component of the report server. This provides
tight integration with the SCADA. It also supports the online change functionality avail-
able with the 7.20 CitectSCADA release using the report server reload.
With the Scheduler release, equipment definitions are now part of the report server proc-
ess. This means that the equipment browse now returns data from the centralized report
servers. The equipment information will be cached on the client so it will still provide
the existing client side performance while adding centralized online change func-
tionality.

1159
Chapter 40: Scheduler for Engineers

Backing up CitectSCADA
Back up your CitectSCADA project as you would any project within CitectSCADA. A
backup will include the configuration settings made during design time. See below for
backing up runtime defined schedules.
Refer to the topic Backing up a project for more information in the CitectSCADA main
help.
To back up schedule entries made at runtime using the Scheduler ActiveX control interface:
Copy the [ClusterName].[ReportServerName].scheduling file (i.e. Cluster1.-
ReportServer1.scheduling.xml) from the CitectSCADA 'Data' directory on your local
machine to a secondary location.
To restore the scheduler engine state and configuration view within the Scheduler Acti-
veX control- copy the xml file back into the Data directory.
To confirm the restore open the Scheduler page at runtime and select the configuration
view.

Scheduler Security and Permissions

Scheduler integrates into the CitectSCADA security model by allowing access to certain
features based on the areas the user has access to.
When adding equipment to Scheduler, you can define the area to which the equipment
belongs. This helps to add security around the use of equipment, as the Scheduler inter-
face will only list equipment that is available to the current user. They will only be able
to create, modify, delete and browse schedules for equipment that belongs to the area or
areas they have access to. If the user attempts to access equipment in other through
Cicode, an error code is returned.
When a new user logs on, the Scheduler interface will refresh and list the equipment
which is available to that user, based on the areas the user has permission to access.
For more information regarding Security refer to the section Using CitectSCADA Security
in the CitectSCADA main help.

1160
Chapter 40: Scheduler for Engineers

Online Changes
Online changes have been extended to include CitectSCADA. Records can be modified
during runtime using the project editor, recompiled and the resulting database files
updated ( for CitectSCADA the files are equip.dbf and restate.dbf). You can initiate a con-
figuration reload for each server using the Runtime Manager or using Cicode functions.
The following rules apply:
l If you delete equipment or an equipment state, the engine will not process any sched-
uled entries that belong to that equipment or equipment state.
l If you modify an equipment name or the name of an equipment state, it is similar to
deleting the equipment or equipment state and adding a new one.

Redundancy
For CitectSCADA it is recommended a redundant report server is configured. Syn-
chronize the time on both servers.

1161
Chapter 40: Scheduler for Engineers

Redundancy is supported for the scheduler engine and is provided as follows:

l When connection is established the scheduler files are synchronized (merged)
between the Peer Report Servers.
l Only the active server will execute the schedules. When both servers are running the
active server will be the first server that was started. If a network outage occurs, after
it is restored the primary will become active.
l When both servers are online, changes to the Scheduler file are replicated across both
servers.
l If one of the Report servers becomes inoperative the schedules will run on the remain-
ing Reports server. When the inoperative report server returns online, the client will
remain with the current Reports server.
For more information about redundancy refer to the topic Alarms, Reports and Trends
Server Redundancy in the CitectSCADA help.

Note: At startup the scheduler engine may begin executing actions before other
server processes in the system are available. This may result in the action not com-
pleting successfully. To help avoid this issue, use the ini parameter [Scheduling]Start-
Delay to delay the startup of the scheduler engine. This allows time for the other
server processes of the system to come online before any scheduled actions are ini-
tiated.

Kernel Trace Messages

The scheduler outputs status information to the kernel regarding the Runtime Transition
Manager and the Redundancy engine.

UNINTENDED EQUIPMENT OPERATION

Runtime Transition Manager

These messages are prefixed with “Runtime Transition Manager:”

1162
Chapter 40: Scheduler for Engineers

Start delayed - Start operation was requested but delayed due to the start delay period
not being elapsed. The message indicates that the start will occur later and specifies in
how many milliseconds. A timestamp is supplied indicating the local time that the start
was called.
Started - Runtime Transitions Manager has been started, and a local timestamp sup-
plied indicating when.
Delayed Start Cancelled - Prior start call which was queued due to startdelay has been
dequeued and not started.
Stopped - Runtime Transition Manager has halted its operation, a local timestamp indi-
cating when.
Redundancy Engine

These messages are prefixed with "Scheduler Redundancy:"

Synchronization stopped due to connect failed - Synchronization has been aborted due
to a lack of connection between the local and peer.
Synchronization stopped due to disconnect - Synchronization has been aborted due to a
connection disconnection between the local and peer.
Synchronization initiated from (peer or local) – Synchronization has been started. Peer
or local will be specified in this method, and indicates which server is initiating the syn-
chronization start.
Synchronization Complete - This indicates that a synchronization has successfully com-
pleted.

Tracelog Trace Messages

The scheduler outputs diagnostics information to the platform trace log.
For more information regarding log files and the rules belonging to platform logging sys-
tems refer to the section Monitoring and Debugging Runtime in the CitectSCADA main
help.
The tracelog.Report.<Report server name>.dat file contains report server related trace
information and is similar to the syslog.dat file.
Refer to the [Debug] parameters help section in this guide for information pertaining to
logging. If you require additional information refer to the help for the Computer Setup
Editor in CitectSCADA.

1163
Chapter 40: Scheduler for Engineers

Notes:By default the logging levels are set to every category, but only Critical and
Error level traces will be logged. As the traces from the scheduler are currently Infor-
mational only, change this level to include information. (If that is the only change
made, then informational traces from every component will be directed to the trace-
log) With manipulation of the debug ini parameters, you can fine tune a fairly gran-
ular trace set.
Example for scheduler critical, error, information ONLY:
[Debug]SeverityFilter= Critical,Error,Information
CategoryFilterMode=0
CategoryFilter=Scheduler

Runtime Transition Manager

These messages are prefixed with “Runtime Transition Manager:”

Start delayed - Start operation was requested but delayed due to the start delay period
not having elapsed. The message indicates that the start will occur later and specifies in
how many milliseconds. A timestamp is supplied indicating the local time that the start
was called.
Started - Runtime transitions manager has been started, and a local timestamp supplied
indicating when.
Delayed Start Cancelled - Prior start call which was queued due to startdelay has been
dequeued and not started.
Stopped - Runtime transition manager has halted its operation and a local timestamp
indicating when.
Equipment

These messages are prefixed with "Equipment"

Mode changed - Gives an equipment name, the previous mode (Automatic or Manual)
and the new mode, along with the standard timestamp information of when the tran-
sition occurred.
Demand Response Mode changed - Gives an equipment name, the previous demand
response mode (numeric) and the new mode, along with the standard timestamp infor-
mation when the transition occurred.
Manual state changed - Gives an equipment name, the previous state (string) and the
new state, along with the standard timestamp information when the transition occurred.
This message is only triggered on manual override state changes.
State changed - Gives an equipment name, the previous state (string) and the new state,
along with the standard timestamp information when the transition occurred. This mes-
sage will be triggered for both automatic equipment state changes and manual ones.

1164
Chapter 40: Scheduler for Engineers

Note: Currently traces for equipment property changes are logged on the server that
they occurred on. No updates done via synchronization are logged.

Time Synchronization
For operators to schedule equipment during the transition of daylight saving the client
and server should be in the same time zone.
If the time of the client machine is no longer synchronized with the time of the server
unplanned state changes may occur or state changes may not occur at the correct time.

Configuring Scheduler

Before Getting Started

Before configuring Scheduler you need to understand the following terms that are used
throughout this guide:
l Equipment – a component or set of components that when grouped form a logical
item within CitectSCADA.
l States – any condition or mode of operation belonging to the equipment. For example
a light may have two states, on and off.

Scenario

The following ‘factory’ scenario will be used for examples throughout the Scheduler
help.

1165
Chapter 40: Scheduler for Engineers

Configuring Equipment for Inclusion in Scheduler

In Scheduler, equipment is any item or items in your control system that can be sched-
uled to operate, such as a set of light, a single light in a room, heating or even a motor.
Equipment is defined in CitectSCADA using the Equipment form, which is accessible
from the Equipment menu in the Project Editor.
The following fields are used specifically when setting schedules for this item of equipment:
Scheduled
Select True or False from the drop down list. For Scheduler select the option True for the
equipment to be listed in the CitectSCADA interface at runtime.
Default State
From the drop down list select the default state. The State should be defined using the
State form. For the light in meeting room 1 the default state would be OFF.

1166
Chapter 40: Scheduler for Engineers

The equipment should have a default state defined belonging to the same cluster. If no
default state is defined there will be a compile error.
Example - equipment hierarchy in Scheduler:
Using the 'Factory ' scenario the lights for Line 1 and the lighting and heating for Meet-
ing room 1 need to be added into the system as equipment.
Follow the naming convention guidelines (described in the topic Equipment Properties
enter the names as:
Factory.Offices.MeetingRoom1.Lighting
Factory.Offices.MeetingRoom1.Heating
Factory.Floor.Line1.Light1
Factory.Floor.Line1.Light2
Factory.Floor.Line1.Light3
Factory.Floor.Line1.Light4
Factory.Floor.Line1.Light5
Factory.Floor.Line1.Light6
At runtime the following tree is displayed in the Scheduler.

Once you have configured the equipment for your system, you need to define the
required equipment states. For example, the light in meeting room 1 the default state
would be OFF.
See Also

Configuring Equipment States

Equipment States Properties

1167
Chapter 40: Scheduler for Engineers

Configuring Equipment States

Equipment States belong to equipment and determine the action that the item or group
of equipment will take at a scheduled time. As equipment can have multiple states, iden-
tify the states that exist for the equipment before defining them. For example, in the fac-
tory scenario described earlier, the heating in meeting room 1 could have three states: on,
off, or standby. The lights in meeting room 1 could be identified to have two states: on
and off.
See Also

Equipment States properties

Editing States
From the project editor choose Equipment | Equipment States
Modify the properties of the States form, when complete
Click Replace to modify an existing record.

Equipment State Properties

UNINTENDED EQUIPMENT OPERATION

Do not use the scheduler in situations where equipment state actions must be executed.
The engine does not ensure that defined actions are executed for every state transition. The
scheduler engine will not be able to run actions when other state actions for the same equip-
ment take longer time to complete or a communication fault occurs.

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

From the Project Editor choose System | Equipment States

Field Description

Name Name of the State. Usually this would be an 'action' the equipment could be
scheduled to do. For example, a light could have the action 'on' or 'active'
defined.

Equipment The equipment belonging to this state. For example: "Fac-

1168
Chapter 40: Scheduler for Engineers

Field Description

tory.Floor.Line1.Light1".
Equipment should be an existing item on the selected cluster.

Cluster The name of the cluster to which this State will belong.
Name

Entry The action the State will take when triggered. For example the entry action for
Action light 1 could be tag_light1=1. When light1 is scheduled, this will trigger the
light to turn on. Entry Action can be any Cicode expression.

Repeat An action set to run periodically when state is active.

Action

Delay The time that needs to elapse before the state will initially become active.
If delay is defined the Entry Action for the state will not occur until the delay
period has elapsed. For example; this would allow you to turn on every light
sequentially to avoid a power spike.

Period Sets the frequency of the 'Repeat Action'. For example set the repeat action to
occur every hour.
Note: The repeat period will not start until the entry action has completed. The
first repeat action will occur after the entry action completes plus one repeat
time period. For example, if the Entry Action takes ten minutes to complete, the
Repeat Action will not start until after ten minutes even though the Repeat
Action is set to occur every two minutes.

Comment Any useful comment.

The following fields are implemented with extended forms (press F2).

Extended forms fields

Field Description

Priority Number used to determine which schedule entry will run if a schedule conflict
occurs between more than one state.

DR
Demand and response mode (DR). The default DR mode value is 0.
Mode

Click Add to append a new record, or Replace to modify an existing record.

Note: If the report server is run in single process mode and no user is logged in, all
tag writes attempted by the scheduler when actions are run will not succeed. We rec-
ommend running the report server(s) in multi-process mode to avoid this issue (the
server user will be logged in), or setting the citect.ini parameter [Client]Auto-
LoginMode to either 2 or 6 to insure a user is always logged in.

1169
Chapter 40: Scheduler for Engineers

Configuring States with Entry Action

UNINTENDED EQUIPMENT OPERATION

Do not use the scheduler in situations where equipment requires a guaranteed sequence of
successful actions. The scheduler engine will attempt to run the actions in the correct
order, but if entry actions take too long or a failure in communications occurs when an
entry action is run, the engine does not guarantee that the equipment will receive every
command.

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

The entry action is a Cicode expression to execute when the equipment transitions to the
state. For example, the expression can be used to write a value to a variable tag.
Using the factory scenario described earlier, the states 'ON' and 'OFF' were identified for
the heating in meeting room 1. The states would be configured as below:

Field Value

Name ON

Equipment Factory.Office.MeetingRoom1.Heating

Cluster Name Cluster1

Entry Action tag_heating=1

Field Value

Name OFF

Equipment Factory.Office.MeetingRoom1.Heating

Cluster Name Cluster1

Entry Action tag_heating=0

An entry action when triggered, causes the equipment to perform a certain action. In the
example above when the state is changed the heating will either turn on or off.

1170
Chapter 40: Scheduler for Engineers

Note: If the report server is run in single process mode and no user is logged in, all
tag writes attempted by the scheduler when actions are run will fail. We recommend
running the report server(s) in multi-process mode to avoid this issue (the server
user will be logged in), or setting the citect.ini parameter [Client]AutoLoginMode to
either 2 or 6 to insure a user is always logged in.

Open the runtime view to see the actions that are planned to be executed. You can ena-
ble the tag write event queue logging to help identify incomplete actions. Refer to the
[General]TagWriteEventQue parameter in the CSE Help Reference for more information.

SchedulerConfiguring States with Delay

When configuring states you can define a delay. A delay is a period where the entry
action does not occur until the period of the delay has elapsed. Delay enables you to turn
on equipment sequentially thus avoiding a power spike and being more energy efficient.
Using the factory scenario described earlier, the states on and off were identified for the
lights 1 to 6 for line 1. To avoid a power spike when every light was turned 'ON' at the
same time, a delay is set for each 'ON' state belonging to the lights.
The 'ON' states would be configured as below:

State Equipment Entry Action Delay

ON Factory.Floor.Line1.Light1 tag_l1l1=1 00:00:01 secs

ON Factory.Floor.Line1.Light2 tag_l1l2=1 00:00:02 secs

ON Factory.Floor.Line1.Light3 tag_l1l3=1 00:00:03 secs

ON Factory.Floor.Line1.Light4 tag_l1l4=1 00:00:04 secs

ON Factory.Floor.Line1.Light5 tag_l1l5=1 00:00:05 secs

ON Factory.Floor.Line1.Light6 tag_l1l6=1 00:00:06 secs

This means lights 1 to 6 will turn on over a period of 6 seconds, when triggered at the
same time. A light every second.

Configuring States with Repeat Action and Period

1171
Chapter 40: Scheduler for Engineers

UNINTENDED EQUIPMENT OPERATION

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

When configuring states you can define a repeat action. This action can be set to repeat
for the specified repeat period. For example, the heating set point can be adjusted to fol-
low the outside temperature trend to save energy. The first repeat action will execute
after waiting for one repeat period starting after completion of the entry action.

Field Value

Name ON

Equipment Factory.Office.MeetingRoom1.Heating

Cluster Name Cluster1

Entry Action tag_heating=1

Repeat tag_heating_sp = MySetpointAdjusted(tag_heating_temp, tag_outside_

Action temp)

Period 00:15:00

Note:
• The repeat action will only start after the entry has completed.
• The repeat action will re-trigger at or after the specified period.
• The repeat action will not re-trigger until the previous repeat action has completed.

Demand and Response Support

Demand and response (DR)refers to the mechanisms used for the management of elec-
tricity consumption in response to supply conditions. The Open ADR is an example of a
standard that can be used to help automate demand response in commercial buildings.
To provide demand response, a system has pre-defined levels that are used to adjust the
expected consumption of energy.
You can use CitectSCADA to implement a demand and response solution.

1172
Chapter 40: Scheduler for Engineers

In Scheduler, states can be defined multiple times, each for a specific DR mode. Thus the
state that is action-ed (scheduled to occur) is determined by the DR mode for the equip-
ment. In the example below "line2.lights" has multiple 'On' States with different DR
modes. This allows the room to be scheduled for ‘On’, with the amount of energy con-
sumed adjusted according to the assigned DR mode.

Equipment DR Entry
Equipment Description
State Mode Action

Factory.Floor.Line2.Lights On 0 Tagl2_ When scheduled light will

lights=1 turn on at 100% energy out-
put

On 1 Tagl2_ Energy saving 20%

lights=80

On 2 Tagl2_ Energy savings is 40%

lights=60

On 3 Tagl2_ Energy savings is 60%

lights=40

ON 4 Tagl2_ Energy Savings is 80%

lights=20

Off 0 Tagl2_
lights=0

The default DR mode value is '0'. When the DR mode field is empty, the default value is
used. The scheduler engine selects the state with the nearest lower DR mode value in the
case where an exact match to the current specified DR mode is not found.
Set the DR mode on equipment using the EquipSetProperty Cicode function
For example : EquipSetProperty (Equipment, "DRMODE", "1", cluster)

Using the Scheduler ActiveX Control

Adding the CitectSCADA ActiveX control to a pageScheduler

Being an ActiveX control, you can insert the CitectSCADA as an object on a Citect-
SCADA graphics page.
To do this, do one of the following:

l Go to Edit | Insert ActiveX Control. The Insert ActiveX dialog box appears.
l Double-click the CitectSCADA Control item in the ActiveX Controls list box.
l In Graphics Builder go to Objects | Scheduler or Ctrl-U
l In Graphics Builder, display the toolbar from the View|Show Toolbar menu and
click the Scheduler tool.
The Scheduler Control properties dialog will open.

1173
Chapter 40: Scheduler for Engineers

For details on configuring the properties for the control, see the topics: ActiveX Object
Properties - Appearance (Tag Association), and Defining Common Object Properties in
the CitectSCADA help.
As an ActiveX control you can resize, and re-position the control on the page. For Citect-
SCADA resize the control so the whole calendar will display in the control window at
runtime.
See Also

States

Defining States

Configuring Special Day Groups

Special days are days where the normal daily or weekly schedule does not apply to your
equipment. Using the Special Day Cicode functions you can add, modify and delete spe-
cial days and special day groups. The groups are used to organize the different types of
special days. For example, school holidays, public holidays, or days set aside for system
maintenance.
The special days can be viewed in the Scheduler ActiveX Control. Special days are high-
lighted in the view and the list of available groups is available on the edit recurrence
dialog.
Using Cicode and the Graphics Builder, you can create a user interface that would allow
the operator to add a new special day or create a new special day group

1174
Using the Web Client

This section contains information on the Web Client and describes

the following:
The CitectSCADA Web Client
System architecture
Getting Started
Preparing a Project for Deployment
Configuring a deployment
Implementing Multiple Language Support
Web Client Upgrade Issues
Frequently Asked Questions

1175
1176
Chapter 41: The Web Client
The CitectSCADA Web Client allows you to view a live CitectSCADA project within a
Web browser. It provides easy access to CitectSCADA Runtime for LAN-connected users
requiring read/write access to current production information.
For example, a senior manager could monitor a facility and access current production
information from any computer on the LAN without the need for extensive downloads
or software installation.

Note: On 64 bit Windows operating systems (XP 64 bit and Vista 64 bit), there are
two Internet Explorer options. One for 32 bit mode and one for 64 bit mode. The Web
Client needs to be used in Internet Explorer 32 bit mode.

If you start the Control Client and then start the Web Client on the same machine run-
ning Windows Vista operating system, an alert message will be displayed. This will
occur for projects that use ActiveX executable components, for example the Example
project. In order to use these projects you need to add the Web Server address as a
trusted site in Internet Explorer.
See Also
System architecture

System architecture
To display a live CitectSCADA project in an Internet browser, you need to combine the
content of the project pages and the current data these pages present using standard,
Web-based communication protocols. To understand the communication architecture for
the CitectSCADA Web Client, it's easiest to consider the role each of the following com-
ponents play in achieving this outcome:
l CitectSCADA Web Server - Performs the server-side functionality of the system. It
operates by accepting requests from the client, and providing a response to the client
when the clients details are authenticated. It then directs a client to the graphical and
functional content of a CitectSCADA project and the location of the runtime servers.
This information is stored on the Web Server when a CitectSCADA project is con-
figured as a "deployment". A CitectSCADA Web Server can contain multiple deploy-
ments.

1177
Chapter 41: The Web Client

l CitectSCADA Runtime Servers (including the I/O Server, Alarm Server, Trends
Server and Reports Server) - Monitor the physical production facility and contain
the live variable tag data, alarms and trends that the Web Client will display.
l Web Client - provides the platform to merge a deployed project's pages and content
with the raw data drawn from the runtime servers. Again, standard Web tech-
nologies are necessary, so the client uses Microsoft Internet Explorer.
The following diagram shows how these components interact.
CitectSCADA Web Client communications architecture.

1178
Chapter 41: The Web Client

Once the Web Client has connected to the Runtime servers, steps 2 and 3 become an
ongoing process, with the necessary content being called upon as the user navigates the
project pages.
The citect.ini file settings used by a Web Client are taken from the citect.ini file on the
Web Server at the time of connection.
This diagram has the system components set up on different computers purely for the
sake of explaining the communications model. In reality, the flexibility of the architecture
allows these components to be distributed in any necessary arrangement; they can even
share a common location.

Getting Started
The CitectSCADA Web Client Help is designed to guide you through the steps necessary
to successfully set up a Web Client system.
For detailed information on installing and configuring the web server for both Microsoft
IIS and Apache, refer to the The CitectSCADA Installation and Configuration Guide
which is available in a PDF format on the Installation CD, or in the Documentation
folder of your CitectSCADA installation.
To facilitate your installation, first familiarize yourself with the System architecture, and
then work your way through the following steps, as they will logically guide you
through the correct set up procedure.

1179
Chapter 41: The Web Client

Note: In order to implement a web client solution you need to first install Microsoft
.NET Framework 2.0 on the web client machine.

1. Preparing a CitectSCADA project for deployment

This section explains the adjustments that need to be made to a CitectSCADA
project prior to deployment on the Web Server.
l Preparing a Project for Deployment
2. Configuring a deployment
This section describes how to deploy a project on the Web Server, by identifying its
source location and associated servers.
l Configuring a deployment
3. Multi-language support
If you are using IIS as your Web Server platform, there are several language
options you can implement on the Web Server interface.
l Implementing Multiple Language Support
If you have followed the procedures outlined above and your deployed project does not
seem to be performing as expected, use the Frequently Asked Questions section to help
resolve any issues you might be having.

Preparing a Project for Deployment

Before deploying a project on a Web Server, you will need to makes adjustments in the
CitectSCADA configuration environment to get it ready for Web-based delivery. In pre-
paring to make these adjustments, consider the following:
l Functionality limitations of the Web Client platform
l Identifying external files for inclusion in a deployment
l Running the Web Deployment Preparation tool

Note: To use the Web Client, your CitectSCADA system needs to be configured to
communicate using TCP/IP. This means the network addresses in your project needs
to be defined using standard IP addressing.

1180
Chapter 41: The Web Client

Functionality limitations of the Web Client platform

Due to the architecture necessary to support Web-based execution of CitectSCADA
projects, the Web Client cannot offer the full functionality of a standard CitectSCADA sys-
tem.
Consider the list of feature limitations and Cicode function limitations to assess if this
will be detrimental to the performance of your project. Some adjustments might be nec-
essary.
See also
Feature limitations
Cicode Function Limitations

Feature limitations
The following features are not supported:
l Cicode Debugger
l Remote shutdown
l Fuzzy Logic
l Kernel windows
l Keyboard shortcuts that clash with Internet Explorer's keyboard shortcuts
l Web Client is unable to act as a CitectSCADA Server
l Pages based on the default Menu Page template will only show buttons for pages pre-
viously visited
l The Page Select button on the default Normal template only lists pages previously
visited
l The CSV_Include project's Update Page List menu item will not work

Note: If your project is based on the CSV_Include template, you need to create a
customized menu to access pages from the menu bar.

See Also
Functionality limitations of the Web Client platform
Cicode Function Limitations

Cicode Function Limitations

Several Cicode functions are unavailable with the Web Client, or limited in their capabil-
ities:

1181
Chapter 41: The Web Client

Cluster Func- Cluster functionality not supported

tions

DebugBreak Cicode debugger not supported

DelayShutdown Programmatic Shutdown not supported

FTP Functions Not every FTP function is supported

Fuzzy Logic Removed from control due to size

Functions

KerCmd Kernel windows not supported

Pro- Programmatic Shutdown not supported

jectRestartGet

Pro- "
jectRestartSet

ProjectSet "

Shutdown "

ShutdownForm "

SwitchConfig Configuration environment not available

TraceMsg Kernel windows not supported

UserCreate Changes to user profiles need to be made on the machine where the
project is compiled and auto-deployed.

UserCreateForm "

UserDelete "

UserEditForm "

UserPassword "

User- "
PasswordForm

GetWinTitle Windows other than the main window only

1182
Chapter 41: The Web Client

WinFree "

WinMode "

WinMove "

WinPos "

WinSize "

WinTitle "

WndShow "

WndViewer Invokes multimedia applications. Feature not supported

See Also
Identifying external files for inclusion in a web deployment
Functionality limitations of the Web Client platform
Feature limitations

Running the Web Deployment Preparation tool

The final step in preparing a project for deployment involves running it through the
Web Deployment Preparation tool. This takes a freshly compiled project and creates the
necessary files and directories for Web-based delivery.
To run a project through the Web Deployment Preparation tool:

1. Verify that the project you want to deploy has had any associated user files or Acti-
veX objects identified in the Web Client Files dialog (see Identifying external files for
inclusion in a deployment).
2. Check the Fast Runtime Display option in the Graphics Builder. Update pages and
pack libraries for include projects and then main projects.
3. Locate the project you want to deploy in Citect Explorer and do a fresh compile.
4. Go to the Citect Explorer Tools menu and select Web Deployment Preparation (or
click the following icon on the Explorer toolbar):

5. A progress indicator appears. The size of the project significantly affects how long
this process takes; a large project with many files can take over ten minutes to proc-
ess, depending on your hardware. (You can abort the deployment preparation if you
want.)

1183
Chapter 41: The Web Client

6. When complete, a dialog appears stating the preparation was successful. Click OK.
The project is now ready for deployment on the Web Server. If you change a
project, you need to do a fresh compile and run the Web Deployment Preparation
tool again.

Note: You can run the Web Deployment Preparation tool automatically when you
compile a project. To do this, go to the Citect Project Editor Tools menu and select
Options. Select the Prepare for Web Deployment option and click OK. Be aware that
this increases the time taken for each compile, particularly for large projects.

Configuring a deployment
A deployment represents the implementation of a CitectSCADA project on the Web
Server. It incorporates the files and components necessary to display a project, and keeps
a record of the location of the servers where CitectSCADA Runtime data is generated.
The deployments configured on a Web Server are listed on the Web Client home page,
which is the page that appears when you initially log in. The configuration details for a
deployment can be displayed by clicking the small plus (+) icon to the left of the deploy-
ment name.
The type of action you can implement for a deployment depends on the permissions
granted by your log in. For example, if you log in as a View-only Client, you can only
view a deployment. If you are an administrator, you can edit deployments and create
new ones.
The following list describes the functionality associated with each of the icons presented
on the home page.:

Add New Deployment - takes you to the Deployment Configuration page

where you can create a new deployment (Administrator Clients only).

Help - displays this help page on how to configure and use the Web Client.

Edit Deployment - takes you to the Deployment Configuration page and

allows you to edit the selected deployment (Administrator Clients only).

Delete Deployment - Deletes the selected deployment (Administrator Clients

only).

Start Control Client - Displays the selected deployment with Control Client
permissions (Control Client and Administrator Client only)

1184
Chapter 41: The Web Client

Start View-only Client - Displays the selected deployment with View-only

Client permissions

Additionally, the System Messages panel provides notification of events that impact the
current status of the Web Server.

Note: The Citect.ini file settings used by a Web Client are taken from the Citect.ini file
on the Web Server at the time of connection. This includes which clusters a Web
Client has access to. To switch clusters in a project viewed using a Web Client, use
the functions ClusterActivate and ClusterDeactivate.

See Also
Preparing a Project for Deployment
Creating a new deployment
Deploying a project from within CitectSCADA
Displaying a deployment
Editing an existing deployment
Updating a deployment to reflect project changes
Deleting a deployment

Creating a new deployment

To configure a deployment of a CitectSCADA project on a Web Server, you need to log in
to the Web Client with Administrator permissions. This will provide you with access to
the full functionality of the home page.
To add a new deployment

1. Click the Add New Deployment icon.

This will display the Deployment Configuration page.

2. Type a name in the Deployment text box, and include a Description if necessary. A
deployment name cannot contain any of the following characters: \ * ? | . , / " ' :
; < > # &

Note: If you've upgraded your version of the Web Client, you can still view your
legacy deployments that you created using version 6.1 or earlier of the Web
Client. For details, see Web Client Upgrade Considerations.

3. Identify the source of the CitectSCADA project's content in the Project Path field.

1185
Chapter 41: The Web Client

If the project is located locally on the Web Server, you can use a normal path
address. The path needs to point directly to the project within the
CitectSCADAUser directory. For example, the location of the MyExample project
would be:
[User]\MyExample

Note: If you are remotely administering the Web Server and use a local path
address, verify that the path represents the location of the project on the Web
Server computer, not the computer you are currently using.

If the project is not located on the Web Server, you need to use a UNC address that
identifies the host network computer and the directory it can be found in. For
example,
\\ComputerName\<path to application data>\User\MyExample

Note: You need to share the directory a project resides in to allow the Web Server
access to it. Ideally, create a share from the directory (called WebShare, for exam-
ple) and then use the following project path:

\\ComputerName\WebShare

Remember that if you are trying to access the project directory from a remote com-
puter, a "local" administrator log in will not provide you with appropriate access
on a different computer. use a network user profile that will be recognized by other
computers on the same domain.
4. Determine if any of the I/O, Alarms, Reports or Trends Servers associated with the
project are protected by a firewall. If they are, you need to confirm with the firewall
administrator if the CitectSCADA ports have been opened to allow direct access, or if
the firewall is using address forwarding.
If forwarding is being used, you will need to identify each server by typing the
name in the Server field, using the following format:

If you have alarm properties enabled on an Alarm Server, you will need to con-
figure an alarm properties connector as a separate server to let the Web Server
know which port it is running on. Type the Alarm Server name in the Server field,
using the following format:
<ClusterName>.<AlarmServerName>_AlarmProps

For example:
ClusterOne.AlarmServerOne_AlarmProps

1186
Chapter 41: The Web Client

Type in the Address and Port for each server, as supplied by the firewall admin-
istrator.

Note: The Web Client will automatically add any servers that are redirected in
this way to the [AddressForwarding] section of the local Citect.ini file. See Using
address forwarding for more information.

You can add additional servers to the list by selecting the Add New Server icon.
5. Use the Client Control text box to specify the use of a particular version of the Web
Client component when the deployment is displayed.
The menu lists the different versions of the Web Client control currently installed
on the Web Server. Typically, choose the version of the control that matches the
version of CitectSCADA your project was compiled on.
6. Click Apply Changes.

This is important, as you'll lose your changes if you jump straight back to the
home page.
All the project files are retrieved from the path indicated, and copied to the Web
Server ready for access by the Web Clients.
Once complete, information about the size of the project appears in the File Paths
banner above the Project Path field. The number to the left indicates how many
files are included in the project; the number to the right indicates the total size of
the project.
The deployment is saved. When you return to the Web Client home page, by clicking the
home icon, your new deployment is listed.
See Also
Deploying a project from within CitectSCADA
Displaying a deployment

Deploying a project from within CitectSCADA

The Web Client architecture lets you deploy a project from within the CitectSCADA con-
figuration environment, avoiding the need to use the Web Client interface to setup a sys-
tem.
This process requires you to adjust two parameters in the Citect.ini file:
l [WebServer]WebClientCab

l [WebServer]DeployRoot

1187
Chapter 41: The Web Client

These parameters identify the client component used with the project and the location of
the deployment root directory. When the project is compiled and prepared for deploy-
ment, it is placed directly on the Web Server.
Notes:
l If you've upgraded your Web Client to version 7, you can still view your legacy
deployments. For details, see Web Client Upgrade Issues.
l When implementing this option, consider to your Citect.ini file configuration, as any
errors with these parameters are difficult to diagnose. To avoid input errors, use the
Web Deployment Tool on the Citect Explorer tool bar with the Web Server's Web
Deployment GUI.
l If the project name contains non-ASCII characters, deploying from within Citect-
SCADA might be unsuccessful and raise errors. Under these circumstances, use the
Web Server interface to create the deployment.
To deploy a project from within CitectSCADA:

1. Confirm that your CitectSCADA system is configured to use TCP/IP. If you run the
Computer Setup Wizard, the Networking page will identify which communications
protocol is being used.
2. Adjust the [WebServer]DeployRoot parameter within the Citect.ini file. This param-
eter represents the directory where the deployment will be located on the WebServer.
If you have set up an IIS-based Web Server, the default location will be the Deploy
directory within the installed directories. For example:
[WebServer]
DeployRoot=C:\inetpub\wwwroot\Citect\deploy

Note: When setting the [WebServer]DeployRoot ini parameter, the path needs to con-
tain "deploy" as the last subfolder name, otherwise the deployment will be unsuc-
cessful. Use a mapped drive instead of a UNC address if deploying to a network
destination from a Windows 2000 system. Do not map a drive directly to the
deployment location, as the path needs to finish with a "deploy" subfolder.

3. Adjust the [WebServer]WebClientCab parameter within the Citect.ini file. This

parameter represents the directory path and client component to use when a deploy-
ment is run, in relation to the installed Client directory. For example:
[webserver]
WebClientCab=700/CitectSCADAWebClient_7_0_176.cab

Note the use of a forward slash in the defined path.

4. Compile your project and then prepare it for deployment. Go to the Citect Explorer
Tools menu and select Web Deployment Preparation or select the following icon on
the Explorer toolbar.

1188
Chapter 41: The Web Client

Your project will now appear as a deployment within the Web Client home page
next time you log in. Each project that is deployed is given a dedicated deploy-
ment name and project path.

Note: You can run the Web Deployment Preparation process automatically when
you compile a project. To do this, go to the Citect Project Editor Tools menu and
choose Options. Select the Prepare for Web Deployment option and click OK. Be
aware, however, that this might increase the time necessary for a project to com-
pile.

5. Determine if any of the I/O, Alarms, Reports or Trends Servers associated with the
project are running behind a firewall. If they are, you need to confirm with the fire-
wall administrator if the CitectSCADA ports have been opened to allow direct access,
or if the firewall is using port forwarding.
If port forwarding is being used, you will need to log in to the Web Client as an
Administrator, select the project, and then the Edit Deployment button:

This will take you to the deployment configuration page.

Note: A project is considered as being directly deployed If deployed from within

CitectSCADA. The project name and the project path of a direct deployment can-
not be changed using 'Edit Deployment'. To redeploy the project Run "Web
Deployment Preparation" again. Other deployment configurations such as IP
address and port number can be changed using the 'Edit Deployment' option.
This is in contrast to deployments that are added from within the Web Server
homepage.

6. Identify each server that port forwarding is being used for by typing the name in the
Server field, using the following format:

1189
Chapter 41: The Web Client

For example:
ClusterOne.AlarmServerOne_AlarmProps

7. Type in the Address and Port for each server, as supplied by the firewall admin-
istrator.

You can add additional servers to the list by selecting the Add New Server icon.
See Also
Displaying a deployment

Displaying a deployment
When you display a deployment, it downloads the necessary Web Client component file
from the Web Server, enabling you to run the associated CitectSCADA project in your
Web browser.

To display a deployment:

1. Locate the deployment you want to display in the list of available deployments.
2. Click the relevant icon (Start Control Client or Start View-only Client) to display the
deployment.

The display options available to you depend on your login permissions. If you select the
View-only Client icon (the one with the gold lock), you can only read the current values
for the CitectSCADA project.
Once the necessary project files and components have been downloaded, the Citect-
SCADA project appears. You can now navigate the project pages as necessary.

Note: An alert message might appear if the current user on the client machine does
not have Windows administrator rights when a new or updated component file (.cab

1190
Chapter 41: The Web Client

file) is downloaded. Verify that the current Windows user has administrator rights if
a new deployment is run or an updated .cab file needs to be downloaded.

Editing an existing deployment

If necessary, you can edit the settings for a deployment. For example, you can change the
name of the deployment or specify a new address for a runtime server.
To edit a deployment's settings, you need to be logged in as an Administrator Client.
To edit an existing deployment

1. Select the deployment you want to edit in the list of available deployments.
2. Click the Edit Deployment icon.

This takes you to the Deployment Configuration page.

Change the fields as necessary. For field descriptions, see Creating a new deploy-
ment.

Note: If you give a deployment a new Name, it is duplicated instead being

updated and overwritten. This allows you to easily copy an existing deployment;
however, to avoid confusion, delete the original deployment with the old name if
it's no longer necessary.

3. Click Apply Changes. (This is important, as you'll lose your changes if you jump
straight back to the home page.)

The Web Server retrieves a fresh set of pages and components for the CitectSCADA
project, which will include any recent changes.
See Also
Updating a deployment to reflect project changes

1191
Chapter 41: The Web Client

Updating a deployment to reflect project changes

If you change a source CitectSCADA project, you need to update its associated deploy-
ment to publish these changes on the Web Server.
Updating a deployment uploads the latest project pages and components to the Web
Server for distribution. This is important as discrepancies might occur between the
project pages and the data being pulled from the runtime servers if the content is not up
to date.
To update a deployment:

1. Verify that the project you want to update has been compiled and processed within
the CitectSCADA by the Web Deployment Preparation tool. See Running the Web
Deployment Preparation tool.
2. Select the deployment you want to update.
3. Click the Edit Deployment icon.

This takes you to the Deployment Configuration page.

4. Click Apply Changes.

The Web Server retrieves a fresh set of pages and components for the CitectSCADA
project, which will include any recent changes.
See Also
Editing an existing deployment
Deleting a deployment

Deleting a deployment
To delete a deployment from a Web Server, you need to log in as an Administrator
Client.
To delete a deployment from the Web Server:

1. Select the deployment you want to delete from the list of available deployments.
2. Click Delete Deployment.

A dialog asks you to confirm that you want to delete the deployment. Click OK.

1192
Chapter 41: The Web Client

Implementing Multiple Language Support

The Web Client deployment configuration interface can be displayed using languages
other than English. The following languages are supported by default:
l French
l German
l Spanish
l Chinese
l Japanese
l Korean
You can also implement other languages by translating the resource message file that
defines the text displayed. In the case of the languages listed above, this file has already
been translated with a version for each language stored in the installed locales folder.
See Also
How default languages are implemented
Using a language different to the current system locale setting
Implementing a non-default language

How default languages are implemented

When you connect a client computer to the Web Server, the script on the web page auto-
matically detects the language code currently defined as the default for the browser. This
code is drawn from the system locale setting defined in Control Panel|Regional Options
on the client machine.
Once the browser's language code has been determined, the script attempts to match it
with those available on the Web Server. If a match is made, the associated language is
automatically used for the Web Client deployment configuration interface. If a match can-
not be made, it defaults to English.
For example, if your Windows Locale setting is Chinese (PRC), the language code set for
your browser would be "zh-cn". This is compared to the current list of language codes on
the Web Server, which by default is the following:

Language Windows Language Code

1193
Chapter 41: The Web Client

English en

French fr

German de

Spanish es

Simplified Chinese zh

Japanese ja

Korean ko

Having found no match in "zh-cn", the script tries to load Simplified Chinese language,
"zh", as a match. The interface will automatically display in Chinese.
See Also
Using a language different to the current system locale setting

Using a language different to the current system locale setting

You can display the content of the Web Client's deployment configuration pages using a
language that's different to the current system locale setting for the computer. To do this,
use a URL query string in the address field of your browser.
To switch to a language other than the default:

1. Decide which language you want to use and determine its associated language code.
(See How default languages are implemented for a list of the codes for the default lan-
guages supported by the Web Server).
For example, if you want to use Chinese, the code necessary would be zh.

Note: If the language you want to use is not one of the supported languages, you
need to create and translate your own message file. See Implementing a non-
default language.

2. Use a URL query to indicate the language you want to use for the Web Client deploy-
ment pages. For example, if the address field on your browser currently reads:
http://localhost/CitectSCADAPowerSCADA Expert

add a "/?lang=" query to the end of the address. For example, Chinese would be:
http://localhost/CitectSCADAPowerSCADA Expert/?lang=zh

1194
Chapter 41: The Web Client

Note: If you use a code that represents a regional variation of one of the default
languages and that specific code cannot be matched, the Web Server can only
implement the available default version of the language. For example, using the
language code for Chinese (PRC), "zh-cn", results in the Simplified Chinese being
used, "zh".

Your Web browser now displays the Web Client's deployment configuration pages using
the appropriate language.
See Also
Implementing a non-default language

Implementing a non-default language

If you need to use a language on the Web Client's deployment configuration interface
other than one of the default languages supported by the Web server, you can implement
your own translation of the messages file that defines the text that appears.
To display a language other than those supported by default:

1. Using a text editor that supports the language you want to edit, open one of the exist-
ing message files located in the Web Server's locales directory; the default path is:
C:\Program Files\Citect\CitectSCADA 7.10Schneider Electric\PowerSCADA Expert
7.30\Web Server\locales

Open a file that includes the language that will be easiest to translate. The lan-
guage code at the start of each file name can be used to identify the language each
file represents; for example, the English language file is called enmsg.xml.
2. Save the file back to the locales directory, using the appropriate language code in the
name.
To name the file correctly, check the list of Windows Language Codes for the
appropriate code. This will allow your translated resource file (XXmsg.xml) to be
automatically loaded when the Web Client home page is launched, provided it
matches the current system locale setting.
For example, to implement Hebrew on the Web Client's configuration pages, you
would name your file hemsg.xml. To use the Taiwanese variation of Chinese, you
would call the file zh-twmsg.xml.
3. Now change the file content. Firstly, set the correct encoding format.
The encoding format is defined in the top line of the file, which appears as fol-
lows:
<?xml version="1.0" encoding="iso-8859-1" ?>

1195
Chapter 41: The Web Client

If the language uses English characters, the format you would use is ANSI, which
is defined as "iso-8859-1" (see example above).
If the language uses non-English characters, you would use Unicode, which is
defined as "UTF-8" (see example below).
<?xml version="1.0" encoding="UTF-8" ?>

4. Now translate the text that appears on the Web Client interface.
The content that needs to be translated is divided across two sections within the
file: "labels" and "messages". The labels section includes the content used to
describe and identify the elements of the interface; the messages section includes
the notifications that appear in the system messages panel.
To translate these sections, alter the text between the enclosing XML tags. Do not
alter the tags themselves. The XML tags define where each label is used.

Note: Make sure you maintain any "%" characters, as these are used to insert sys-
tem information.

For example, the English file:

<span id="TITLE">CitectSCADA Web Client Deployment</span>
<span id="SYSMSG">System Messages</span>
<span id="DEP">Deployment</span>
<span id="DESC">Description</span>
<span id="ACTION">Action</span>

<sysmsg id="DELOK">% deleted.</sysmsg>
<sysmsg id="DELCAN">% will NOT be deleted.</sysmsg>
<sysmsg id="DEPNULL">You can't % an empty deployment.</sysmsg>

...
would appear as follows in Spanish:

<span id="TITLE">Despliegue del Cliente Web CitectSCADA</span>
<span id="SYSMSG">Mensajes del Sistema</span>
<span id="DEP">Despliegue</span>
<span id="DESC">Descripción</span>
<span id="ACTION">Acción</span>

<sysmsg id="DELOK">% eliminado.</sysmsg>
<sysmsg id="DELCAN">% NO será eliminado.</sysmsg>
<sysmsg id="DEPNULL">No puede % un despliegue vacío.</sysmsg>

Once you have translated the file and saved it with the appropriate name to the locales
folder, your Web Server will be able to support the language.

Note: When you save your file, make sure the text editor you used saves the file in

1196
Chapter 41: The Web Client

the appropriate format depending on the language coding used, i.e. ANSI or Unicode
(UTF-8) . See step 3 above.

Web Client Upgrade Considerations

If you have upgraded your Web Client from an earlier version to version 7.x, read the fol-
lowing sections about installation and how to use the upgraded Web Client tool with
existing deployments.
Installation
If you intend to use the Web client on Windows 2000 or Windows 2003 Server, you need
to first install the latest Windows Installer module on your machine. This is available
via the Windows Update feature in Windows 2000 or Windows 2003 Server.
Upgrading to the new version of the Web Client adds a new folder named 700 to the
client folder of the WebServer folder.

If you're planning on installing Web Client version 7.x but want to view legacy (that is,
pre-version 7.0) deployments, before installing the new version, back up your old deploy-
ments to a durable storage medium and place them in a secure location. Then, after
installing the new version, copy your old deployment(s) back to the deploy folder (see
above), and the legacy .cab file(s) to the corresponding folder in the client folder; this
will make your old deployments available for use.
Creating new deployments
When creating a new deployment, be aware that the .cab file you use (Client Control) for
the deployment needs to correspond to the correct version of the project you want to
access or the deployment will not succeed. For example, to create a deployment based on
a version 7.0 CitectSCADA project, from the Client Control menu choose
700/filename.cab; to create a deployment based on a version 7.30 CitectSCADA project,
from the Client Control menu choose 730/filename.cab.
Deploying a project from within CitectSCADA
If you are deploying a project from within CitectSCADA, edit the [webserver] section in
your citect.ini file to specify the correct cab file for the version of the Web Client you're
using. For example, for a version 7.0 deployment, specify a .cab file located in the 700
folder; for a 7.10 version, specify the 710 folder.

1197
Chapter 41: The Web Client

Frequently Asked Questions

This section answers frequently asked questions concerning the Web Client. One section
is dedicated to considerations pertaining to Windows 2003 Server, and the other to gen-
eral considerations:
l Windows 2003 Server-related considerations
l General considerations

Windows 2003 Server-related considerations

This section describes considerations relating to the Windows 2003 server product.
Q. My Web Client Deployment Page displays incorrectly on Windows 2003 Server:
Show Server Details is missing and the icons for Start client, Delete Deployment, and
Edit Deployment are also missing. How do I fix this?
A: There are two possible answers:
l When IIS 6.0 is installed, it defaults to a "locked" mode, meaning it can serve up only
static content. ASP, ASP.NET, and FrontPage Server Extensions are disabled and
needs to be explicitly and separately enabled. The CitectSCADA Web Server needs
ASP enabled on the IIS.
To enable ASP for IIS6 on Windows 2003 Server:

1. Choose Start|Control Panel, then double-click Add or Remove Programs.

2. In the Add or Remove Programs dialog box, click Add/Remove Windows Com-
ponents.
3. In the Windows Components Wizard dialog box, select ApplicationServer, and then
click Details.
4. In the Application Server dialog box, select Internet Information Services(IIS) and
click Details.
5. In the Internet Information Services (IIS) dialog box, select World Wide Web Service
and click Details.
6. In the World Wide Web Service dialog box, select the Active Server Page option.
7. On Windows 2003 Server, the default setting is to have the web locations except local-
host as an untrusted site. Consequently you need to modify your browser's security
settings.
To update your Trusted Sites settings for Windows 2003 Server:

1. Choose Tools|Internet Options.

2. Click the Security tab and then Trusted Sites|Sites.

1198
Chapter 41: The Web Client

3. In Add this Web site to the zone field, add the web server's IP address as follows:
http://<ip address>

Note: Whenever Web Client pages do not load, display, or perform correctly, verify
your security settings even if you are not running Windows 2003 Server.

Q: When I try to start the Web Client, I get the alert message "Starting Citect Web
Client Failed: Can not initialize Citect system", and then the Web Client browser win-
dow stops responding to my inputs. How do I correct this?
A: First check that you haven't accidentally deleted the #DisplayClient folder from the
installed Web Server directory, as this will cause this error. By default, this directory is
located at:

C:\Inetpub\wwwroot\Citect\deploy\#displayclient

If this is not the case, this is due to an incorrect MIME setting: the initialization files are
not being recognized in Windows 2003 as registered file extensions. To correct this, add
the correct MIME type extension by doing the following:
1. Run the IIS manager and go to Web Sites|Default Web Site|Citect|deploy.
2. Choose Properties from the folder's right-click menu.
3. Go to HTTP Headers|MIME types.
4. In the Extension field, enter ".*".
5. In the MIME type field, enter "all".
6. Restart your Web server and client.

General considerations
This section describes general considerations relating to the Web Client product.
Q. When I try to run a deployment in Internet Explorer, I get the following error: "Prob-
lems with this page might prevent it from being displayed properly...". What is the
cause?
A. When you first try to run a deployment, Citect will attempt to download the client
component (the .cab file) associated with that deployment if it is not already present on
the local machine. If this download of the client component is triggered, and the cur-
rently signed in user does not have Windows local administrative rights on the client,
then this alert message occurs.

1199
Chapter 41: The Web Client

The solution is to verify that the person who runs a deployment for the first time is a
Windows local administrator on the client machine. Once the components have been
downloaded, any user will be able to access and run the deployment. The alert message
will not reoccur unless the .cab file is updated.
Q. I deployed a project from within CitectSCADA using the appropriate Citect.ini
[WebServer] parameters, but the project does not appear in the list of deployments on
the Web Server. A dialog informed me that the deployment was successful. What has
happened?
A. This situation can occur if you make an error with the syntax for the [WebServer]
DeployRoot parameter. If, for example, you use a curly bracket instead of a square bracket,
(for example, "[WebServer}DeployRoot"), the compiler cannot read the parameter and
deployment files are sent to the CitectSCADA project directory instead:
[User]\<Project Name>

The deployment is flagged as successful, but it cannot be located by the Web Server.
If you have deployed a project but it does not appear in the Web Server's list, check the
location above for a subfolder called "Web Deploy". If such a folder exists, correct the syn-
tax used in your Citect.ini file.
Q. I deleted a user from the list of users configured for access to the Web Server, but
they can still log in. How do I deny them access?
A. Sometimes a user can connect to the Web Server even after their user account has
been deleted. This can occur when the operating system does not immediately report the
user deletion to the web server. The period between the deletion of a user and the restric-
tion of access can be about a half an hour.
The solution is to deny access to the user before deleting them. That way, they cannot
gain access. See the topic "Deleting a user account" in the Web Client section of the Citect-
SCADA Installation and Configuration Guide.
Q. When I try to run the Web Client component for the first time, I get a "System Set-
tings Change" message instructing me to restart my computer. What do I do?
A. This message appears on computers that contain old versions of some system files
necessary by the Web Client Control. If these files are used by another application during
installation, this System Settings Change message appears. Click OK to restart your
machine to allow the newer versions of the necessary files to be installed during system
reboot. The alert message will not reoccur unless another application reloads the old
files.
Q. One of the ActiveX Object's included in my project cannot locate its associated data
source. Where is it?

1200
Chapter 41: The Web Client

A. If an ActiveX object has an associated data source, you need to verify the data source
can be located by the computer hosting the Web Client. See the topic Managing asso-
ciated data sources for details.
Q. Why does a pop-up saying "Client control (CitectSCADAWebClient_7_0_xxx.cab) is
not in the option list!" when I try to edit my deployment from the Web Client Deploy-
ment Configuration Page?
There are two possible reasons for this dialog:
1. You might have set the [Web Server] parameter WebClientControl incorrectly. The
Web page might not recognize the name or version of the .cab file. also check that
you've used a forward slash in front of the cab file name, as this is necessary for the
Web Server to locate the correct file.
2. A user might have deleted the necessary .cab file from C:Program Files\C-
itect\CitectSCADA 7.10\WebServer\client\700C:\Program Files\Schneider Elec-
tric\PowerSCADA Expert 7.30\WebServer\client\700(or the specified location). Therefore,
the Web page cannot find it.
Q. The Process Analyst interface normally displays in a foreign language as I trans-
lated the language resource DLL, but it displays in English on the Web Client plat-
form. How do I correct this?
A. A Process Analyst control running inside a CitectSCADA Web Client supports run-
time language switching, but you need to configure which languages the Web Client will
download to the client machine.
To configure the languages to download:

1. Create a zip file in the C:\Program Files\Citect\CitectSCADA

7.30\WebServer\client\730C:\Program Files\Schneider Electric\PowerSCADA Expert 7.3-
0\WebServer\client\730 folder called bin.zip.
2. Add to the zip file the language resource DLL files that you want the client to down-
load and use. (You can find these files in your \Program Files\Common
Files\CitectSchneider Electric Shared\PowerSCADA Expert folder.)

Note: The bin.zip file and its contents are not version-checked. This means you
need to manually remove the bin.zip from the Web Client machines if your server
contains a more recent bin.zip file. To do this:

1. Find the installation directory of the Analyst.dll file on your Web Client
machines and look for a file called bin.zip in this directory.
2. Delete this file.
3. Reconnect to the Web server to download the latest bin.zip file.
Q. I have keyboard shortcuts configured in my CitectSCADA project, but they do not
work properly when the project is deployed in the Web Client. What's wrong?

1201
Chapter 41: The Web Client

A. Keyboard shortcuts configured for Internet Explorer (IE) take precedence over key-
board shortcuts configured within your CitectSCADA projects. For example, the Example
project has F11 assigned to call up Help on a selected animation point on a graphics
page. If the project is run as a Web Client deployment, F11 will toggle the view to full
screen, as is the case normally with IE.
This is a limitation of using Internet Explorer to host CitectSCADA projects. The easiest
solution is to return to the CitectSCADA configuration environment and assign your
shortcuts so that no clashes occur. See the Internet Explorer Help for details of pre-
configured keyboard shortcuts.
Q. I can't print from the Web Client. Why not?
A. You can print from the Web Client, but not by using your browser's File | Print com-
mand. Instead, in your CitectSCADA project, create a Print control that uses the Cicode
WinPrint() function to print the page you want.

Q. The new page that I added to my CitectSCADA project does not appear in the Page
Select list or the default menu page in the Web Client. How can I correct this?
A: If the page you added to your CitectSCADA project does not appear in Web Client,
you can manually type in the page name in the Page Select list to view this new page. In
this version of the Web Client, the new page is not added to the default menu page.
Q. The Web Client Deployment Page displays incorrectly on Windows 2000 Advanced
Server. 'Show Server Details' is missing, and the icons for Start client, Delete Deploy-
ment and Edit Deployment are also missing. What is wrong?
A. This appears to be caused by Windows Automatic Update installing several com-
ponents at the same time after a fresh install of the operating system. Even though Inter-
net Explorer might have been upgraded to the latest version (for example, 6.0.2800.1106)
it might still behave as a version 5 browser; for example, it offers limited support for
"iframes". If you call up About Internet Explorer from the Help menu, and a Version 5-
style dialog appears with a version 6 release number, then your computer is affected in
this way.
A complete uninstall/reinstall of Internet Explorer will correct the problem.
Q. When I launch the web server, the login form prompts me for a user name and
password. When I enter the valid local administrator user name and password the
HTTP 500 Internal server error message pops up saying that the page cannot be dis-
played. What is wrong?
A. The problem is caused by the fact that the computer was in an invalid state in the
way that it lost its trust relationship with the domain controller. Removing the computer
and re-adding it to the domain will correct the problem. To do so perform the following
steps:

1202
Chapter 41: The Web Client

1. Open the Computer properties dialog. (WinKey + Pause/Break).

2. On the Computer Name tab click Change Enable workgroup and enter any string,
such as "Test".
3. Click Ok and enter the credentials, Apply (no need to restart at this point) Click
Change again, Enable domain and enter "Citect.com".
4. Click Ok, enter the credentials, click OK to reboot.
Q. When I start the control client from a web client the Internet Explorer information
bar displays telling me that it has blocked the running of scripts or ActiveX controls.
A. One of the reasons for this issue is Internet Explorer security preventing the download
of any ActiveX controls. To resolve this issue, add the web site to the list of trusted sites
under Tools -> Internet Options -> Security

1203
Chapter 41: The Web Client

1204
Chapter 42: Windows Language Codes

code Windows locale setting code Windows locale setting

af Afrikaans hu Hungarian

sq Albanian is Icelandic

ar-sa Arabic (Saudi Arabia) id Indonesian

ar-iq Arabic (Iraq) it Italian (Standard)

ar-eg Arabic (Egypt) it-ch Italian (Switzerland)

ar-ly Arabic (Libya) ja Japanese

ar-dz Arabic (Algeria) ko Korean

ar- Arabic (Morocco) ko Korean (Johab)

ar-tn Arabic (Tunisia) lv Latvian

ar- Arabic (Oman) lt Lithuanian

ar-ye Arabic (Yemen) mk FYRO Macedonian

ar-sy Arabic (Syria) ms Malaysian

ar-jo Arabic (Jordan) mt Maltese

ar-lb Arabic (Lebanon) no Norwegian (Bokmal)

ar- Arabic (Kuwait) no Norwegian (Nynorsk)

ar-ae Arabic (U.A.E.) pl Polish

ar- Arabic (Bahrain) pt-br Portuguese (Brazil)

1205
Chapter 42: Windows Language Codes

code Windows locale setting code Windows locale setting

ar-qa Arabic (Qatar) pt Portuguese (Portugal)

eu Basque rm Rhaeto-Romanic

bg Bulgarian ro Romanian

be Belarusian ro- Romanian (Moldavia)

ca Catalan ru Russian

zh- Chinese (Taiwan) sz Sami (Lappish)

zh- Chinese (PRC) sr Serbian (Cyrillic)

zh- Chinese (Hong Kong SAR) sr Serbian (Latin)

zh- Chinese (Singapore) sk Slovak

hr Croatian sl Slovenian

cs Czech sb Sorbian

da Danish es Spanish (Traditional)

nl Dutch (Standard) es- Spanish (Mexico)

nl-be Dutch (Belgium) es-gt Spanish (Guatemala)

en English es-cr Spanish (Costa Rica)

en- English (United States) es-pa Spanish (Panama)

en- English (United Kingdom) es-do Spanish (Dominican Republic)

en- English (Australian) es-ve Spanish (Venezuela)

1206
Chapter 42: Windows Language Codes

code Windows locale setting code Windows locale setting

en- English (Canada) es-co Spanish (Colombia)

en- English (New Zealand) es-pe Spanish (Peru)

en-ie English (Ireland) es-ar Spanish (Argentina)

en- English (South Africa) es-ec Spanish (Ecuador)

en- English (Jamaica) es-cl Spanish (Chile)

en English (Caribbean) es-uy Spanish (Uruguay)

en- English (Belize) es-bo Spanish (Bolivia)

en-tt English (Trinidad) es-sv Spanish (El Salvador)

et Estonian es- Spanish (Honduras)

fo Faeroese es-ni Spanish (Nicaragua)

fa Farsi es-pr Spanish (Puerto Rico)

fi Finnish sx Sutu

fr French (Standard) sv Swedish

fr-be French (Belgium) sv-fi Swedish (Finland)

fr-ca French (Canada) th Thai

fr-ch French (Switzerland) ts Tsonga

fr-lu French (Luxembourg) tn Tswana

gd Gaelic (Scotland) tr Turkish

gd-ie Gaelic (Ireland) uk Ukrainian

1207
Chapter 42: Windows Language Codes

code Windows locale setting code Windows locale setting

de German (Standard) ur Urdu

de- German (Switzerland) vg Valley Girl

de-at German (Austria) ve Venda

de-lu German (Luxembourg) vi Vietnamese

de-li German (Liechtenstein) xh Xhosa

el Greek ji Yiddish

he Hebrew zu Zulu

hi Hindi

Using the StruxureWare Templates

This section contains information about the StruxureWare templates.

Introducing StruxureWare Templates

1208
Chapter 43: Introducing StruxureWare Templates
The StruxureWare Template Project is a preconfigured project that includes a set of tem-
plates intended for use in StruxureWare designed systems.

Note: These templates are not designed for direct upgrade from existing tab style tem-
plates. If you want to use these templates you will need to manipulate the page
objects so that the objects are rendered correctly on screen.

When a new CitectSCADA project is created to use SxW_Style_1 as the default template
style, the StruxureWare Template (SxW_Style_Include) project is automatically incor-
porated as an included project. This means the project's templates are available for
implementation when creating your graphics pages in Graphics Builder.
As well as including a standard graphics page template for creating plant mimics, the
project also includes predefined alarm templates, a set of file templates for displaying
text, Rich Text Format and HTML files. They have identical page navigation, alarm
banners and menus for consistent "look and feel", and usability across an entire project.

Note: Do not modify the StruxureWare Template project for use as a runtime project.
It will not compile successfully, and be set aside for use as a template for new
projects. CitectSCADA upgrades install a new version of the StruxureWare Template
project, which will overwrite changes you make to the project when this happens.

The StruxureWare Interface

1209
Chapter 43: Introducing StruxureWare Templates

The StruxureWare template is divided into 3 parts:

1. The header
2. The right panel
3. The main window

Note: The Alarm templates include a left-hand panel that enables users to filter
using the Equipment hierarchy.

The right panel contains:

1 Option to switch between navigation tree representing your Menu Configuration

or Equipment hierarchy. Click on the Menu option to view common menu con-
figuration for all pages in your project. On selecting a page it will open in the
main window. The icon dimensions for optimal display in the menu and equip-
ment tree are 16x16.
To view the Equipment tree (lists all equipment defined in your project) click on
the Equipment option.

2 Click on the plus and minus signs next to the nodes to expand and collapse items.

1212
Chapter 43: Introducing StruxureWare Templates

User configurable logo. To display your logo in the allocated space, define your
logo as bitmap symbol in your project. The dimension of the bitmap should be
3
230 x 50. Assign the name of your symbol (in format of library.symbol) to project
/ INI parameter [Page]Logo.

The Main Window

The main window contains the open pages and alarm views that have been selected
from the right panel.

1 History button. Move back through the tabs that have been opened.

2 Page specific navigation commands.

• Up navigation command changes the display to the “parent” page. You can
assign a parent page by setting an environment variable in Graphics Builder. To
do so, open the page properties dialog of a page (via File | Properties menu com-
mand), click the Environment tab, and add a variable called “ParentPage”.
Assign the name of the parent page to the value of this variable
• Left / Right navigation commands display the previous / next page relative to
the current page. To configure previous / next page, open the page properties
dialog in Graphics Builder (via File | Properties menu command), click the Gen-
eral tab, and set page name to the Previous page / Next page fields.

3 Forward and back navigation command buttons and the Display list button. Use
to scroll and display the list of opened pages.

4 Tabs of opened pages. Allows you to access and navigate between pages that
have been selected from the right-panel or launched from other pages.

1213
Chapter 43: Introducing StruxureWare Templates

Page specific menu commands. Menu configuration defined specified for this
5 page appears here. (Menu configuration that is common to all pages appears on
the navigation tree on the right panel).

Normal Standard graphics page. See Normal Page Template.

Blank For users who want to create their pages from scratch. See Blank Page Tem-
plate.

Data For users who want to display a table of data retrieved from built-in data browse
Browse functions on a page. See Data Browse Page Template.

Alarm Includes Alarm, Disabled, Hardware, Sequence of events and Summary for
displaying different types of alarm list. See Alarm Page Templates.

Proc- Includes SinglePA, DoublePA, PopPA. See Process Analyst Page Templates.
ess
Analyst

SPC Includes SpcPareto, SpcCpk, SpcXRSChart, EventSPCXRS, MeanMeanChart,

RangeChart and StandardChart. See SPC Page Templates.

File Includes File, File_RTF and File_HTML for displaying a plain text file, rich text
format file and HTML file / URL respectively. See File Page Templates.

See Also
Creating a New Project
Creating Pages

1215
Chapter 44: Using StruxureWare Pages and Templates

Normal Page Template

A template designed for creating user-necessary content and plant mimics. This page
contains the navigation and alarm panels featured on StruxureWare templates. If you
are creating a project based on the StruxureWare style templates, use this template for
your standard graphics pages.
The Normal template creates a page in display format to be shown with a title bar. Two
wide-screen sizes are available: HD768 (1388x768,16:9) and HD1080 (1920x1080,16:9).
See Also
Creating SxW Style Pages
Securing the Window Titlebar

Blank Page Template

The blank template is included for users who want to create their pages from scratch.
There are no differences between the StruxureWare blank template and the template in
the include project.
See Also
Creating Pages

Data Browse Page Template

The data browse template is included for users who want to create a page that displays
a table of data retrieved from built-in data browse functions. The template includes the
Equipment tree view on the left side of the main window. This is used to filter the dis-
play list based on the selected equipment node .
When using this template to create a new page within your project, configure the Data
Browse pop up form. When configured the new page will display the appropriate data
session at runtime.

Field Description

Equipment The symbol library for displaying equipment symbol for each item in the equip-
Symbol ment tree. The symbol is displayed based on the type of the equipment. It
Library should have the same name as the equipment type assigned to an equipment
(Optional) record. If not specified, it defaults to a symbol library named “Equipment”.

Equipment The default symbol to be displayed next to the item in the equipment tree if sym-
Default bol corresponding to the equipment type of the item cannot be found from the
Symbol supplied Equipment Symbol Library. The symbol should be specified in format

1216
Chapter 44: Using StruxureWare Pages and Templates

(Optional) of <library name>.<symbol name>

Browse The type of project configuration to be browsed and displayed, including:

Type AccumBrowse – for listing accumulators
AlmBrowse – for listing alarm tags
AlmSummary – for listing alarm summary
EquipBrowse - for listing equipment
ServerBrowse – for listing servers
TagBrowse – for listing variable tags
TrnBrowse – for listing trend tags

Clusters A comma delimited string specifying only items from a subset of clusters to be
(Optional) included in the display. If not specified, items from all clusters will be included.

Filter A filter expression specifying the records to return during the browse If not
(Optional) specified, all records will be returned. Please see the browse open Cicode func-
tion of the selected browse type for the details of filter expression supported.

Fields A comma delimited string specifying the fields (columns) to be returned during
(Optional) the browse. If it is not specified, all fields of the selected browse type will be dis-
played: Tag, Tag Item, Value, Comment, Cluster, Equipment, Item, Type, IODev,
Addr, Arr_Size, Eng_Zero,Eng_Full, Eng_Units,Format, Deadband, Raw_Zero,
Raw_Full, Scaled_Type, Ovr_Mode, Ctrl_Mode, Override, Valid, Status, Field,
Num_Subs.

Sort By A comma delimited string specifying the order of sorting preferences. This is
(Optional) only applicable to TagBrowse. Please see the Sort parameter of the built-in
Cicode function TagBrowseOpen for details.

View Name A name to represent a view setting about the placement and width of the col-
(Optional) umns displayed on the browse table. The view name works with the Save view
and Restored saved view options at runtime. You can assign a unique view on
different data browse pages or share the same view among multiple pages.
When user selects the Save view command from the Action tab, the current col-
umn settings will be saved under the view name. Once a view is saved, when
user re-enters the page, previous saved view settings will be retrieved auto-
matically. The saved view can also be restored on demand by selecting the
Restored saved view from the Action tab. User can reset (forget) the view to the
default as how it was pre-configured by selecting the Restore view to default
command under the Action tab.
For system engineers, the information associated with a view name is saved
under INI parameters:
[BrowseTableView] <BrowseType>.<ViewName>.Fields
<BrowseType>.<ViewName>.ColWidths
in comma delimited format. You can pre-configure these parameters in your
project as the defaults.

Privilege Only applicable to Browse Type of "TagBrowse", this specifies the privilege
(Optional) required by the logged on user to change the values / operating mode of var-
iable tags displayed on the table. If no privilege is defined, no modification will
be allowed.

Use the equipment tree to filter the data browse table at runtime. Items belonging to
selected parent and child branches will be displayed with the exception of 'Server-
Browse' which is not associated with equipment.
Refer to Interactive Data Browse List for list display options available at runtime.

1217
Chapter 44: Using StruxureWare Pages and Templates

Interactive Data Browse List

The Data Browse template features an interactive list that supports the following func-
tionality:
Adjustable Columns
The user can adjust the columns displayed on the data browse list. Options include:
l Reposition a column by drag-and-drop its column heading to the new position.
l Adjust the size of a column by dragging the column separator that appears at the
right edge of a column heading.
Selection of data rows
The user can select single or multiple rows on the display list so that the same operation
can be applied to multiple selected rows in one go. Row selection works as follows:
l To select a single data browse row: Left-click a row that is not already selected to
select it.
l To select a continuous range of data browse rows: Select a single row to mark the
start of the selection. Then hold the SHIFT key and left-click another row to extend the
selection. Alternatively, you can select rows by dragging the mouse cursor from the
starting to the ending row. Once rows are selected, you can extend its range by SHIFT
left-clicking another row of alarm.
l To select disjointed rows, hold the CTRL key while selecting a row.
l To deselect alarm(s): Left-click any alarm within a selection range to deselect the
whole range. Only the row that you have clicked will remain selected. Click the
selected row again to deselect it.
Context Menu
If the page is set to display tag browse data, right-click on any row will bring up the con-
text menu for operations. Options available in the context menu will vary depending on
whether single or multiple items are selected:
The commands will only work if:
l Tag field is included in the table display
l For system with multiple clusters, the cluster field will also need to be included
The items available on the menu are selection sensitive depending on whether single or
multiple items are selected at the time. The following options are available only when
single row is selected:
l Set Value

1218
Chapter 44: Using StruxureWare Pages and Templates

Note: To disable the Set Value command leave the privilege field empty. See Data
Browse Template topic for more information.

The following options are available:

l Set Override Mode
l Set Control Mode

Alarm Page Templates

Alarm page templates are included for the following types of alarm displays:
l Active Alarm Page: Used to create a page displaying active alarms that are unac-
knowledged or acknowledged and still in alarm state. The template has the equip-
ment tree-view panel displayed on the left hand side of the page for filtering of the
display list. The tree-view will display a hierarchy of equipment available to the cur-
rently logged on user. The template also includes vertical and horizontal scroll bars
to allow users to view columns and rows off screen. To create a default active alarm
page for your project, create a new page based on the alarm template. By default, the
name of the page is expected to be "Alarm". However, you can change the name of
the page by adjusting the setting for the INI parameter [Page]AlarmPage.
l Disabled Alarm Page : Used to create a page displaying alarms that are presently dis-
abled in the system. The alarms will appear on this page when they have been dis-
abled from the normal alarm system due to a maintenance shutdown, nuisance
tripping etc. The template has the equipment tree-view panel displayed on the left
hand side of the page for filtering of the display list. The tree-view will display a hier-
archy of equipment available to the currently logged on user. To create a default dis-
abled alarm page for your project, create a new page based on the disabled template.
By default, the name of the page is expected to be "Disabled". However, you can
change the name of the page by adjusting the setting for the INI parameter [Page]Dis-
abledPage.
l Sequence of Events Page: Used to create a page displaying a snapshot of every state
transition of an alarm instance that have occurred. The template has the equipment
tree-view panel displayed on the left hand side of the page for filtering of the display
list. When configured the tree-view will display a hierarchy of equipment available to
the currently logged on user. To create a default SOE alarm page for your project,
create a new page based on the soe template. By default, the name of the page is
expected to be "SOE". However, you can change the name of the page by adjusting
the setting for the INI parameter. [Page]SOEPage. Unlike the active, hardware, and dis-
abled alarm pages, that are refreshed automatically at runtime to display real time
data, the SOE and summary pages display a snapshot of events that have occurred,

1219
Chapter 44: Using StruxureWare Pages and Templates

therefore is not updated automatically. To retrieve the latest events you can manually
refresh the page.
l Alarm Summary Page : Used to create a page displaying a historical log of alarms
that have occurred. This page can be used for troubleshooting purposes.The template
has the equipment tree-view panel displayed on the left hand side of the page for fil-
tering of the display list. When configured the tree-view will display a hierarchy of
equipment available to the currently logged on user. To create a default summary
alarm page for your project, create a new page based on the summary template. By
default, the name of the page is expected to be "Summary". However, you can change
the name of the page by adjusting the setting for the INI parameter [Page]Sum-
maryPage.

SUMMARY DATA NOT AUTOMATICALLY REFRESHED

Summary data is not automatically refreshed at runtime. Manually refresh the Summary
and SOE page before using its data for analysis of plant state.

Failure to follow these instructions can result in injury or equipment damage.

The alarm templates display alarm lists using a "no draw" mode. The display of alarm
fields is handled by a new set of template specific Cicode functions and genies to control
each of the alarm fields' position and size. The alarm list is installed with a callback
event function to redraw the alarm list upon data change. The "no draw" mode and data
change callback event are supported by a modified form of the existing Cicode function
AlarmDsp().

Page Specific Menus

If your project is created using StruxureWare starter project, a set of menus are already
pre-configured for each of the alarm pages. When the user displays an alarm page, its
page specific menu items will be automatically displayed. Options available on the page
specific menu vary according to the type of Alarm page.

Name Description

Acknowledge Acknowledge all alarms on the current page. Available on Active Alarm page.
Page

Disable Page Disable all alarms on the current page. Available on Active Alarm page.

Enable Page Enables all alarms on Page. Available on Disabled Alarm Page.

Filter... Opens the alarm filter form. Filter form varies according to alarm page open.

1220
Chapter 44: Using StruxureWare Pages and Templates

Name Description

Reset Filter Clears the effect of the filter criteria specified through the filter form.

Auto size col- Auto size column widths in the alarm display list.
umns

Add col- Add column to the alarm display list.

umn…

Save View Save the column settings of the alarm display.The same settings will then be
used for this alarm page.

Restore Restore the column settings according to the alarm format set in parameter
Saved View [Format]<FormatName>.

Reset view to Reset the column settings of alarm display to default. Define your own default
default by setting parameters[Format]<FormatName> as project parameters.

Print/Export Print or Export the current page

Interactive Alarm List

The alarm page templates feature an interactive alarm list that supports the following
functionality:
Adjustable Columns
The user can adjust the columns displayed on the alarm list. Options include:
l Reposition a column by drag-and-drop its column heading to the new position.
l Delete a column by drag-and-drop its column heading (vertically) beyond the column
heading row.
l Insert or delete a column via a pop-up menu by right-clicking a column heading
l Adjust the size of a column by dragging the column separator that appears at the
right edge of a column heading.
Dockable Equipment tree-view
l Adjust the width of the equipment tree-view by dragging the column separator that
appears at the right edge of the column.When selected the column separator will
change from blue to gray.
l To hide the equipment tree-view click the arrow icon on the column separator. On
clicking it the equipment tree-view will collapse and be hidden from view. Click the
arrow icon at the edge of the page to show the equipment tree-view on screen.
Selection of Alarms

1221
Chapter 44: Using StruxureWare Pages and Templates

The user can select single or multiple alarms on the alarm list so that the same oper-
ation can be applied to multiple selected alarms in one go. If some of the selected alarms
are off-screen, before the required operation is completed, a message dialog will popup,
reminding the user that some of the selected records are not viewable. On clicking Con-
tinue or the Enter key the selected records on and off the screen will be acted on. On click-
ing Cancel or the ESC key the command is canceled. If the selected records are viewable
on-screen the message dialog will not open.
Alarm selection works as follows:
l To select a single alarm: Left-click an alarm that is not already selected to select it.
l To select a continuous range of alarms: Select a single alarm to mark the start of the
selection. Then hold the SHIFT key and left-click another alarm to extend the selec-
tion. Alternatively, you can select rows by dragging the mouse cursor from the start-
ing to the ending row. Once rows are selected, you can extend the range of the
selection by SHIFT left-clicking another row of alarm.
l To select disjointed rows, hold the CTRL key while selecting a row.
l To deselect alarm(s): Left-click any alarm within a selection range to deselect the
whole range. Only the row that you have clicked will remain selected. Click the
selected row again to deselect it.
Sorting the Alarm List
Users can sort the alarm list display using most fields except for 'State' and 'Type'. To
sort click on the header of the relevant column.
The default order of alarms is dependent on the [Alarm]SummarySortMode parameter
and the type of alarm page.
Refer to the topic Default Sort Order for more information.
Context Menu
Right-click on any alarm row to bring up the context menu for alarm operations.Options
available in the context menu will vary depending on whether single or multiple items
are selected. If you right-click on an alarm that is not already selected, this will select it.
Subsequent commands (selected from the context menu) will then only operate on this
single alarm. On the other hand, if you right-click on any alarm within a selection range,
this will not change the selection. Subsequent commands selected will operate on each
alarm within the selection range. Several operation options are available in the context
menu:
l Acknowledge: acknowledges selected alarms. This option is restricted by the privilege
set by the parameter [Privilege]AckAlarms. This is not available on the Alarm Sum-
mary page.
l Disable: disables selected alarms. This option is restricted by the privilege set by the
parameter [Privilege]DisableAlarms. It is not available on the Disabled Alarms page.

1222
Chapter 44: Using StruxureWare Pages and Templates

l Enable: enables selected alarms. This option is restricted by the privilege set by the
parameter [Privilege]DisableAlarms. It is not available on the Active Alarms page.
l Comment: Add a comment to an event. This option is only available when a single
row is selected. This option is restricted by the privilege set by the parameter [Priv-
ilege]AckAlarms. This option is available to Alarm Summary and SOE pages only.
l Information: displays the detailed information of a single alarm.
l Help: displays the Help page (which is set in the Help field of the alarm record in
Project Editor) of a single alarm.

Note: The Hardware Alarms template only allows a single alarm to be selected. Its
context menu has only the Acknowledge option which is also restricted by the priv-
ilege set by parameter [Privilege]AckAlarms.

Filtering Alarms using the Equipment tree-view

You can filter the alarm display list to show alarms belonging to selected parent and
child equipment branches. If no equipment is selected in the tree-view then all alarms
are displayed.
To select equipment, check the box to the left of the relevant branches. If you select equip-
ment with child branches, then the child equipment will be automatically selected, with
their check boxes grayed out.

Note: If the parent equipment branch is checked, child equipment cannot be dese-
lected.

If the parent is not selected you can change the checked states of the child equipment.
Next to each item in the tree, an alarm count is displayed. The count includes the total
number of alarms belonging to the equipment and its child hierarchy. The type of
alarms that are counted vary according to the type of alarms that are displayed on the
list. For example, on the active alarms page, the count represents the active alarms asso-
ciated to that equipment, while on the disabled alarms page, the count represents the dis-
abled alarms associated to that equipment. Other points to consider with the equipment
count include:
1. The count on the tree node represents the total number of alarms that are associated
with that equipment hierarchy branch.
2. For alarms that are not associated to equipment, the count is not available due to the
nature of the equipment tree view.
3. The counts are not affected by the filter applied to the alarm list.

1223
Chapter 44: Using StruxureWare Pages and Templates

4. Due to point 2 and 3, the total sum of the counts from the equipment tree does not
equal to the alarm count on the alarm banner, and they never mean to be com-
parable. The alarm count on the banner represents the total number of (unfiltered)
unacknowledged alarms in the system (subjected to the viewable areas of the cur-
rently logged on user).

Process Analyst Page Templates

The Process Analyst template is the default template for you to create trend pages. The
StruxureWare Style project includes templates for the three following types of trend dis-
play:
l SinglePA - A template that displays a single Process Analyst chart on the page. To
create a default trend page for your project, please create a new page based on this
template and name it "ProcessAnalyst". You can change the default page name by set-
ting parameter [Page]ProcessAnalystPage
l DoublePA - A template that displays two Process Analyst charts on the page.
l PopPA - A template that displays a single Process Analyst chart on the page. The
size of the page is reduced to make it suitable for pop-up pages. To create a default
trend pop-up page for your project, please create a new page based on this template
and name it "!ProcessAnalystPopup". You can change the default page name by set-
ting parameter [Page]ProcessAnalystPopupPage
The functionality of traditional trends, double trends, and popup trends are largely incor-
porated into the Process Analyst on the new templates.
There is a key difference between the new PA templates and the existing trend templates,
which is pen assignment. The trend templates can get pens assigned to the page at both
design time and runtime, but every PA template needs the pens assigned at runtime
only. This can be done by calling the Process Analyst Cicode functions and pass the
PAV file or individual trend pens to those functions.
There are two new items on the PA templates:
l The Show/Hide Trend Statistics button shows and hides trend statistics columns in
the Process Analyst.
l The Std Deviation column works out the sample standard deviation value of the sam-
ples within the display area.
See Also

Process Analyst for Operators

1224
Chapter 44: Using StruxureWare Pages and Templates

Statistical Process Control Trend Page Templates

The following trend templates are provided for charting different types of statistical proc-
ess control:
l SPCPareto: Displays a Pareto chart for multiple variable tags
l SPCCpk: Displays an SPC mean chart and a Capability chart
l SPCXRSChart: Displays SPC mean, range and standard deviation charts
l EventSPCXRS: Displays SPC mean, range and standard deviation charts for Event
SPC trend tag
l MeanMeanChart: Displays SPC mean charts for two SPC trend tags
l RangeChart: Displays SPC mean and range charts for an SPC trend tag
l StandardChart: Displays SPC mean and standard deviation charts for an SPC trend
tag

File Page Templates

The following templates have been included for displaying different types of file:
l File: Displays a plain text file on the page. This template replicates the the func-
tionality of the original file template found in the standard Include project. The new
template is compatible with any existing PageFile() or DspFile() Cicode functions. It
can display up to 24 lines of text from a file at a time. Buttons are provided for the
user to browse to different rows and columns of the file.
l File_RTF: Displays a rich text format (RTF) file on the page using the CiTextBox Acti-
veX control. It can also display plain text file.
l File_HTML: Displays a hypertext markup language (HTML) file or an universal
resource locator (URL) link on the page. It needs Microsoft Internet Explorer to be
installed on the machine.
Several common features are presented on the templates:
The new file template replicates the functionality of the original file template in the
Include project. The new template is compatible with any existing PageFile() or DspFile()
Cicode functions. The HD768 version of the template can display up to 23 lines of text
from a file on screen, while the HD1080 version of the template can display up to 33
lines of text on screen. Buttons are provided for the user to browse to different rows and
columns of the file.
Several new features are added to the templates:

1225
Chapter 44: Using StruxureWare Pages and Templates

l When you create a page based on any of these templates in Graphics Builder, you
can predefine the file for display at runtime. Clicking anywhere on the page will
show a genie style dialog to allow you to enter a file path to assign a file to the page.
A Citect path substitution string can be used in the file path. When the page is
recalled at runtime, for example via PageDisplay(), the specified file will be auto-
matically displayed.
l The "Open File" button displays an Open File dialog to select a different file to dis-
play.
l The "Refresh" button reopens the already opened file to get the latest contents.
l The full path name of the currently opened file is displayed.

1226
Chapter 45: Creating a New Project
Creating a project based on the StruxureWare templates project is simple; by default, it is
incorporated as an included project in new projects. This means whenever you start a
new project, the StruxureWare templates are ready to use as necessary.
There are two ways to create a project based on the StruxureWare templates:
l Use the pre-defined starter project
l Create a project from scratch

Note: It is recommended when creating a project, you base it on one of the starter
projects. Offering a basic level of functionality, the project can be modified and
extended to suit your needs.

Using the pre-defined starter project

To base a project on an existing starter project:

1. Choose New Project from the File menu, or click the New Project button.
2. Type a name for your project and choose a location for the files. When naming your
project do not use spaces in the project name. Although CitectSCADA does not pre-
vent you from using spaces in a project name, using spaces can cause unpredictable
results.
3. Click the Create project based on starter project checkbox.
4. Choose the project on which you want to base your new project.
5. Click OK.
Two pre-defined starter projects with page resolutions HD1080 and HD768 for wide
screens only are provided as part of the product installation. Each of the starter projects
will be based on project "SxW_Style_1" and contain:
l A cluster named "Cluster1".
l A server of each server types: “IOServer1”, “AlarmServer1”, “ReportServer1” and“-
TrendServer1”.
l A memory I/O devices named “Internal”.
l Equipment type “Motor” and its associated template file, graphical genie and super-
genie pop-up pages.
l A role named "Administrators" which is linked to the "BUILTIN\Administrators"
Windows group and have global privilege of 1 to 8. This allows a user to log in

1227
Chapter 45: Creating a New Project

CitectSCADA at runtime using a Windows user account who belongs to the Admin-
istrators group of the local machine.
l Pages of Alarm, Summary, Disabled, Hardware, ProcessAnalyst and !Pr-
ocessAnalystPopup, Data Browse -Control Inhibit, and Manual Override, based on
the relevant templates found in the SxW_Style_Include project.
l Page specific menu items. For example, the active alarm page will have page specific
menu items such as Simulate, History, Acknowledge and Disable, and Filter options.
The newly created project will be immediately compilable, and will contain a basic level
of built-in functions such as viewing alarms and trends, and a menu displayed in the
right-panel to easily access and navigate the included pages.
Create a project from scratch
To configure a project based on the StruxureWare templates from scratch, follow these
steps:
1. Create a privileged user; see Creating a Privileged User.
2. Run the Computer Setup Wizard; see Running the Computer Setup Wizard.
3. Set up instant trending; see Using Instant Trending.
4. Set up multiple monitor display; see Displaying a Project on Multiple Monitors.
5. Implement audible alarms; see Implementing Audible Alarms.
6. Add Pages; see Creating New Pages
7. Create/define custom menu; see Creating Custom
Don't modify the StuxureWare template project for use as a runtime project; set it aside
for use as a template for new projects.
If creating a project based on the StuxureWare templates, it is not recommended to
include pages based on templates that use a different style, including the earlier Include
project. Doing so might affect functionality.
See Also
Creating Pages

Creating a Privileged User

Some StruxureWare template project content is restricted via a user login. Without a
valid login, some project functionality will be disabled. For example, the Close window
(the cross) button on title bar will not work if you log in as a user with restricted priv-
ileges.
By default, the following elements within the StruxureWare templates project are
restricted by global privileges.

1228
Chapter 45: Creating a New Project

Element Global Privilege Associated Parameter

Editing users 8 [Privilege]EditUser

Project shutdown 8 [Privilege]Shutdown

Acknowledge alarms 1 [Privilege]AckAlarms

Disable alarms 8 [Privilege]DisableAlarms

Silence alarms 0 [Privilege]SilenceAlarms

When configuring a StruxureWare template project,check that your users have appro-
priate access to the available functionality. Verify that your users can acknowledge
alarms if necessary.
To adjust the global privileges for the elements previously listed for a more complex
security architecture, adjust the [Privilege] parameters in the Citect.ini file. Click the rel-
evant link in the previous table above for details.
See Also
Running the Computer Setup Wizard
Privilege Parameters in the Parameters online help

Running the Computer Setup Wizard

As with any CitectSCADA project, you need to fill in the Computer Setup Wizard on any
machine where a StruxureWare template project will be run. See Running the Computer
Setup Wizard for more information.

Using Instant Trending

Instant trending is natively supported by the Process Analyst. The steps to implement
instant trending are as follows:
1. Create a Process Analyst page. Create a page that has a Process Analyst object on it.
You may create these pages based on the provided tab style templates. For a full-
screen page, create the page based on the SinglePA template. For a pop-up page,
create the page based on the PopPA template.
2. Set the sample cache duration. Samples collected for Instant Trends are kept in the
cache up to a default number of samples and time period. You can adjust these set-

1229
Chapter 45: Creating a New Project

tings using the parameters [Trend]InstantTrendSamples and [Trend]Instant-

TrendIdleTime.

3. Call the Process Analyst Display. At runtime, call your process analyst page either
as a fullscreen page or pop-up page using the Cicode function PageDisplay(page-
name) or PagePopup(pagename) respectively.
4. Add Variable Tags / Local Variables for Trending. Use the Add Pens dialog pro-
vided with the Process Analyst to add pens to the process analyst chart as normal. In
the dialog, you can now select any variable tags or local variables for trending.
See Also
Process Analyst Page Templates

Displaying a Project on Multiple Monitors

For projects based on the StruxureWare templates, multiple monitors will be supported
through the core product. You can display a CitectSCADA window on each of the mon-
itors on the machine by adjusting the following parameters:
l [MultiMonitors]Monitors - Adjust this parameter to indicate how many monitors
your project will be running on.
l [MultiMonitors]StartupPage<n> - This parameter determines which page will appear
on each monitor at startup. You have to duplicate this parameter for each monitor.
For example, StartupPage1 determines the page that appears on the first monitor at
startup, StartupPage2 determines what appears on the second monitor, and so on. If
you do not specify a startup page for a particular monitor, the page specified in
parameter [Page]Startup will be displayed.
See Also
Working with Multiple Monitors

Implementing Audible Alarms

The StruxureWare template project offers support for audible alarms. You can configure
a project so that a selected wav file is sounded whenever an alarm of a particular prior-
ity is triggered. You can even assign different sounds to different alarm priorities, allow-
ing the urgency of an alarm to be determined from its sound.
To implement audible alarms in your project:

1230
Chapter 45: Creating a New Project

Sound1 identifies the .wav file that will be sounded whenever a priority 1 alarm is trig-
gered.

3. If necessary, adjust the parameter [Alarm]SoundnInterval. This parameter determines

how long the selected wav file sounds, based on the priority of the alarm (n). For
example, [Alarm]Sound1Interval sets the length of time a priority 1 alarm is sounded
for.
4. Verify that your users have appropriate privileges associated with their login to
silence alarms, otherwise they will not be able to silence an alarm. See Creating a
Privileged User and the parameter [Privilege]SilenceAlarms.
See Also
Alarm Page Templates

Creating Pages
If you created your project by selecting the Create project based on starter project check-
box in the New Project dialog, pages of Alarm, Summary, SOE, Disabled, Hardware, Pro-
cessAnalyst and !ProcessAnalystPopup will already be created in your new project. You
can accept those pages or modify them as you develop your project. See Creating a new
project.
If you created your project from scratch, there are no predefined pages in your project.
The navigation controls at runtime on the StruxureWare template expect several default
pages to exist in your project for basic functionality such as alarm and trend displays.
You are recommended to add the following pages to your project based on the provided
templates of your chosen size:

Template Description

SinglePA or Dou- Process Analyst page for displaying trends.

blePA

!PopPA Process Analyst pop-up page.

Data Browse Tem- Tag Browse page.

plate

Alarm Active Alarms page, called from the Alarms toolbar.

Hardware Hardware Alarms page, called from the Alarms toolbar.

Disabled Disabled Alarms page, called from the Alarms toolbar.

Summary Alarms Summary page, called from the Alarms toolbar using the His-

1231
Chapter 45: Creating a New Project

Template Description

torical events icon.

SOE (Sequence of Sequence of events page, called from the Alarms toolbar using the His-
Events) torical events icon.

The links between the pages listed and the controls that call them are defined by the
[Page] parameter settings within the Citect.ini file. The relevant parameters are [Page]Pro-
cessAnalystPage, [Page]ProcessAnalystPopupPage, [Page]AlarmPage and [Page]Hard-
warePage, etc. If you want a button to call a page with a different name, adjust these
parameter settings. For details see Page Parameters.

Creating new pages

The normal template in the StruxureWare template library is designed with minimal con-
tent to enable the presentation of customer-necessary information and plant mimics.
Pages are created based on this template within Graphics Builder by choosing the nec-
essary template from the Use Template dialog (File | New Page). You can access the
StruxureWare templates by selecting SxW_style_1 from the Style field.

Note: If you try to launch a StruxureWare template from within Citect Explorer, you
need to drill down to [Project Name]/Graphics/Templates/sxw_style_1/[Resolution] to
locate it. Two different wide screen resolutions are provided HD768 and HD1080.

Creating Custom Menus for StruxureWare templates

The content of the menus on pages based on the StruxureWare templates can be con-
figured via the Menu Configuration dialog, which is launched from Citect Project Editor
at configuration time.

Note:If your project is based on a StruxureWare starter project a basic pre-configured

menu exists. The menu allows you to access the page templates included in the
starter project and is displayed in the right-panel. Page specific menu items are dis-
played under the active page list. Options available vary according to the type of
page.

Example 1: In the basic example outlined below the following pages MyFirstPage,
MySecondPage, MyThirdPage, MyActiveAlarmPage, MyDisabledPage, and MySOEPage
will be added to the menu so they will be listed in the right-hand panel.

1232
Chapter 45: Creating a New Project

To configure:
1. From the Citect Project Editor -> select System -> Menu Configuration
2. In the Menu Configuration dialog complete the following fields:

Field Value

Level 1 MyPage

Level 2 MyFirstPage

Menu Command PageDisplay("Name of Page") e.g PageDisplay("MyFirstPage")

3. Click Add
4. Repeat steps 1 to 4 for the remaining pages MySecondPage, and MyThirdPage.
5. When finished compile and run your project. The right-panel should look like the one
below:

Example 2: To separate the alarm pages from the other graphic pages will create a new
node MyAlarm Pages , and add MyActiveAlarmPage, MyDisabledPage, and MySOE-
Page .
To configure:
1. From the Citect Project Editor -> select System -> Menu Configuration
2. In the Menu Configuration dialog complete the following fields:

Field Value

Level 1 MyAlarm Pages

Level 2 My Active Alarm Page

Menu Command PageDisplay("Name of Page") e.g PageDisplay("MyActiveAlarmPage")

3. Click Add
4. Repeat steps 1 to 4 for the remaining pages MyDisabledPage, and MySOEPage.
5. When finished compile and run your project. The right-panel should look like the one
below:

1233
Chapter 45: Creating a New Project

Example 3:In the next example an icon will be added to appear next to the Active Alarm
Page. The icon used is a standard symbol in the Include project.
To configure:
1. From the Citect Project Editor -> select System -> Menu Configuration
2. In the Menu Configuration dialog complete the following fields:

Field Value

Level 1 MyAlarm Pages

Level 2 My Active Alarm Page

Menu Command PageDisplay("Name of Page") e.g PageDisplay("MyActiveAlarmPage")

Symbol icons_16x16.alam_act

3. Click Replace
4. When finished compile and run your project. The right-panel should look like the one
below:

1234
Chapter 45: Creating a New Project

Note: The above examples are for basic illustration only. It is recommended you refer
to the example project and the menu configuration settings to further your under-
standing.

See Also

Menu configuration dialog

Using Environment Variables in StruxureWare Templates

Whereas parameters apply specified rules to every template page, environment variables
apply rules to specific pages. In this way, you can use environment variables to specify
functionality for specific pages.
For example, to display a specific page, you'd specify the page name as the environment
variable. To call a specific Cicode function, you'd specify the function name (with a "?"
prefix), space, then a list of comma separated arguments, like this: ?WinPrint LPT1,0,0,
Trend.pal. (The "?" indicates that the variable is to be interpreted as a function call rather
than a page to display.)
Let's look at a more detailed example: usually the standard Print button is used for print-
ing a graphics page in WYSIWYG format. If you have a text/html file displayed on the
page, or perhaps a trend, you can create your own print function (for example, Print-
Trend) and specify it in the environment variable, as ?PrintTrend. To reduce the amount
of ink used, specify the WinPrint function with a user-defined palette. In this case you
would specify it as a parameter rather than as an environment variable so that it applies
to every page.

Note: For pages created based on the Process Analyst templates, you can print the
screen using the standard Print button, or print the chart using the Print button on
the toolbar of the Process Analyst object. Give the user both alternatives as they both
serve different purposes.

1235
Chapter 45: Creating a New Project

1236
Using the Tab Style Page Templates

This section contains information on the Tab Style Page Templates

and describes the following:
Introducing Tab Style Page Templates
Using Pages and Templates
Creating a New Project
"Tab Style Page Templates Reference" in the CitectSCADA Technical
Reference

1237
1238
Chapter 46: Introducing Tab Style Page Templates
The Tab Style Template Project is a preconfigured project that includes a set of templates
styled for the Windows 7 environment. It will help you reduce the time necessary to con-
figure a new project.
When a new CitectSCADA project is created, the Tab Style Template (Tab_Style_Include)
project is automatically incorporated as an included project. This means the project's tem-
plates are available for implementation when creating your graphics pages in Graphics
Builder.
As well as including a standard graphics page template for creating plant mimics, the
project also includes predefined process analyst and alarm templates (with or without
the equipment tree-view panel), a set of file templates for displaying text, Rich Text For-
mat and HTML files. They have identical tab style navigation and alarm menus for con-
sistent "look and feel" across an entire project. The project also supports multimonitor
displays, allowing you to simultaneously display several graphics pages across several
computer screens.

Note: Do not modify the Tab Style Template project for use as a runtime project. It
will not compile successfully, and be set aside for use as a template for new projects.
CitectSCADA upgrades install a new version of the Tab Style Template project,
which will overwrite changes you make to the project when this happens.

Where to Find Information

Use the following links for details about the preconfigured content in the Tab Style Tem-
plate Project:
l Predefined templates. See Using Templates.
l Common toolbars. See Common Toolbars.
It also describes the processes used to create a project based on Tab Style templates:
l Creating a new project. See Creating a New Project.
l Creating pages. See Creating Pages.
l Creating custom menus. See Creating Custom Menus.
Reference material is also included, describing the citect.ini parameters and Cicode func-
tions available to customize a project.

1239
Chapter 46: Introducing Tab Style Page Templates

1240
Chapter 47: Using Pages and Templates
When you create a new project based on the Tab Style templates, the following templates
are available for you to use as you create your graphics pages. These templates share
Common Navigation Functionality, such as a customizable tabbed menu, a navigation
toolbar and an alarm toolbar. This section describes the templates and their buttons,
menus and tools.
The Tab Style template project has the following templates:

Tem- Description
plate
Type

Normal Standard graphics page. See Normal Page Template.

Blank For users who want to create their pages from scratch. See Blank Page Tem-
plate.

Data For users who want to display a table of data retrieved from built-in data browse
Browse functions on a page. See Data Browse Page Template.

Alarm Includes Alarm, Disabled, Hardware, Summary and Sequence of events for
displaying different types of alarm list. See Alarm Page Templates.

Proc- Includes SinglePA, DoublePA, PopPA. See Process Analyst Page Templates.
ess
Analyst

SPC Includes SpcPareto, SpcCpk, SpcXRSChart, EventSPCXRS, MeanMeanChart,

RangeChart and StandardChart. See SPC Page Templates.

File Includes File, File_RTF and File_HTML for displaying a plain text file, rich text
format file and HTML file / URL respectively. See File Page Templates.

See Also
Creating a New Project
Creating Pages

1241
Chapter 47: Using Pages and Templates

Common Navigation Functionality

The tab style page templates include common toolbars for easy navigation and feature
access, as well as a consistent appearance. This helps ensure pages that are created
based on these templates will look and operate in the same style.
The following three toolbars remain on screen during operation:
l Custom tabbed menus toolbar: Provides tabbed menus capable of navigation to a spe-
cific page or calling Cicode expression. The content of the menus (and its associated
buttons and sub-menus) is read from the menu configuration database configured via
Project Editor.
l Navigation toolbar: Provides navigation buttons and common page functions such
as direct access to home page, printing of current page and user login.
l Alarm toolbar: Provides access to alarm pages and displays the last three active
alarms.
See Also
Custom Tabbed menus Toolbar
Navigation Toolbar
Alarm Toolbar

Custom Tabbed Menus Toolbar

The tab style templates provides a tabbed toolbar to present the custom menus defined
in the menu configuration database. The tabbed menu toolbar consists of following com-
ponents:
Tab buttons
Tab buttons are equivalent of selecting a menu option in a traditional menu system.
Each tab contains a list of menu items (represented as icons) relating to that tab.
Menu icons (buttons)
Each tab contains a row of menu icons, each of which either performs a function such as
calling up a page or running a Cicode expression.
Sub-menu drop down lists
Optionally, a drop-down list may be provided next to the menu icon for further options.
You can also view it as a sub-menu to the top-level tab. In this case, the menu icon
serves as a collection point for related sub-menu items.
Hidden menu items

1242
Chapter 47: Using Pages and Templates

Where there are too many menu items to fit comfortably within the menu bar (either for
the tabs or the menu icons), a pair of drop-down list buttons are supplied at either end
of the menu bar which provide access to the menu items. The horizontal arrow buttons
on the menu bar displays only those items not visible on either side of the screen. The
vertical arrow button on the left side of the menu bar displays menu items (either tabs or
the menu icons for the currently selected tab)
See Also
Creating Custom Menus

Navigation Toolbar
The Navigation toolbar includes clickable text and icons to quickly access the common
pages and functions from every page in the project.
The following items are available from the toolbar:

Ico- Nam-
Description
n e

Goes Goes back to the page displayed before the current page.
back
one
page
in the
page
his-
tory

Goes Goes forward to the page that was displayed prior to the back button
for- being pressed. The arrow to the right of the button allows you to
ward select from menu of recently visited pages.
one
page
in the
page
his-
tory

Dis- Changes the display to the "parent page" of the current page. You
plays can assign a parent page to a graphics page by setting an envi-
the ronment variable in Graphics Builder. To do this, open the page you
par- want to assign a parent to. Go to the properties dialog for the page
ent (File | Properties), and click the Environment tab. Add a new var-
page iable called "ParentPage" with a value of the page name of the parent
page.

Dis- Moves backwards through pages in a browse sequence if a sequence

plays is configured. To configure a browse sequence, go to the Page Prop-

1243
Chapter 47: Using Pages and Templates

Ico- Nam-
Description
n e

the erties dialog (File | Properties) for each page in the sequence and
preset the Previous field on the General tab accordingly.
vious
page

Dis- Moves forwards through pages in a browse sequence if a sequence is

plays configured. To configure a browse sequence, go to the Page Prop-
the erties dialog (File | Properties) for each page in the sequence and
next set the Next field on the General tab accordingly.
page

Dis- Displays the "home" page. A home page act as a default page for the
plays project. To set a home page, use the [Page]HomePage parameter.
the
home
page

Dis- Displays a dialog box with a list of graphics pages defined in the
plays project. The user can select a page name for display.
the
Page
Selec-
t
dialo-
g

Prints Prints the current graphic page to the selected printer using the
the built-in WinPrint() Cicode function. You can specify your own print-
cur- ing function for the page by setting an environment variable in Graph-
rent ics Builder. To do this, open the page you want to assign a printer
page function to. Go to the properties dialog for the page (File | Prop-
erties), and click the Environment tab. Add a new variable called
"PrintPage" with a value of Cicode command in the syntax of "?" fol-
lowed by a valid Cicode function name and comma separated argu-
ments, for example, ?MyPrintFunction "arg1","arg2".

Login Displays the standard CitectSCADA login prompt. The menu to the
/ Log- right offers extra options. The default options are Login, Logout,
out Change Password, Edit User (restricted by login) and Create User
(restricted by login). Logged in user is indicated to the right of the
button. You can override the default options by defining your own
login menu in the menu configuration database via Project Editor. The
Page field and Level 1 field of these menu items needs to be set to
"Template" and "Login" respectively.

1244
Chapter 47: Using Pages and Templates

Alarm Toolbar
The alarms toolbar provides access to current alarm information and navigation buttons
for single-click access to alarm pages. It also includes standard CitectSCADA prompt
and current date and time.
The alarms toolbar contains the following features:

Icon Name Description

n/a Last The center panel of the toolbar displays the last alarms triggered
Alarms within the system, providing the operator with an immediate visual
cue to alarm occurrences.

You can modify the format of this list and control which alarms
appear. For example, you can set the list to only display alarms of a
particular type, category or priority.

For details, see the Alarm parametersLastAlarmFmt, Las-

tAlarmCategories, LastAlarmPriorities, and LastAlarmType in the
parameter online help .

Active Changes the display to the active alarms page. This button is
Alarms animated and shows the count of unacknowledged alarms in the
system. The page displayed by this button is determined by the
parameter [Page]AlarmPage.

His- The arrow to the right allows you to change the display to the
torical sequence of events or alarm summary page. When clicking on the
Events historical events button again the sequence of events page will dis-
play by default.However, if there is no SOE page configured in the
project, the alarm summary page will be displayed.

Sequence of events - Select the option Sequence of Events. The

SOE page displays each state transition of an alarm instance as a
separate row.

This page is determined by the [Page]SOEPage.

Alarm Summary - The alarm summary page provides an historical

log of alarm occurrences.

This page is determined by the [Page]SummaryPage.

Hard- Changes the display to the hardware alarms page. This is an

ware animated button which will blink when an unacknowledged hard-
Alarms ware alarm occurs. The page displayed by this button is deter-
mined by the parameter [Page]HardwarePage.

Dis- Changes the display to the disabled alarms page. This button

1245
Chapter 47: Using Pages and Templates

abled shows the count of disabled alarms in the system. The page dis-
Alarms played by this button is determined by the parameter [Page]Dis-
abledPage.

Alarm Silences the audible alarm buzzer that sounds when there are
Silenc- pending unacknowledged alarms. See Implementing Audible
e Alarms.

Normal Page Template

A template designed for creating user-necessary content and plant mimics. This page
contains the custom tabbed menus, the standard navigation and alarm toolbars featured
on tab style templates. If you are creating a project based on the tab style templates, use
this template for your standard graphics pages.
The Normal template creates a page in display format to be shown with a title bar. Sev-
eral sizes of templates are available including XGA (1024 x 768), SXGA (1280 x 1024),
HD1080 (1920 x 1080) and WUXGA (1920 x 1200).

Note: Starting in version 7.20, you can customize the behavior of the standard win-
dow titlebar to lock down its functions to achieve the same result that used to be
only possible by hiding it in the previous versions. This is achieved by overriding
the titlebar events or setting the startup mode of the window.

See Also
Creating Tab Style Pages
Securing the Window Titlebar

Blank Page Template

The blank template is included for users who want to create their pages from scratch.
There are no differences between the tab style blank template and the template in the
include project.
See Also
Creating Pages

1246
Chapter 47: Using Pages and Templates

Data Browse Page Template

The data browse template is included for users who want to create a page that displays
a table of data retrieved from built-in data browse functions. The template includes the
Equipment tree library control.
When using this template to create a new page within your project, configure the Data
Browse pop up form. When configured the new page will display the appropriate data
session at runtime.

Field Description

Browse The type of project configuration to be browsed and displayed, including:

Clusters A comma delimited string specifying only items from a subset of clusters to be
(Optional) included in the display. If not specified, items from all clusters will be included.

1247
Chapter 47: Using Pages and Templates

different data browse pages or share the same view among multiple pages.
When user selects the Save view command from the Action tab, the current col-
umn settings will be saved under the view name. Once a view is saved, when
user re-enters the page, previous saved view settings will be retrieved auto-
matically. The saved view can also be restored on demand by selecting the
Restored saved view from the Action tab. User can reset (forget) the view to the
default as how it was pre-configured by selecting the Restore view to default
command under the Action tab.
For system engineers, the information associated with a view name is saved
under INI parameters:
[BrowseTableView] <BrowseType>.<ViewName>.Fields
<BrowseType>.<ViewName>.ColWidths
in comma delimited format. You can pre-configure these parameters in your
project as the defaults.

Interactive Data Browse List

1248
Chapter 47: Using Pages and Templates

starting to the ending row. Once rows are selected, you can extend its range by SHIFT
left-clicking another row of alarm.
l To select disjointed rows, hold the CTRL key while selecting a row.
l To deselect alarm(s): Left-click any alarm within a selection range to deselect the
whole range. Only the row that you have clicked will remain selected. Click the
selected row again to deselect it.
Context Menu
If the page is set to display tag browse data, right-click on any row will bring up the con-
text menu for operations. Options available in the context menu will vary depending on
whether single or multiple items are selected:
The commands will only work if:
l Tag field is included in the table display
l For system with multiple clusters, the cluster field will also need to be included
The items available on the menu are selection sensitive depending on whether single or
multiple items are selected at the time. The following options are available only when
single row is selected:
l Set Value
The following options are available:
l Set Override Mode
l Set Control Mode

Action Tab
When the user displays a Data Browse page based on the Data Browse template, an
Action tab will be automatically added to the menu bar.The following options are avail-
able on the Action tab:

Icon Name Description

Refresh Reload the column settings.

Auto-Fit Auto size column widths in the data browse list.

Columns

1249
Chapter 47: Using Pages and Templates

Icon Name Description

Has the following options:

Save View Save View - Current column settings will be saved. When you
re-enter the page, previous saved view settings will be
retrieved automatically.
Restore Saved View - Restores the saved view on demand.
Reset View to Default - Reset the view to the default value.

Alarm Equipment Tree-view Page Templates

Alarm page templates are included for the following types of alarm displays:
l Active Alarm Page (alarm_equip): Used to create a page displaying active alarms
that are unacknowledged or acknowledged and still in alarm state. The template has
the equipment tree-view panel displayed on the left hand side of the page. When con-
figured the tree-view will display a hierarchy of equipment available to the currently
logged on user. The template also includes vertical and horizontal scroll bars to
allow users to view columns and rows off screen. To create a default active alarm
page for your project, create a new page based on the alarm_equip template. By
default, the name of the page is expected to be "Alarm". However, you can change the
name of the page by adjusting the setting for the INI parameter [Page]AlarmPage.
l Disabled Alarm Page (disabled_equip): Used to create a page displaying alarms that
are presently disabled in the system. The alarms will appear on this page when they
have been disabled from the normal alarm system due to a maintenance shutdown,
nuisance tripping etc.The template has the equipment tree-view panel displayed on
the left hand side of the page. When configured the tree-view will display a hierarchy
of equipment available to the currently logged on user. To create a default disabled
alarm page for your project, create a new page based on the disabled_equip template.
By default, the name of the page is expected to be "Disabled". However, you can
change the name of the page by adjusting the setting for the INI parameter [Page]Dis-
abledPage.
l Sequence of Events Page (soe_equip): Used to create a page displaying a snapshot
of every state transition of an alarm instance that have occurred. The template has
the equipment tree-view panel displayed on the left hand side of the page. When con-
figured the tree-view will display a hierarchy of equipment available to the currently
logged on user. To create a default SOE alarm page for your project, create a new
page based on the soe_equip template. By default, the name of the page is expected
to be "SOE". However, you can change the name of the page by adjusting the setting
for the INI parameter. [Page]SOEPage. Unlike the active, hardware, and disabled
alarm pages, that are refreshed automatically at runtime to display real time data, the
SOE and summary pages display a snapshot of events that have occurred, therefore

1250
Chapter 47: Using Pages and Templates

is not updated automatically. To retrieve the latest events you can manually refresh
the page.
l Alarm Summary Page (summary_equip): Used to create a page displaying a his-
torical log of alarms that have occurred. This page can be used for troubleshooting
purposes.The template has the equipment tree-view panel displayed on the left hand
side of the page. When configured the tree-view will display a hierarchy of equip-
ment available to the currently logged on user. To create a default summary alarm
page for your project, create a new page based on the summary_equip template. By
default, the name of the page is expected to be "Summary". However, you can change
the name of the page by adjusting the setting for the INI parameter [Page]Sum-
maryPage.

SUMMARY DATA NOT AUTOMATICALLY REFRESHED

Summary data is not automatically refreshed at runtime. Manually refresh the Summary
page before using its data for analysis of plant state.

Failure to follow these instructions can result in injury or equipment damage.

The alarm equipment tree-view templates display alarm lists using a "no draw" mode.
The display of alarm fields is handled by a new set of template specific Cicode functions
and genies to control each of the alarm fields' position and size. The alarm list is
installed with a callback event function to redraw the alarm list upon data change. The
"no draw" mode and data change callback event are supported by a modified form of
the existing Cicode function AlarmDsp().

Common Functionality
The alarm equipment tree-view page templates offered as part of the tab style page tem-
plates include common graphical user interface (GUI) features for easy operation and
consistent appearance.
These include:
l Action Tab - Provides controls to carry out common tasks that apply to the whole of
the alarm list.
l Interactive Alarm List - Provides controls to manipulate the columns displayed on
the alarm list and select alarms.
l Equipment Tree-view filter - The tree-view can be used to filter the results of the list
of alarms displayed.
l Column Sorting and Filtering Status Indicator - Sorting and filtering status indicator
shown in header of column.

1251
Chapter 47: Using Pages and Templates

See Also
Action tab
Interactive Alarm List
Filtering Alarms using the Equipment tree-view
Column Sorting and Filtering Status Indicator

Action Tab
When the user displays an alarm page based on the alarm equipment tree-view tem-
plates, an Action tab will be automatically added to the menu bar. Options available on
the Action tab vary according to the type of Alarm page.

Icon Name Description

Acknowledge Acknowledge all alarms on the current page. Available on

Page Active Alarm page.

Disable Page Disable all alarms on the current page. Available on

Active Alarm page.

Silence Alarm Silence alarm sound. Available on Active Alarm page.

Enable Page Enables all alarms on Page. Available on Disabled Alarm

Page.

Set Filter Opens the alarm filter form. Filter form varies according
to alarm page open.

Reset filter Clears the effect of the filter criteria specified through
the filter form.

Reload View Reload the column settings according to the alarm format
set in parameter [Format]<FormatName>.

Save View Save changes to the alarm display

1252
Chapter 47: Using Pages and Templates

Icon Name Description

Add column Add column to the alarm display list.

Auto size col- Auto size column widths in the alarm display list.
umns

Print/Export Print or Export the current page

Interactive Alarm List

The alarm equipment tree view page templates feature an interactive alarm list that sup-
ports the following functionality:
Adjustable Columns
The user can adjust the columns displayed on the alarm list. Options include:
l Reposition a column by drag-and-drop its column heading to the new position.
l Delete a column by drag-and-drop its column heading (vertically) beyond the column
heading row.
l Insert or delete a column via a pop-up menu by right-clicking a column heading
l Adjust the size of a column by dragging the column separator that appears at the
right edge of a column heading.
Dockable Equipment tree-view
l Adjust the width of the equipment tree-view by dragging the column separator that
appears at the right edge of the column.When selected the column separator will
change from blue to gray.
l To hide the equipment tree-view click the arrow icon on the column separator. On
clicking it the equipment tree-view will collapse and be hidden from view. Click the
arrow icon at the edge of the page to show the equipment tree-view on screen.
Selection of Alarms
The user can select single or multiple alarms on the alarm list so that the same oper-
ation can be applied to multiple selected alarms in one go. If some of the selected alarms
are off-screen, before the required operation is completed, a message dialog will popup,
reminding the user that some of the selected records are not viewable. On clicking Con-
tinue or the Enter key the selected records on and off the screen will be acted on. On click-

1253
Chapter 47: Using Pages and Templates

ing Cancel or the ESC key the command is canceled. If the selected records are viewable
on-screen the message dialog will not open.
Alarm selection works as follows:
l To select a single alarm: Left-click an alarm that is not already selected to select it.
l To select a continuous range of alarms: Select a single alarm to mark the start of the
selection. Then hold the SHIFT key and left-click another alarm to extend the selec-
tion. Alternatively, you can select rows by dragging the mouse cursor from the start-
ing to the ending row. Once rows are selected, you can extend the range of the
selection by SHIFT left-clicking another row of alarm.
l To select disjointed rows, hold the CTRL key while selecting a row.
l To deselect alarm(s): Left-click any alarm within a selection range to deselect the
whole range. Only the row that you have clicked will remain selected. Click the
selected row again to deselect it.
Sorting the Alarm List
Users can sort the alarm list display using most fields except for 'State' and 'Type'. To
sort click on the header of the relevant column.
The default order of alarms is dependent on the [Alarm]SummarySortMode parameter
and the type of alarm page.
Refer to the topic Default Sort Order for more information.
Context Menu
Right-click on any alarm row to bring up the context menu for alarm operations.Options
available in the context menu will vary depending on whether single or multiple items
are selected. If you right-click on an alarm that is not already selected, this will select it.
Subsequent commands (selected from the context menu) will then only operate on this
single alarm. On the other hand, if you right-click on any alarm within a selection range,
this will not change the selection. Subsequent commands selected will operate on each
alarm within the selection range. Several operation options are available in the context
menu:
l Information: displays the detailed information of a single alarm that has the cursor
focus (indicated by surrounded by a white box).
l Help: displays the Help page (which is set in the Help field of the alarm record in
Project Editor) of a single alarm that has the cursor focus.
l Acknowledge: acknowledges selected alarms. This option is restricted by the privilege
set by the parameter [Privilege]AckAlarms . This is not available on the Alarm Sum-
mary page.
l Disable: disables selected alarms. This option is restricted by the privilege set by the
parameter [Privilege]DisableAlarms . It is not available on the Disabled Alarms page.

1254
Chapter 47: Using Pages and Templates

Column Sorting and Filter Status Indicator

When you specify a filter or sort columns via the provided UI the status is shown in the
header of the columns. Whether you select equipment in the tree view panel, specify
filters via the filter form or click on the column header to sort a column, one of the fol-
lowing symbols will appear on the filtered/sorted column(s).

Symbol Description

No sorting or filtering is applied

Sorted in ascending order

Sorted in descending order

Filtered without explicit sorting order

Filtered and sorted in ascending order

Filtered and sorted in descending order

If an equivalent field to the column is being filtered the appropriate filter symbol will
appear in the heading of the column. For example, date and time should be filtered
together, thus when the date field is specified in the alarm filter form, the filter symbol
will appear in the time column.

Filtering Alarms using the Equipment tree-view

For alarm pages with the equipment tree view pane, you can filter the alarm display list
to show alarms belonging to selected parent and child equipment branches. If no equip-
ment is selected in the tree-view then all alarms are displayed.

1255
Chapter 47: Using Pages and Templates

To select equipment, check the box to the left of the relevant branches. If you select equip-
ment with child branches, then the child equipment will be selected and grayed out.

Note: If the parent equipment branch is checked, child equipment cannot be dese-
lected.

If the parent is not selected you can change the checked states of the child equipment.
Next to each item in the tree, an alarm count is displayed. The count includes the total
number of alarms belonging to the equipment and its child hierarchy. The type of
alarms that are counted vary according to the type of alarms that are displayed on the
list. For example, on the active alarms page, the count represents the active alarms asso-
ciated to that equipment, while on the disabled alarms page, the count represents the dis-
abled alarms associated to that equipment. Other points to consider with the equipment
count include:
1. The count on the tree node represents the total number of alarms that are associated
with that equipment.
2. For alarms that are not associated to equipment, the count is not available due to the
nature of the equipment tree view.
3. The counts are not affected by the filter applied to the alarm list.
4. Due to point 2 and 3, the total sum of the counts from the equipment tree does not
equal to the alarm count on the alarm banner, and they never mean to be com-
parable. The alarm count on the banner represents the total number of (unfiltered)
unacknowledged alarms in the system (subjected to the viewable areas of the cur-
rently logged on user).

Alarm Page Templates

Templates are included for the following types of alarm displays:
l Active Alarm Page (Alarm): Used to create a page displaying active alarms that are
unacknowledged or acknowledged and still in alarm state.To create a default active
alarm page for your project, create a new page based on this template. By default, the
name of the page is expected to be "Alarm". However, you can change the name of
the page by adjusting the setting for the INI parameter [Page]AlarmPage.
l Hardware Alarm Page (Hardware): Used to create a page displaying details of any
system errors that are unacknowledged or acknowledged and still in alarm state, for
example, if communications are lost, if Cicode can't execute, if a graphics page is not
updating correctly, or if a server becomes inoperative, this page will alert you. To
create a default hardware alarm page for your project, create a new page based on
this template. By default, the name of the page is expected to be "Hardware".

1256
Chapter 47: Using Pages and Templates

However, you can change the name of the page by adjusting the setting for the INI
parameter [Page]HardwarePage.
l Disabled Alarm Page (Disabled): Used to create a page displaying alarms that are
presently disabled in the system. The alarms will appear on this page when they
have been disabled from the normal alarm system due to a maintenance shutdown,
nuisance tripping etc. To create a default disabled alarm page for your project, create
a new page based on this template. By default, the name of the page is expected to be
"Disabled". However, you can change the name of the page by adjusting the setting
for the INI parameter [Page]DisabledPage.
l Sequence of Events Page (SOE): Used to create a page displaying a snapshot of all
state transitions of an alarm instance that have occurred. To create a default SOE
page for your project, create a new page based on this template. By default, the name
of the page is expected to be "SOE". However, you can change the name of the page
by adjusting the setting for the INI parameter. [Page]SOEPage. Unlike the active, hard-
ware, disabled pages that are refreshed automatically at runtime to display real time
data, the SOE and Summary pages display a snapshot of events that have occured,
therefore is not updated automatically. To retrieve the latest events you can manually
refresh the page.
l Alarm Summary Page (Summary): Used to create a page displaying a historical log
of alarms that have occurred. This page can be used for troubleshooting purposes. To
create a default alarm summary page for your project, create a new page based on
this template. By default, the name of the page is expected to be "Summary". How-
ever, you can change the name of the page by adjusting the setting for the INI param-
eter [Page]SummaryPage.

CAUTION Summary data is not automatically refreshed at runtime. Manually refresh the
Summary page before using its data for analysis of plant state.

The alarm templates (except the hardware alarm template) display alarm lists using a
"no draw" mode. The display of alarm fields is handled by a new set of template specific
Cicode functions and genies to control each of the alarm fields' position and size. The
alarm list is installed with a callback event function to redraw the alarm list upon data
change. The "no draw" mode and data change callback event are supported by a mod-
ified form of the existing Cicode function AlarmDsp().

1257
Chapter 47: Using Pages and Templates

Common Functionality
The alarm page templates offered as part of the tab style page templates include com-
mon graphical user interface (GUI) features for easy operation and consistent appear-
ance.
These include:
l Task Panels - Provides controls to carry out common tasks that apply to the whole of
the alarm list.
l Interactive Alarm List - Provides controls to manipulate the columns displayed on
the alarm list and select alarms.
See Also
Task Panels
Interactive Alarm List

Task Panels
The alarm page templates share panels to the left of the alarms list that support the fol-
lowing functionality:
Page Tasks
Allows the user to navigate through the list of alarms a page at a time. The Print /
Export hyperlink (not available in the hardware alarm page) allows the user to send the
alarms on the list to a printer or a file. The output will be presented in a HTML table,
and reflects the columns, filter and sort settings that are currently used on the display.
There are options to output available alarms (starting from page 1) or specific pages of
alarms starting from the current page of the alarm list. The blue box indicates the current
page number of the alarm list.
Filter Tasks
Allows the user to filter the current list based on date time, alarm name, plant area,
alarm category and other criteria. The Reset filter hyperlink clears the effect of the filter
criteria specified through the filter form. The blue box indicates the current filter setting.
It may display one of the following states:
l No Filter - no filter is applied
l Filter Applied - filter criteria specified in the filter form is applied
l Custom Filter - filter criteria is applied via Cicode function AlarmSetInfo() by the user
Control Tasks
Offers the option to:

1258
Chapter 47: Using Pages and Templates

l Acknowledge alarms on the current page (only available on Active Alarms and Hard-
ware Alarms page)
l Disable alarms on the current page (only available on Active Alarms page)
l Enable alarms on the current page (only available on Disabled Alarms page)
l Silence alarm sound (not available on Hardware Alarms page)
This panel is not featured on the Alarm Summary page.
View Tasks
Offers the option to:
l Add new column to the alarm list.
l Automatically fit the width of columns to show the most content.
l Reload the column settings according to the alarm format set in parameter [Format]
<FormatName>.
l Save the current column settings to parameter [Format]<FormatName>, so that the
same settings are used when this page is displayed in the future.
This panel is not featured on the Hardware Alarm page.

Interactive Alarm List

The alarm and alarm equipment tree view page templates (except the Hardware Alarms
template) feature an interactive alarm list that supports the following functionality:
Adjustable Columns
The user can adjust the columns displayed on the alarm list. Options include:
l Reposition a column by drag-and-drop its column heading to the new position.
l Delete a column by drag-and-drop its column heading (vertically) beyond the column
heading row.
l Insert or delete a column via a pop-up menu by right-clicking a column heading
l Adjust the size of a column by dragging the column separator that appears at the
right edge of a column heading.
Selection of Alarms
The user can select single or range of alarms on the alarm list so that the same operation
can be applied to multiple selected alarms in one go. Alarm selection works as follows:
l To select a single alarm: Left-click an alarm that is not already selected to select it.
l To select a range of alarms: Select a single alarm to mark the start of the selection.
Then hold the SHIFT key and left-click another alarm to extend the selection. You can
adjust the range of the selection by SHIFT left-clicking another row of alarm.

1259
Chapter 47: Using Pages and Templates

l To deselect alarm(s): Left-click any alarm within a selection range to deselect the
whole range.
Context Menu
Right-click on any alarm row to bring up the context menu for alarm operations.
Options available in the context menu will vary depending on whether single or mul-
tiple items are selected. If you right-click on an alarm that is not already selected, this
will select it. Subsequent commands (selected from the context menu) will then only oper-
ate on this single alarm. On the other hand, if you right-click on any alarm within a
selection range, this will not change the selection. Subsequent commands selected will
operate on each alarm within the selection range. Several operation options are available
in the context menu:
l Information: displays the detailed information of a single alarm that has the cursor
focus (indicated by surrounded by a white box).
l Help: displays the Help page (which is set in the Help field of the alarm record in
Project Editor) of a single alarm that has the cursor focus.
l Acknowledge: acknowledges selected alarms. This option is restricted by the privilege
set by the parameter [Privilege]AckAlarms . This is not available on the Alarm Sum-
mary page.
l Disable: disables selected alarms. This option is restricted by the privilege set by the
parameter [Privilege]DisableAlarms . It is not available on the Disabled Alarms page.
l Enable: enables selected alarms. This option is restricted by the privilege set by the
parameter [Privilege]DisableAlarms . It is not available on the Active Alarms page.
l Comment: Add a comment to an event. This option is only available when a single
row is selected. This option is restricted by the privilege set by the parameter [Priv-
ilege]AckAlarms . This option is available to Alarm Summary and SOE pages only.

Process Analyst Page Templates

The Process Analyst template is the default template for you to create trend pages. The
Tab Style project includes templates for the three following types of trend display:
l SinglePA - A template that displays a single Process Analyst chart on the page. To
create a default trend page for your project, please create a new page based on this
template and name it "ProcessAnalyst". You can change the default page name by

1260
Chapter 47: Using Pages and Templates

setting parameter [Page]ProcessAnalystPage

l DoublePA - A template that displays two Process Analyst charts on the page.
l PopPA - A template that displays a single Process Analyst chart on the page. The
size of the page is reduced to make it suitable for pop-up pages. To create a default
trend pop-up page for your project, please create a new page based on this template
and name it "!ProcessAnalystPopup". You can change the default page name by set-
ting parameter [Page]ProcessAnalystPopupPage
The functionality of traditional trends, double trends, and popup trends are largely incor-
porated into the Process Analyst on the new templates.
There is a key difference between the new PA templates and the existing trend templates,
which is pen assignment. The trend templates can get pens assigned to the page at both
design time and runtime, but every PA template needs the pens assigned at runtime
only. This can be done by calling the Process Analyst Cicode functions and pass the
PAV file or individual trend pens to those functions.
There are two new items on the PA templates:
l The Show/Hide Trend Statistics button shows and hides trend statistics columns in
the Process Analyst.
l The Std Deviation column works out the sample standard deviation value of the sam-
ples within the display area.
See Also

Process Analyst for Operators

Statistical Process Control Trend Page Templates

The Tab Style project includes the following trend templates for different types of sta-
tistical process control:
l SPCPareto: Displays a Pareto chart for multiple variable tags
l SPCCpk: Displays an SPC mean chart and a Capability chart
l SPCXRSChart: Displays SPC mean, range and standard deviation charts
l EventSPCXRS: Displays SPC mean, range and standard deviation charts for Event
SPC trend tag
l MeanMeanChart: Displays SPC mean charts for two SPC trend tags
l RangeChart: Displays SPC mean and range charts for an SPC trend tag
l StandardChart: Displays SPC mean and standard deviation charts for an SPC trend
tag

1261
Chapter 47: Using Pages and Templates

File Page Templates

The tab style project includes the following templates for displaying different types of
file:
l File: Displays a plain text file on the page. This template replicates the the func-
tionality of the original file template found in the standard Include project. The new
template is compatible with any existing PageFile() or DspFile() Cicode functions. It
can display up to 24 lines of text from a file at a time. Buttons are provided for the
user to browse to different rows and columns of the file.
l File_RTF: Displays a rich text format (RTF) file on the page using the CiTextBox Acti-
veX control. It can also display plain text file.
l File_HTML: Displays a hypertext markup language (HTML) file or an universal
resource locator (URL) link on the page. It needs Microsoft Internet Explorer to be
installed on the machine.
Several common features are presented on the templates:
The new file templates replicate the functionality of the original file template in the
Include project. The new templates are compatible with any existing PageFile() or
DspFile() Cicode functions. They can display up to 24 lines of text from a file at a time.
Buttons are provided for the user to browse to different rows and columns of the file.
Several new features are added to the templates:
l When you create a page based on any of these templates in Graphics Builder, you
can predefine the file for display at runtime. Clicking anywhere on the page will
show a genie style dialog to allow you to enter a file path to assign a file to the page.
A Citect path substitution string can be used in the file path. When the page is
recalled at runtime, for example via PageDisplay(), the specified file will be auto-
matically displayed.
l The "Open File" button displays an Open File dialog to select a different file to dis-
play.
l The "Refresh" button reopens the already opened file to get the latest contents.
l The full path name of the currently opened file is displayed.

1262
Chapter 48: Creating a New Project
Creating a project based on the Tab Style templates project is simple; by default, it is
incorporated as an included project in new projects. This means whenever you start a
new project, the tab style templates are ready to use as necessary.
There are two ways to create a project based on the tab style templates:
l Use the pre-defined starter project
l Create a project from scratch
Using the pre-defined starter project
To base a project on an existing starter project:

1. Choose New Project from the File menu, or click the New Project button.
2. Type a name for your project and choose a location for the files. When naming your
project do not use spaces in the project name. Although CitectSCADA does not pre-
vent you from using spaces in a project name, using spaces can cause unpredictable
results.
3. Click the Create project based on starter project checkbox.
4. Choose the project on which you want to base your new project.
5. Click OK.
Four pre-defined starter projects with page resolutions of XGA, SXGA, WUXGA and
HD1080 (Full HD) are provided as part of the product installation. Each of the starter
projects will be based on project "Tab_Style_1" and 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. This allow a user to log in Citect-
SCADA at runtime using a Windows user account who belongs to the Admin-
istrators group of the local machine.
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.
Create a project from scratch

1263
Chapter 48: Creating a New Project

To make it easier to configure a project based on the tab style templates from scratch, fol-
low these steps:
1. Create a privileged user; see Creating a Privileged User.
2. Run the Computer Setup Wizard; see Running the Computer Setup Wizard.
3. Set up instant trending; see Using Instant Trending.
4. Set up multiple monitor display; see Displaying a Project on Multiple Monitors.
5. Implement audible alarms; see Implementing Audible Alarms.
Don't modify the tab style templates project for use as a runtime project; set it aside for
use as a template for new projects.
If creating a project based on the tab style templates, it is not recommended to include
pages based on templates that use a different style, including the earlier Include project.
Doing so might affect functionality.
See Also
Creating Pages

Creating a Privileged User

Some tab style templates project content is restricted via a user login. Without a valid
login, some project functionality will be disabled. For example, the Close window (the
cross) button on title bar will not work if you log in as a user with restricted privileges.
By default, the following elements within the tab style templates project are restricted by
global privileges.

Element Global Privilege Associated Parameter

Editing users 8 [Privilege]EditUser

Project shutdown 8 [Privilege]Shutdown

Acknowledge alarms 1 [Privilege]AckAlarms

Disable alarms 8 [Privilege]DisableAlarms

Silence alarms 0 [Privilege]SilenceAlarms

When configuring a tab style templates project,check that your users have appropriate
access to the available functionality. Verify that your users can acknowledge alarms if
necessary.

1264
Chapter 48: Creating a New Project

To adjust the global privileges for the elements previously listed for a more complex
security architecture, adjust the [Privilege] parameters in the Citect.ini file. Click the rel-
evant link in the previous table above for details.
See Also
Running the Computer Setup Wizard
Privilege Parameters in the Parameters online help

Running the Computer Setup Wizard

As with any CitectSCADA project, you need to fill inthe Computer Setup Wizard on any
machine where a tab style templates project will be run. See Running the Computer
Setup Wizard for more information.
How you set up a computer using the Wizard is mostly up to you; however, due to
some necessary settings, you need to run the Computer Setup Wizard as a custom setup.
The Wizard page you need to pay attention to are:
l Security Setup - Control Menu Page

Security Setup - Control Menu page

All tab templates are designed to be displayed with the title bar. You need to select the
"Show Title Bar" option when you select to display the page in fullscreen mode.
Window title bar controls can be secured from unauthorized access. See Securing the
Windows Title bar.
See Also
Creating a Privileged User
Using Instant Trending
Implementing Audible Alarms

Using Instant Trending

1265
Chapter 48: Creating a New Project

settings using the parameters [Trend]InstantTrendSamples and [Trend]Instant-

TrendIdleTime.
3. Call the Process Analyst Display. At runtime, call your process analyst page either
as a fullscreen page or pop-up page using the Cicode function PageDisplay(page-
name) or PagePopup(pagename) respectively.
4. Add Variable Tags / Local Variables for Trending. Use the Add Pens dialog pro-
vided with the Process Analyst to add pens to the process analyst chart as normal. In
the dialog, you can now select any variable tags or local variables for trending.
See Also
Process Analyst Page Templates

Displaying a Project on Multiple Monitors

For projects based on the tab style templates, multiple monitors will be supported
through the core product. You can display a CitectSCADA window on each of the mon-
itors on the machine by adjusting the following parameters:
l [MultiMonitors]Monitors - Adjust this parameter to indicate how many monitors
your project will be running on.
l [MultiMonitors]StartupPage<n> - This parameter determines which page will appear
on each monitor at startup. You have to duplicate this parameter for each monitor.
For example, StartupPage1 determines the page that appears on the first monitor at
startup, StartupPage2 determines what appears on the second monitor, and so on. If
you do not specify a startup page for a particular monitor, the page specified in
parameter [Page]Startup will be displayed.
See Also
Working with Multiple Monitors

Implementing Audible Alarms

The tab style templates project offers support for audible alarms. You can configure a
project so that a selected wav file is sounded whenever an alarm of a particular priority
is triggered. You can even assign different sounds to different alarm priorities, allowing
the urgency of an alarm to be determined from its sound.
To implement audible alarms in your project:

1266
Chapter 48: Creating a New Project

Sound1 identifies the .wav file that will be sounded whenever a priority 1 alarm is trig-
gered.

3. If necessary, adjust the parameter [Alarm]SoundnInterval. This parameter determines

Creating Pages
If you created your project by selecting the Create project based on starter project check-
box in the New Project dialog, Alarm, SOE, Disabled, Hardware, ProcessAnalyst, !Pr-
ocessAnalystPopup, ControlInhibit, ManualOverride, VariableTags and generic
equipment pop-up pages would already have been created in your new project. You can
accept those pages or modify them as you develop your project.See Creating a new
project.
If you created your project from scratch, there are no predefined pages in your project.
The navigation controls on the tab template expect several default pages to exist in your
project for basic functionality such as alarm and trend displays. You are recommended
to add the following pages to your project based on the provided templates of your
chosen size:

Template Description

SinglePA or Dou- Process Analyst page for displaying trends.

blePA

!PopPA Process Analyst pop-up page.

Alarm Active Alarms page, called from the Alarms toolbar.

Hardware Hardware Alarms page, called from the Alarms toolbar.

Disabled Disabled Alarms page, called from the Alarms toolbar.

Summary Alarms Summary page, called from the Alarms toolbar using the His-
torical events icon.

1267
Chapter 48: Creating a New Project

Template Description

SOE (Sequence of Sequence of events page, called from the Alarms toolbar using the His-
Events) torical events icon.

Creating new pages

The normal template in the tab style template library are designed with minimal content
to enable the presentation of customer-necessary information and plant mimics.
Pages are created based on this template within Graphics Builder by choosing the nec-
essary template from the Use Template dialog (File | New Page). You can access the tab
style templates by selecting tab_style_1 from the Style field.

Note: If you try to launch a tab style template from within Citect Explorer, you need
to drill down to [Project Name]/Graphics/Templates/tab_style_1/[Resolution] to locate
it. Four different resolutions are provided including XGA, SXGA, HD1080 and
WUXGA.

Creating Custom Menus

The content of the tabbed menus on pages based on the tab style templates can be con-
figured via the Menu Configuration dialog, which is launched from Citect Project Editor
at configuration time. This is different to how menus are defined in the CSV_Include
project. If you are migrating from CSV_Include project to the tab style templates, you can
use the Migration Tool to migrate the CSV_Include menu definition to the Menu Con-
figuration database.
The tabbed menus read the menu configuration data in a custom fashion which are
explained in Defining page menus.
You can choose to use the default menus offered by the tab style templates which can be
turn on or off based on parameter [Page]AddDefaultMenu . Items in the default menus
are assigned with a sorting order of 100. When you configure to show the default menus
and your own defined menus at the same time, the two will be merged and ordered
accordingly. The default menus contain the following items:

1268
Chapter 48: Creating a New Project

Tabs Buttons

Pages Automatically populate the non-system pages configured in the project and
included project(s)

Alarms Active Alarms

Historical events (Alarm summary and SOE pages)

Disabled Alarms

Hardware Alarms

Trends Process Analyst

Calls Cicode function: PageProcessAnalyst("", "")

Process Analyst Popup

Calls Cicode function: ProcessAnalystPopup("","")

See Also
Defining page menus
Defining template popup menus

Defining page menus

Page menus in the tab style templates are defined using the Menu Configuration dialog.
For tab templates the fields have the following properties:
Order
The relative display position of the tabs / buttons or menu items among themselves. For
the tabs and buttons, it determines the display order from left to right. For the drop-
down menu items, it determines the display order from the top to the bottom. If this field
is left blank, it will take the default value of 0. The relevant entries will be displayed at
the start as a result. If more than 1 entry of the same order exists, they are displayed in
the same order as they are defined in the database.
Level 1
This represents the tabs on the tab bar.
Level 2
This represents the buttons displayed under a particular tab.
Level 3
This represents the menu items of the dropdown menu next to a particular button.
Level 4
This represents the sub-menu items of a particular dropdown menu item.
Menu Command

1269
Chapter 48: Creating a New Project

The Cicode expression to be executed when the menu item is selected. String of 256 char-
acters.
Symbol
The symbol to associate with the menu entry in the format of <library name>.<symbol
name>. The template expects the symbol to be a certain size when it is configured
against different menu types: For tabs, symbols are 16 x 16 pixels. For buttons, symbols
are 32 x 32 pixels. Some common symbols can be found in the symbol libraries of icons_
16x16 and icons_32x32. The field is not applicable for menu and sub-menu items.
Comment
A comment about the menu entry. String of 128 characters.
Page
The page on which this entry will exist. If blank, the entry exists every page. The page
name of "Template" is a keyword used in the templates for defining custom pop-up
menus.
Hidden when
The tab menu bar on the template does not support visibility. When the expression
defined in this field is true, the relevant menu entry is disabled instead.
Disabled when
Cicode expression to determine when the menu entry is disabled on the page. String of
256 characters.
Disabled style
This field is not used by the tab menu bar on the template.
Width
The width (measured in pixels) of the item appear on the page. If this is not specified,
the item is automatically sized to show the most content. This field only applies to the
tabs and buttons.
The objects used in the template are subjected to minimum widths: Tab (Level 1)= 63 pix-
els, and Button(Level 2) = 61 pixels.
Checked
Whether the menu item shows a check mark next to it. This field only applies to the
menu items and sub-menu items.
Privilege
The user privilege of (0-8) necessary to select the menu entry.
Area
The user area (0-255) necessary to select the menu entry.

1270
Chapter 48: Creating a New Project

See Also
Defining template popup menus
Configuring Page Menus

Defining template popup menus

The Tab style templates menu bar features two pop up menus:
l Login dropdown - brings up a dropdown menu for different login options. You can
override the default menu by specifying your own menu in the "Menu Configuration"
form. The override menu needs to be assigned with the page name of "Template" and
have field "Level 1" set to "Login" in the form.
l Alarm silence option button - clicking this button displays a context menu for select-
ing different silence options. This button is only enabled if you have sufficient priv-
ileges as specified in the parameter [Privilege] SilenceAlarms. You can override the
default menu by specifying your own menu in the "Menu Configuration" form. The
override menu needs to be assigned with the page name of "Template" and have field
"Level 1" set to "Alarm Sound" in the form.
See Also
Defining page menus
Configuring Page Menus

Using Environment Variables in Tab Style Templates

Note: For pages created based on the Process Analyst templates, you can print the

1271
Chapter 48: Creating a New Project

screen using the standard Print button, or print the chart using the Print button on
the toolbar of the Process Analyst object. Give the user both alternatives as they both
serve different purposes.

1272
Using the Library Control Include Project

This section contains information about the library control include

project
Introducing the Library Control Project
Using the Library Controls

1273
1274
Chapter 49: Introducing the Library Control Include
Project
The Library Control Include project is a series of genies for common UI controls such as
an equipment tree view, data table, and vertical and horizontal scrollbars.
The project is a system include project, and only appears in the Project List tree pane in
Citect Explorer if the View ->“Show Include Project” option is checked.

1275
Chapter 49: Introducing the Library Control Include Project

1276
Chapter 50: Using the Library Controls
The following genies are available for you to use as you create your graphics pages.

G- Description When to use

e-
n-
i-
e

Alar- A version of the Table genie for displaying an alarm list. Place on page to dis-
mT- play an alarm list.
able

Dat- A version of the Table genie to display snapshot information Place on page to dis-
a retrieved via the built-in data browse family of Cicode func- play a snapshot of
Bro- tions, such as AlmBrowse, TagBrowse and TrnBrowse or data retrieved from
wse other data browse-like data by providing custom initialization the built-in data
Tab- callback function to the genie. browse functions.
le

Equ- A version of the Tree genie for displaying a hierarchy of equip- Place on page to dis-
ipT- ment configured in the project. The EquipTree genie auto- play an equipment
ree matically loads the equipment defined in the project. tree.
For advanced usage, such as doing custom actions upon dif-
ferent events, you will need to write your own Cicode func-
tions and assign them to the callback functions part of the
genie form.

Scr- Displays a horizontal scrollbar for panning the displayed con- Place on page to view
oll- tent horizontally to reveal the off-screen portion of the con- the off screen content
ba- tent. This genie can be used with any content by hooking up
r_ the call-back events of the genies with the appropriate Cicode
Hor- functions (written by the users).
z

Scr- Displays a vertical scrollbar for panning the displayed content Place on page to view
oll- vertically to reveal the off-screen portion of the content. This the off screen content
ba- genie can be used with any content by hooking up the call-
r_ back events of the genies with the appropriate Cicode func-
Vert tions (written by the users).

Slid- Displays a Slider for hiding and displaying the equipment Place on page to hide
er tree-view panel on screen. the equipment tree-
view panel

SQL A version of the BrowseTable genie to display information Place on page to dis-
Tab- retrieved using the built-in SQL functions as a disconnected play data retrieved
le recordset. from an SQL data
source.

1277
Chapter 50: Using the Library Controls

Tab Displays a list of opened pages uniquely in the navigation bar. Place on page to dis-
play a list of opened
See Using the Tab Library Control for examples in how the
pages that will allow
control can be used.
users to navigate
between pages easily.

Tab- Displays background highlight for a particular row when it is Use when want to high-
le selected. This genie is to be used in conjunction with the light the selected row
Row Table genies. However, its use is optional. with a blue back-
ground color.
The position and size of the highlight is not automatically cal-
culated at runtime. Locate and resize the instance of this
genie in the Graphics Builder at design time.

Tab- Displays multiple rows of data on the screen in tabular layout. Place on page to dis-
le The genie is designed to display only a certain number of play table like data
rows and columns of data on screen. You can view the off- such as alarms, or
screen portion of the table by using it with the scrollbar database records.
genies or via specific Cicode functions. This genie does not
include the row highlight animation for row selection. How-
ever, you can find out which rows are selected via a set of spe-
cific Cicode functions.

Tag- A version of the Table genie for displaying a table of variable Place on page to dis-
Tab- tags added to the genie using the LibTagTable_AddTag() play a table of variable
le Cicode function. tags.
See Using the Tag Table Library Control for examples in how
the control can be used.

Tre- Displays a collection of items in a parent-child hierarchical Place on page to dis-

e relationship. Displays only a certain number of items on play hierarchical data,
screen. You can view the off-screen rows and columns of the such as an equipment
table by associating it with the scrollbar genies or via specific menu.
Cicode functions.
See Using the Tree Library Control for examples in how the
control can be used.

To use paste the genie on to the graphics page, and fill in the genie parameters at design
time. When complete select OK to save the library control.
See Also

Alarm Table Library Control

Alarm table genie has the following parameters:

Parameter Description

Alarm Table Name of table (max characters). Used to identify the genie when on a
Name graphics page

Width Pixel width of the table at runtime.

1278
Chapter 50: Using the Library Controls

Note:Leave the size of the genie at design time as 100 pixels, as it will be
automatically calculated at runtime.

Number of rows Number of rows displayed on the page.

Header Height Pixel Height of header row in table display.

Row Height Pixel height of row in the table display.

Header Padding The pixel padding between the bottom of the header text (column name)
and the bottom of the header row

Row Padding The pixel padding between the bottom of the cell text and the bottom of
each row.

Column Pad- The pixel padding on the left-hand-side and right-hand-side of the cell text
ding relative to the width of each column.

Refresh Rate The minimum (quickest possible) rate that the control will be redrawn.
The control is only redrawn as required upon changes to the layout, scroll-
ing or other user initiated events.

Scan Delay The number of page scan delay before the genie is initialized at runtime.
(Optional) this can be set to different number on different control genies to stagger
the initialization order. If not set defaults to 1.

Last Alarm List True/False drop down box. Determines whether the alarm list is a normal
list (which will be instantiated via function AlarmDsp) or a last alarm list
(which will be instantiated via function AlarmDspLast)

Horizontal The name of the horizontal scrollbar genie on the page that allows the user
Scrollbar to horizontally scroll the content displayed on the control genie If you do
(Optional) not require horizontal scrolling, leave this field blank.

Vertical Scroll- The name of the horizontal scrollbar genie on the page that allows the user
bar to vertically scroll the content displayed on the control genie If you do not
require vertical scrolling, leave this field blank.
(Optional)

Header Font The pre-configured font for header text .

Auto Width True/False drop down box. False is selected by default

Format Cat- The alarm category for determining the fields (columns) displayed If this is
egory not specified, the columns displayed on the table will be determined by the
field format defined in alarm category 0.

Cluster The cluster of the alarm list If this is not specified, alarms from all clusters
configured in the project will be displayed.

Allow Selection True/False drop down. True is selected by default

Alarm Type The display type of the alarm list Please see the type parameter of the built-
in Cicode function AlarmDsp for details.

AN The Animation Number (AN) of a user created Cicode / Animation Number

object where the alarm list will be instantiated (displayed) If this is less
than 1, the alarm list will be displayed at a random AN. The AN allows the
user to interact with the alarm list using built-in Cicode functions, such as

1279
Chapter 50: Using the Library Controls

AlarmSetInfo(), AlarmDspPrev() and AlarmDspNext(), etc at runtime.

Intialize Callback function that is called when the control initializes. The callback
(Optional) function should return either TRUE (1) for success or FALSE (0) if unsuc-
cessful. By default, if the user specified function does not initialize, the con-
trol genie will retry the function a few times before giving up. This callback
only supports the #Name keyword which represents the name assigned to
the control genie.

Note:The initialization callback function may be called multiple times when-

ever the table is re-initialized.

Left Mouse Callback function that is called when the user clicks the left mouse button
(Optional) No particular return value is expected from this function, and it supports
the following keywords in its argument list:
#Name = name assigned to the genie
#Row = row number of the cell (w.r.t. the underlying data) that is clicked
#Col = column number of the cell that is clicked
#RowDsp = row number of the cell relative to the display that is clicked
#ColDsp = column number of the cell relative to the display that is clicked
#AN= the animation number where the alarm is displayed

Right Mouse Callback function that is called when the user clicks the right mouse button
(Optional) It uses the same specification as that of the Left mouse callback .

Double Click Callback function that is called when the user double-click the left mouse
(Optional) button It uses the same specification as that of the Left mouse callback.

Table Reload Callback function that is called when the control is redrawn No particular
(Optional) return value is expected from this function, and it supports the following
keywords in its argument list:
#Name = name assigned to the genie

Note:The Table can be up to 62 columns (although the latter columns may not have
the column separators). For tables that return more columns that the limit, the first
62 columns will be displayed.

See Also
Using Library Controls

Using the Alarm Table Genie

In the example below a simple initialization function is used to set the columns (fields)
and then filter the display list when the alarm table initializes.
Example: Set columns and filter via table initialization callback event
1. The Cicode sample below will be used in the following example. Open the Cicode
Editor and create a new cicode file, for example, _MyAlmTable_Ex.ci

1280
Chapter 50: Using the Library Controls

INT FUNCTION MyAlmTable_Init(STRING sTable, STRING sEquipment)

// Set up columns
LibTable_AddColumn(sTable, "Name", 150);
LibTable_AddColumn(sTable, "Description", 150, "Desc");
LibTable_AddColumn(sTable, "State", 150);

// Set up filter
INT nAN = LibAlmTable_GetAN(sTable);
INT hEdit = AlarmFilterEditOpen(nAN);
AlarmFilterEditSet(hEdit, "Equipment=" + sEquipment);
AlarmFilterEditCommit(hEdit);
AlarmFilterEditClose(hEdit);

RETURN TRUE;
END

2. From the Graphics Builder create a new page (e.g. the Normal Tab Style Page)
3. When created, from the Object toolbox select -> The Paste Genie icon.
4. In the Paste Genie window select the lib_controls library
5. Select the Alarm Table genie. The Alarm Table genie is pasted onto the graphics
page.
In the ALarm Table Genie property dialog configure the following fields:

Parameter Description

Table Name Table 1

Width 400 ( all columns within the table are displayed. If left at 100 some col-
umns may not be displayed)

Number of rows 10

Header Height 18

Row Height 15

Header Padding 5

Row Padding 4

Column Padding 5

Horizontal Scrollbar

Vertical Scrollbar

Initialize MyAlmTable_Init("#Name","Plant*")

6. Click OK to save the changes

1281
Chapter 50: Using the Library Controls

7. Save the graphics page and compile and run the project.
At runtime the table will look like the following:

See Also
Using Library Controls

Browse Table Library Control

Browse table genie has the following parameters:

Parameter Description

Browse Table Name of table. Used to identify the genie when on a graphics page
Name

Width Pixel width of the table at runtime.

Note: Leave the size of the genie at design time as 100 pixels, as it will be
automatically calculated at runtime.

Number of rows Number of rows displayed on the page.

Header Height Pixel Height of header row in table display.

Row Height Pixel height of row in the table display.

Header Padding The pixel padding between the bottom of the header text (column name)
and the bottom of the header row

Row Padding The pixel padding between the bottom of the cell text and the bottom of
each row.

Column Pad- The pixel padding on the left-hand-side and right-hand-side of the cell text
ding relative to the width of each column.

Refresh Rate The minimum (quickest possible) rate that the control will be redrawn.
The control is only redrawn as required upon changes to the layout, scroll-
ing or other user initiated events.

Scan Delay The number of page scan delay before the genie is initialized at runtime.
(Optional) this can be set to different number on different control genies to stagger

1282
Chapter 50: Using the Library Controls

the initialization order. If not set defaults to 1.

Browse Type The type of project configuration to be browsed and displayed, including:
AccumBrowse – for listing accumulators
AlmBrowse – for listing alarm tags
AlmSummary – for listing alarm summary
EquipBrowse – for listing equipment
ServerBrowse – for listing servers
TagBrowse – for listing variable tags
TrnBrowse – for listing trend tags

Filter (Optional) A filter expression specifying the records to return during the browse If it
is not specified, all records will be returned. Please see the browse open
Cicode function of the selected browse type for the details of filter expres-
sion supported.

Fields A comma delimited string specifying the fields (columns) to be returned

(Optional) during the browse. If it is not specified, all fields of the selected browse
type will be displayed: Tag, Tag Item, Value, Comment, Cluster, Equip-
ment, Item, Type, IODev, Addr, Arr_Size, Eng_Zero,Eng_Full, Eng_Units,
Format, Deadband, Raw_Zero,Raw_Full, Scaled_Type, Ovr_Mode, Ctrl_
Mode, Override, Valid, Status, Field, Num_Subs.

Sort By A comma delimited string specifying the order of sorting preferences. This
(Optional) is only applicable to TagBrowse. Please see the Sort parameter of the built-
in Cicode function TagBrowseOpen for details.

Header Font The pre-configured font for header text .

Cell Font The pre-configured font for cell text.

Selection Font The pre-configured font for cell text when it is selected .

Auto Width True/False drop down box. False is selected by default. Determines
whether the column width will be automatically adjusted to show the entire
cell content when the control is redrawn.

Allow Selection True/False drop down. True is selected by default. Determines whether
allow the rows displayed on the control are selectable .

Clusters A comma delimited string specifying only items from a subset of clusters to
(Optional) be included in the display. If it is not specified, items from all clusters will
be included.

Intialize Callback function that is called when the control initializes. The callback
(Optional) function should return either TRUE (1) for success or FALSE (0) if unsuc-

1283
Chapter 50: Using the Library Controls

cessful. By default, if the user specified function does not initialize, the con-
trol genie will retry the function a few times before giving up. This callback
only supports the #Name keyword which represents the name assigned to
the control genie.

Note:The initialization callback function may be called multiple times when-

ever the table is re-initialized.

Left Mouse Callback function that is called when the user clicks the left mouse button.
(Optional) No particular return value is expected from this function, and it supports
the following keywords in its argument list:
#Name = name assigned to the genie
#Row = row number of the cell (w.r.t. the underlying data) that is clicked
#Col = column number of the cell that is clicked
#RowDsp = row number of the cell relative to the display that is clicked
#ColDsp = column number of the cell relative to the display that is clicked

Right Mouse Callback function that is called when the user clicks the right mouse but-
(Optional) ton. It uses the same specification as that of the Left mouse callback .

Double Click Callback function that is called when the user double-click the left mouse
(Optional) button. It uses the same specification as that of the Left mouse callback.

Note:The Table can be up to 62 columns (although the latter columns may not have
the column separators). For tables that return more columns that the limit, the first
62 columns will be displayed.

See Also
Using Library Controls

EquipTree Library Control

The EquipTree genie has the following parameters:

Note: For the genie to work, report server must be defined in your project, and your
project can connect to the report server at runtime.

Parameter Description

Tree Name Name of table (max characters). Used to identify the genie when on a

1284
Chapter 50: Using the Library Controls

graphics page

Width Pixel width of the table at runtime.

Note:Leave the size of the genie at design time as 100 pixels, as it will be
automatically calculated at runtime.

Number of items Number of items displayed on the page.

Item Height Pixel height of item in the tree display.

Show CheckBox True/False drop down box. False is selected by default. Determines
whether to show the checkboxes next to each of the tree items.

Force Child True/False drop down box. False is selected by default. Determines
whether to force all children tree items to follow the checked status of
their parent when the latter is checked / unchecked.

Window Inst True/False drop down box. True is selected by default. Determines
whether create a new instance of the equipment hierarchy on each win-
dow where the equipment tree is displayed.

Refresh Rate The minimum (quickest possible) rate that the control will be redrawn.
The control is only redrawn as required upon changes to the layout, scroll-
ing or other user initiated events

Expand Level The minimum expand level of the tree hierarchy. Set to 0 to allow the tree
be collapsed to its root items.

Horizontal The name of the horizontal scrollbar genie on the page that allows the
Scrollba user to horizontally scroll the content displayed on the control genie If you
(Optional)r do not require horizontal scrolling, leave this field blank.

Vertical Scrollbar The name of the horizontal scrollbar genie on the page that allows the
(Optional) user to vertically scroll the content displayed on the control genie If you
do not require vertical scrolling, leave this field blank.

Label Font The font used for displaying the tree item label.

Item Font The font used for displaying the optional dynamic text next to the tree
item.

Symbol Library The name of the symbol library that contains the symbols for displayed
(Optional) next to the tree items.

Refresh Rate The minimum rate that the control will be redrawn.
Note: The control is only redrawn as required upon changes to the lay-
out, scrolling or other user initialized events.

Scan Delay The number of page scan delay before the genie is initialized at runtime.
This can be set to different number on different control genies to stagger
the initialization order.

Expand Level The minimum expand level of the tree hierarchy. Set this to 0 to allow the
tree to be collapsed to its root items.

Filter (Optional) A filter expression specifying the equipment records to be displayed on

the tree. If it is not specified, all equipment available to the currently
logged on user will be returned

1285
Chapter 50: Using the Library Controls

Intialize Callback function that is called when the control initializes. The callback
function should return either TRUE (1) for success or FALSE (0) for
unsuccessful. By default, if the user specified function does not initialize,
the control genie will retry the function a few times before giving up. This
callback only supports the #Name keyword which represents the name
assigned to the control genie.

Row Item Callback function that is called when the table initializes The callback func-
tion should return a string value. The value returned will be displayed
next to the tree item label. It supports the following keyword in its argu-
ment list:
#Name - Name assigned to the genie
#Ref – the complete path of the tree item
#Label – the label of the tree item
#ItemDsp- The position of the item as displayed on screen
#IsChecked - The checked status of the tree item
#IsParent - Whether the item is expanded/collapsed
#ItemDsp - The position of the item as displayed on screen
#Node - The handle to the internal menu node object that represents the
tree item
#Level - The level of the tree item

Selected Callback function that is called when a tree item is selected. No particular
return value is expected from this function, and it supports the same set
of keywords as that of the Row Item function in its argument list. Callback
function that is called when the checkbox of a tree item is clicked. No par-
ticular return value is expected from this function, and it supports the
same set of keywords as that of the Row Item function in its argument list.

Checked Callback function that is called when a tree item is selected. No particular
return value is expected from this function, and it supports the same set
of keywords as that of the Row Item function in its argument list. Callback
function that is called when the checkbox of a tree item is clicked. No par-
ticular return value is expected from this function, and it supports the
same set of keywords as that of the Row Item function in its argument list.

Left Mouse Callback function that is called when the user clicks the left mouse button
No particular return value is expected from this function, and it supports
the following keywords in its argument list:
#Node - The handle to the internal menu node object that represents the
tree item
#Level - The level of the tree item

Right Mouse Callback function that is called when the user clicks the right mouse but-
ton. It uses the same specification as that of the Left mouse callback .

Double Click Callback function that is called when the user double-click the left mouse
button. It uses the same specification as that of the Left mouse callback.

Tree Reload Callback function that is called when the control is redrawn. No particular

1286
Chapter 50: Using the Library Controls

return value is expected from this function, and it supports the following
keywords in its argument list:
#Name = name assigned to the genie

Parameter Description

Tree Name Name of table (max characters). Used to identify the genie when on a
graphics page

Width Pixel width of the table at runtime.

Note:Leave the size of the genie at design time as 100 pixels, as it will be
automatically calculated at runtime.

Note: The project will compile and run when configured with longer equipment
names, a runtime error may occur when you attempt to interact with the tree display
based on the 'EquipTree' genie. When this happens, an alarm icon will appear on the
tree view, and a "Too few arguments for function or argument string too long" hard-
ware alarm will be reported. This usually indicates either the equipment name is too
long or the name of the tree genie is too long.

See Also
Using Library Controls

PageTabs Library Control

PageTabs genie has the following parameters:

Note: The PageTabs genie is specifically designed for displaying page data. The
genie internally binds page data to the tab display. You should not add tabs directly.
Manipulating the tab data using the LibTabs Cicode function may result in
unexpected behavior.

Parameter Description

Page Tabs Name of page tabs control (max characters 254). Used to identify the genie
Name when on a graphics page.

Width Pixel width of the tabs control at runtime.

Note: Leave the size of the genie at design time as 100 pixels, as it will be
automatically calculated at runtime.

Tab height Pixel height of the tabs control at runtime.

Vertical Pad- The vertical distance (in pixels) between the tab elements and the bottom
ding of the tabs control.

1287
Chapter 50: Using the Library Controls

Tab Padding The horizontal distance (in pixels) between the edges and elements of a tab

Tab Min Width The minimum width allowed for a tab

Tab Max Width The maximum width allowed for a tab

Auto Width True/False drop down box. False is selected by default. Determines
whether the column width will be automatically adjusted to show full cell
content when the control is redrawn.

Icon Add Pad- Additional vertical padding for the display of icon relative to the text. Pos-
ding itive padding will move the icon further upward, and vice versa.

Refresh Rate The minimum (quickest possible) rate that the control will be redrawn.
The control is only redrawn as required upon changes to the layout, scroll-
ing or other user initiated events.

Page Type The type of page data to be displayed in the tabs:

PageList
GenericMenu
PageMenu
WindowMenu

Menu (Page) Name of page with menu items to display. this is only applicable when Page
Name type is set to "PageMenu"

Default Font The pre-configured font for tab text .

Selection Font The pre-configured font for a tab when it is selected .

Tab Line Style The display style of the separator between tabs, options are:
Dark
Light
None

Tab Select Style The display style for highlighting of selected tab:
Dark
Light
None

Allow Drag Sort Indicates whether to allow individual tabs to be repositioned by drag and
drop.

Allow Drag Indicates whether to allow individual tabs to be deleted by dragging it ver-
Delete tically away from the tabs control.

Tab Select Icon The icon to be displayed when a tab is selected. An icon must be pre-con-
figured as a symbol in your project. It is specified by the syntax of <symbol
library>.<symbol>.

1288
Chapter 50: Using the Library Controls

trol genie will retry the function a few times before giving up. This callback
only supports the #Name keyword which represents the name assigned to
the control genie.
Note:The initialization callback function may be called multiple times when-
ever the tab is re-initialized.

Right Mouse Callback function that is called when the user clicks the right mouse button
(Optional) No particular return value is expected from this function, and it supports
the following keywords in its argument list:
#Name = name assigned to the genie
#Ref = reference (assigned when tab is added) of the cell that is clicked
#TabDsp = tab number of the cell relative to the display that is clicked
#Icon =Icon number indicating the different areas with a tab is clicked:
<=0 - text on tab is clicked
1- icon to left hand side of text is clicked
2- icon to right hand side of text is clicked
3- selection icon (only shows up when a tab selected) is clicked

Double Click Callback function that is called when the user double-click the left mouse
(Optional) button. It uses the same specification as that of the Left mouse callback.

Tabs Reload Callback function that is called when the control is redrawn. No particular
(Optional) return value is expected from this function, and it supports the following
keywords in its argument list:
#Name = name assigned to the genie

See Also
Using Library Controls

Scroll bar Horizontal Library Control

The horizontal scrollbar genie has the following parameters:

Parameter Description

Scrollbar Name A unique name used to identify the genie within a page.

Width The pixel width of the control at runtime. Leave the size of the genie at
design time as 100 pixels, as it will be automatically calculated at run-
time.

Update on Drag True/False (True selected by default). Determines whether the position of
the scrollbar and the contents of the associated control genie is updated
while the thumb is being dragged

Auto Hide Determines whether the scrollbar will be automatically hidden when the
contents of the associated control are fully displayed on screen

Allow Double Determines whether the scrollbar will response to mouse double-click
Click event

1289
Chapter 50: Using the Library Controls

Hidden When A user specified expression to explicitly hide the scrollbar If this is not
specified, it is defaulted to FALSE (not hidden).

Initialize Callback function that is called when the control initializes The callback
function should return either TRUE (1) for success or FALSE (0) if unsuc-
cessful. By default, if the user specified function does not initialize, the
control genie will retry the function a few time before giving up. This call-
back only supports the #Name keyword which represents the name
assigned to the control genie.

Callback Callback function to be called when the position of the scrollbar is

updated. No particular return value is expected from this function, and it
supports the following keywords in its argument list:
#Name = name assigned to the genie
#Pos = position of the scrollbar
#View = number of items for the scrollbar view (that constitutes one
page of items)
#Max = maximum (total) number of items for the scrollbar

Right Mouse Callback function to be called when the user clicks the right mouse button
on the scrollbar. Supports the same set of substitutions as Callback.

See Also
Using Library Controls

Scroll bar Vertical Library Control

The horizontal scrollbar genie has the following parameters:

Parameter Description

Scrollbar Name A unique name used to identify the genie within a page.

Height The pixel height of the control at runtime. Leave the height of the genie at
design time as 100 pixels, as it will be automatically calculated at run-
time.

Update on Drag True/False (True selected by default). Determines whether the position of
the scrollbar and the contents of the associated control genie is updated
while the thumb is being dragged

Auto Hide Determines whether the scrollbar will be automatically hidden when the
contents of the associated control are fully displayed on screen

Allow Double Determines whether the scrollbar will response to mouse double-click
Click event

Hidden When A user specified expression to explicitly hide the scrollbar If this is not
specified, it is defaulted to FALSE (not hidden).

Initialize Callback function that is called when the control initializes The callback
function should return either TRUE (1) for success or FALSE (0) for fail-

1290
Chapter 50: Using the Library Controls

ure. By default, if the user specified function fails to initialize, the control
genie will retry the function a few time before giving up. This callback
only supports the #Name keyword which represents the name assigned
to the control genie.

Callback Callback function to be called when the position of the scrollbar is

Right Mouse Callback function to be called when the user click the right mouse button
on the scrollbar. Supports the same set of substitutions as Callback.

See Also
Using Library Controls

Slider Library Control

The Slider genie has the following parameters:

Parameter Description

Slider Name A unique name used to identify the control genie within a page.

Length The pixel height of the control at runtime. Leave the size of the genie at
design time as 100 pixels, as it will be automatically calculated at run-
time.

Minimum Offset The min. offset (in pixels) the slider can be dragged to. The acceptable
range is -4000 to 4000.

Maximum Offset The max. offset (in pixels) the slider can be dragged to. The acceptable
range is -4000 to 4000.

Docked Offset The offset (in pixels) the slider is moved to when it is docked. If this is not
(Optional) set, it is defaulted to -4000.
The acceptable range is -4000 to 4000.

Dockable Whether the middle thumb button will appear at runtime, so that the user
can click on it to move the slider to the docked offset.

Update on Drag Whether the position of the scrollbar and the contents of the associated
control genie is updated while the thumb is being dragged.

Hidden Determines whether to hide the genie

Scan Delay The number of page scan delay before the genie is initialized at runtime
(Optional) This can be set to different number on different control genies to stacker

1291
Chapter 50: Using the Library Controls

their initialization order. If this is not set, it defaults to 0.

Initialize Callback function that is called when the control initializes The callback
function should return either TRUE (1) for success or FALSE (0) for
unsuccessful. By default,if the user specified function can not initialize
successfully, the control genie will retry the function a few times before
giving up. This callback only supports the #Name keyword which rep-
resents the name assigned to the control genie.

Callback Callback function to be called when the position of the slider is updated.
No particular return value is expected from this function, and it supports
the following keywords in its argument list:
#Name = name assigned to the genie
#Offset = Offset of the slider position relative to its initial position

Right Mouse Callback function to be called when the user click the right mouse button
on the scrollbar

See Also
Using Library Controls

SQL Table Library Control

Tag table genie has the following parameters:

Parameter Description

SQL Table Name of table (max characters). Used to identify the genie when on a
Name graphics page

Width Pixel width of the table at runtime.

Note: Leave the size of the genie at design time as 100 pixels, as it will be
automatically calculated at runtime.

Number of rows Number of rows displayed on the page.

Header Height Pixel Height of header row in table display.

Row Height Pixel height of row in the table display.

Header Padding The pixel padding between the bottom of the header text (column name)
and the bottom of the header row

Row Padding The pixel padding between the bottom of the cell text and the bottom of
each row.

Column Pad- The pixel padding on the left-hand-side and right-hand-side of the cell text
ding relative to the width of each column.

Refresh Rate The minimum (quickest possible) rate that the control will be redrawn.
The control is only redrawn as required upon changes to the layout, scroll-
ing or other user initiated events.

1292
Chapter 50: Using the Library Controls

Connection Str The ADO connection string to the database source Please see the sConnect
parameter of the built-in Cicode function SQLCreate for details.

SQL Selection The SQL query statement to return a table of records (recordset)
Query

Header Font The pre-configured font for header text .

Cell Font The pre-configured font for cell text.

Selection Font The pre-configured font for cell text when it is selected .

Auto Width True/False drop down box. False is selected by default. Determines
whether the column width will be automatically adjusted to show full cell
content when the control is redrawn.

Allow Selection True/False drop down. True is selected by default. Determines whether
allow the rows displayed on the control are selectable .

Note: The initialization callback function may be called multiple times

whenever the table is re-initialized.

Right Mouse Callback function that is called when the user clicks the right mouse but-
(Optional) ton. It uses the same specification as that of the Left mouse callback .

Double Click Callback function that is called when the user double-click the left mouse
(Optional) button. It uses the same specification as that of the Left mouse callback.

1293
Chapter 50: Using the Library Controls

Note: The Table can be up to 62 columns (although the latter columns may not have
the column separators). For tables that return more columns that the limit, the first
62 columns will be displayed.

See Also
Using Library Controls

Tabs Library Control

Tabs genie has the following parameters:

Note: All fields are mandatory unless specified otherwise.

Parameter Description

Tabs Name Name of tabs control (max characters). Used to identify the genie when on
a graphics page.

Width Pixel width of the tabs control at runtime.

Note: Leave the size of the genie at design time as 100 pixels, as it will be
automatically calculated at runtime.

Tab height Pixel height of the tabs control at runtime.

Vertical Pad- The vertical distance (in pixels) between the tab elements and the bottom
ding of the tabs control.

Tab Padding The horizontal distance (in pixels) between the edges and elements of a tab

Tab Min Width The minimum width allowed for a tab

Tab Max Width The maximum width allowed for a tab

Auto Width True/False drop down box. False is selected by default. Determines
whether the column width will be automatically adjusted to show full cell
content when the control is redrawn.

Icon Add Pad- Additional vertical padding for the display of icon relative to the text. Pos-
ding itive padding will move the icon further upward, and vice versa.

Refresh Rate The minimum (quickest possible) rate that the control will be redrawn.
The control is only redrawn as required upon changes to the layout, scroll-

1294
Chapter 50: Using the Library Controls

ing or other user initiated events.

Default Font The pre-configured font for tab text .

Selection Font The pre-configured font for a tab when it is selected .

Tab Line Style The display style of the separator between tabs, options are:
Dark
Light
None

Tab Select Style The display style for highlighting of selected tab:
Dark
Light
None

Allow Drag Sort Indicates whether to allow individual tabs to be repositioned by drag and
drop.

Allow Drag Indicates whether to allow individual tabs to be deleted by dragging it ver-
Delete tically away from the tabs control.

Tab Select Icon The icon to be displayed when a tab is selected. An icon must be pre-con-
figured as a symbol in your project. It is specified by the syntax of <symbol
library>.<symbol>.

Intialize Callback function that is called when the control initializes The callback
(Optional) function should return either TRUE (1) for success or FALSE (0) if unsuc-
cessful. By default, if the user specified function does not initialize, the con-
trol genie will retry the function a few time before giving up. This callback
only supports the #Name keyword which represents the name assigned to
the control genie.
Note:The initialization callback function may be called multiple times when-
ever the tab is re-initialized.

Left Mouse Callback function that is called when the user clicks the left mouse button
(Optional) No particular return value is expected from this function, and it supports
the following keywords in its argument list:
#Tab= tab ordinal number of the cell that is clicked
#Name = name assigned to the genie
#Ref = reference (assigned when tab is added) of the cell that is clicked
#TabDsp = tab number of the cell relative to the display that is clicked
#Icon =Icon number indicating the different areas within a tab when
clicked:
<=0 - text on tab is clicked
1- icon to left hand side of text is clicked
2- icon to right hand side of text is clicked
3- selection icon (only shows up when a tab selected) is clicked

Right Mouse Callback function that is called when the user clicks the right mouse but-
(Optional) ton. It uses the same specification as that of the Left mouse callback .

1295
Chapter 50: Using the Library Controls

Double Click Callback function that is called when the user double-click the left mouse
(Optional) button. It uses the same specification as that of the Left mouse callback.

See Also
Using Library Controls

Using the Tab Genie

There are two ways to populate data to the tabs:
1. Set cell value directly to the table.
2. Binding a Cicode function to return the value for the individual tabs.
Example 1: Set create tabs statically on initialization
1. The cicode sample below will be used in the following example. Open the Cicode
Editor and create a new cicode file, for example, _MyTab_Ex1.ci

//Callback function to respond to the initialization event of the tab genie

INT FUNCTION MyTabs_Init(STRING sTabs)
// Pre-populate with 2 auto-width tabs
LibTabs_AddTab(sTabs, "Tab1", 0);
LibTabs_AddTab(sTabs, "Tab2", 0);
RETURN TRUE;
END

2. From Graphics builder create a new page (e.g. Normal Tab Style Page)
3. When created, from the Object Toolbox select -> The Paste Genie icon
4. In the Paste Genie window select the lib_contols library
5. Select the Tabs genie. The genie is pasted onto the graphics page. In the tasb genie
dialog configure the following fields:

Parameter Description

Tab BarName MyTabs1

Width 400

Height 30

Initialize MyTabs_Init("#Name")

1296
Chapter 50: Using the Library Controls

6. Click OK to save the changes

7. Save the graphics page, and compile and run the project.
At runtime the tab layout should look like the following:

Example 2: Binding a Cicode function to return the value for the individual tabs
This is similar to setting a formula in Excel. With binding, cell values are not stored in
the tabs control. the control will call the provided Cicode function when it needs the
data.

1. Using the Cicode sample below, open the Cicode Editor and create a new Cicode file,
function.For Example:'MyTabs_Ex2.ci'

INT FUNCTION MyTabs_InitDyn(STRING sTabs)

// Bind callback function for data display
LibTabs_SetDataTask(sTabs, "Value", "MyTabs_GetCellValue", "^"#Name^",#Tab");

// Set the number of tabs for the control

LibTabs_SetCount(sTabs, 3);

RETURN TRUE;
END

//Function to return the value for a data cell

STRING FUNCTION MyTabs_GetCellValue(STRING sTabs, INT nTab)
RETURN "Dyn. value for Tab(" + nTab:# + ")";
END

2. As in example 1 add a tabs library control to the graphics page. In the Tabs Genie
property dialog configure the following fields:

Parameter Description

Tabs Name MyTabs2

Width 400

Height 30

Can Remove Tab TRUE

Initialize MyTabs_Initdyn("#Name")

1297
Chapter 50: Using the Library Controls

3. Click OK to save the changes

4. Save the graphics page, and compile and run the project.
At runtime the tab layout should look like the following:

See Also
Using Library Controls

Table Library Control

Table genie has the following parameters:

Note: All fields are mandatory unless specified otherwise.

Parameter Description

Table Name Name of table (max characters). Used to identify the genie when on a
graphics page

Width Pixel width of the table at runtime.

Note: Leave the size of the genie at design time as 100 pixels, as it will be
automatically calculated at runtime.

Number of rows Number of rows displayed on the page.

Header Height Pixel Height of header row in table display.

Row Height Pixel height of row in the table display.

Header Padding The pixel padding between the bottom of the header text (column name)
and the bottom of the header row

Row Padding The pixel padding between the bottom of the cell text and the bottom of
each row.

Column Pad- The pixel padding on the left-hand-side and right-hand-side of the cell text
ding relative to the width of each column.

Refresh Rate The minimum (quickest possible) rate that the control will be redrawn.
The control is only redrawn as required upon changes to the layout, scroll-
ing or other user initiated events.

1298
Chapter 50: Using the Library Controls

Header Font The pre-configured font for header text .

Cell Font The pre-configured font for cell text.

Selection Font The pre-configured font for cell text when it is selected .

Auto Width True/False drop down box. False is selected by default. Determines
whether the column width will be automatically adjusted to show complete
cell content when the control is redrawn.

Allow Selection True/False drop down. True is selected by default. Determines whether
allow the rows displayed on the control are selectable .

Note: The initialization callback function may be called multiple times

whenever the table is re-initialized.

Right Mouse Callback function that is called when the user clicks the right mouse button
(Optional) It uses the same specification as that of the Left mouse callback .

Double Click Callback function that is called when the user double-click the left mouse
(Optional) button It uses the same specification as that of the Left mouse callback.

1299
Chapter 50: Using the Library Controls

Note:The Table can be up to 62 columns (although the latter columns may not have
the column separators). For tables that return more columns that the limit, the first
62 columns will be displayed.

See Also
Using the Tag Table Library Control
Using Library Controls

Using the Table Genie

There are two ways to populate data to the table:
1. Set cell value directly to the table.
2. Binding a Cicode function to return the value for the individual cells of the table.
Example 1: Set cell value directly to the table
In this case, the value is stored with the table. You will need to set a new value to the
individual cell of the table if required.
1. The Cicode sample below will be used in the following example. Open the Cicode
Editor and create a new cicode file, for example, _MyTable_Ex1.ci

//Callback function to respond to the initialization event of the table genie

INT FUNCTION MyTable_Init(STRING sTable)
// Add your columns
LibTable_AddColumn(sTable, "Column1", 150);
LibTable_AddColumn(sTable, "Column2", 100);

// Add data directly to the table

MyTable_AddRow(sTable, "Value for Cell(1,1)", "Value for Cell(1,2)");
MyTable_AddRow(sTable, "Value for Cell(2,1)", "Value for Cell(2,2)");
MyTable_AddRow(sTable, "Value for Cell(3,1)", "Value for Cell(3,2)");

RETURN TRUE;
END
//Function to add a new row of data to the table
INT FUNCTION MyTable_AddRow(STRING sTable, STRING sCol1Value, STRING sCol2Value)
// Add data to the table, and the data is stored in the table
INT nRow = LibTable_SetCellValue(sTable, -1, 1, sCol1Value);
RETURN LibTable_SetCellValue(sTable, nRow, 2, sCol2Value);
END

2. From the Graphics Builder create a new page (E.g. the Normal Tab Style Page)
3. When created, from the Object toolbox select -> The Paste Genie icon.
4. In the Paste Genie window select the lib_controls library

1300
Chapter 50: Using the Library Controls

5. Select the Table genie. The Table genie is pasted onto the graphics page.
In the Table Genie property dialog configure the following fields:

Parameter Description

Table Name Table 1

Width 400 (all columns within the table are displayed. If left at 100 some col-
umns may not be displayed)

Number of rows 10

Header Height 18

Row Height 15

Header Padding 5

Row Padding 4

Column Padding 5

Horizontal Scrollbar

Vertical Scrollbar

Initialize MyTable_Init("#Name")

6. Click OK to save the changes

7. Save the graphics page and compile and run the project.
At runtime the table will look like the following:

Example 2: Binding a Cicode function to return the value for the individual cells of the
table
This is similar to setting a formula in Excel. With binding, cell values are not stored in
the table. The table will call the provided Cicode function when it needs data.

1301
Chapter 50: Using the Library Controls

1. The Cicode sample below will be used in the following example. Open the Cicode
Editor and create a new cicode file, for example, _MyTable_Ex2.ci

INT FUNCTION MyTable_InitDyn(STRING sTable)

// Add your columns
LibTable_AddColumn(sTable, "Column1", 150);
LibTable_AddColumn(sTable, "Column2", 100);

// Bind callback function for data display

LibTable_SetDataTask(sTable, "Value", "MyTable_GetCellValue", "^"#Na
#Col");

// Set the number of rows for the table

LibTable_SetPropertyInt(sTable, "RowCount", 9);

RETURN TRUE;
END
//Function to return the value for a data cell
STRING FUNCTION MyTable_GetCellValue(STRING sTable, INT nRow, INT nCol)
IF (nRow > LibTable_GetPropertyInt(sTable, "RowCount")) THEN
RETURN "";
END
RETURN "Dyn. value for Cell(" + nRow:# + "," + nCol:# + ")";
END

2. As in example 1 add a table library control to the graphics page.

In the Table Genie property dialog configure the following fields:

Parameter Description

Table Name MyTable2

Width 400 (all columns within the table are displayed. If left at 100 some col-
umns may not be displayed)

Number of rows 10

Header Height 18

Row Height 15

Header Padding 5

Row Padding 4

Column Padding 5

Horizontal Scrollbar

1302
Chapter 50: Using the Library Controls

Vertical Scrollbar

Initialize MyTable_InitDyn("#Name")

3. Click OK to save the changes

Compile and then run the project. At runtime the table will look like the following:

See Also
Using Library Controls

Table Row Library Control

Table Row genie has the following parameters:

Parameter Description

Table Name The name of the table (or its derived) genies that already exists on the
page.

Row Number of row as it appears on screen

See Also
Using Library Controls

Tag Table Library Control

Tag table genie has the following parameters:

Parameter Description

Tag Table Name Name of table (max characters). Used to identify the genie when on a
graphics page

1303
Chapter 50: Using the Library Controls

Width Pixel width of the table at runtime.

Note: Leave the size of the genie at design time as 100 pixels, as it will be
automatically calculated at runtime.

Number of rows Number of rows displayed on the page.

Header Height Pixel Height of header row in table display.

Row Height Pixel height of row in the table display.

Header Padding The pixel padding between the bottom of the header text (column name)
and the bottom of the header row

Row Padding The pixel padding between the bottom of the cell text and the bottom of
each row.

Column Pad- The pixel padding on the left-hand-side and right-hand-side of the cell text
ding relative to the width of each column.

Refresh Rate The minimum (quickest possible) rate that the control will be redrawn.
The control is only redrawn as required upon changes to the layout, scroll-
ing or other user initiated events.

Vertical Scroll- The name of the horizontal scrollbar genie on the page that allows the user
bar (Optional) to vertically scroll the content displayed on the control genie If you do not
require vertical scrolling, leave this field blank.

Header Font The pre-configured font for header text .

Cell Font The pre-configured font for cell text.

Selection Font The pre-configured font for cell text when it is selected .

Auto Width True/False drop down box. False is selected by default. Determines
whether the column width will be automatically adjusted to show full cell
content when the control is redrawn.

Allow Selection True/False drop down. True is selected by default. Determines whether
allow the rows displayed on the control are selectable .

1304
Chapter 50: Using the Library Controls

Right Mouse Callback function that is called when the user clicks the right mouse button
(Optional) It uses the same specification as that of the Left mouse callback .

Double Click Callback function that is called when the user double-click the left mouse
(Optional) button It uses the same specification as that of the Left mouse callback.

Note:The Table can be up to 62 columns (although the latter columns may not have
the column separators).

See Also
Using Library Controls

Using the Tag Table Genie

Use the Tag Table genie on a page when you want to be able to view variable tags where
the value of each tag changes constantly within your project.
The table does not automatically populate with variable tags unless a Cicode function is
called to add the tags to it. The Cicode function to add variable tag to the table is:
LibTagTable_AddTag(STRING sTable, STRING sTag)
Example 1: Populating the table with a button
1. From the Object toolbox select -> The Paste Genie icon.
2. In the Paste Genie window select the lib_controls library
3. Select the Tag Table genie. The tag Table genie is pasted onto the graphics page.
In the Tag Table Genie property dialog configure the following fields:

Parameter Description

1305
Chapter 50: Using the Library Controls

TagTable Name Tags

Width 300 ( all columns within the table are displayed. If left at 100 the value
column is not displayed)

Number of rows 20

Header Height 18

Row Height 15

Header Padding 5

Row Padding 4

Column Padding 5

Horizontal Scrollbar

Vertical Scrollbar Verbar (name of horizontal scrollbar placed on current page)

4. Click OK to save the changes

5. Paste the Vertical Scrollbar genie onto the graphics page. Position where the width of
the table might end.In the 'Library_Control - Scrollbar' dialog:

Parameter Description

Scrollbar Name Verbar

Height 100

Update on Drag True (default)

Allow double-click True (default)

Auto Hide False (default)

Hidden When False (default)

6. Click OK to save the changes

7. From the Object toolbox select the 'Button'object
8. Draw a button onto the page and configure as follows:

Action Up

Up Command LibTagTable_AddTag("VariableTags","Bit_1")

9. Click OK to save the changes

10. Compile and Run the project.
11. At runtime open the example page and click on the 'VariableTag' button
12. The table will refresh and the Bit_1 tag and corresponding value will be displayed.
Variations of the example include:

1306
Chapter 50: Using the Library Controls

l Adding a second button for another Tag e.g Bit_2

l Configuring the button to accept multiple tags( though space is limited). The Cicode
for the up command could be :
LibTagTable_AddTag("VariableTags","Bit_1");
LibTagTable_AddTag("VariableTags","Bit_2");
LibTagTable_AddTag("VariableTags","Bit_4")

l Configuring a button to launch a form field where you can enter the name of the tag:
The Cicode for the up command could be:
LibTagTable_AddTag("Variabletags", Input("Add Tag","Tag name:", ""));

Example 2: Initialized Cicode function in table configuration

1. Using the Cicode sample below, open the Cicode Editor and create a function.
Example:'MyTagTableInitialze' initialization function:

INT FUNCTION MyTagTableInitialize(STRING sTable)

INT hSession;
STRING sCluster;
STRING sTag;
INT nError;

// Add all variable tags to the tag table

hSession = TagBrowseOpen("", "Cluster,Tag", "Cluster:A,Tag:A", "");
nError = TagBrowseFirst(hSession);
WHILE (nError = 0) DO
sCluster = TagBrowseGetField(hSession, "Cluster");
sTag = TagBrowseGetField(hSession, "Tag");
LibTagTable_AddTag(sTable, sCluster + "." + sTag);
nError = TagBrowseNext(hSession);
END
IsError();
TagBrowseClose(hSession);

// Tell the tag table initialization is completed

RETURN TRUE;
END

Save the Cicode file.

2. As in example 1 add the Tag table library control and Vertical scroll bar to the graph-
ics page.
In the Tag Table Genie property dialog configure the following fields:

1307
Chapter 50: Using the Library Controls

Parameter Description

TagTable Name Tags

Width 300 ( all columns within the table are displayed. If left at 100 the value
column is not displayed)

Number of rows 20

Header Height 18

Row Height 15

Header Padding 5

Row Padding 4

Column Padding 5

Horizontal Scrollbar

Vertical Scrollbar Verbar (name of horizontal scrollbar placed on current page)

Initialze MyTagTableInitialize("#Name")

3. Click OK to save the changes

4. Paste the Vertical Scrollbar genie onto the graphics page. Position where the width of
the table might end.In the 'Library_Control - Scrollbar' dialog:

Parameter Description

Scrollbar Name Verbar

Height 100

Update on Drag True (default)

Allow double-click True (default)

Auto Hide False (default)

Hidden When False (default)

5. Click OK to save the changes

Compile and then run the project. At runtime the table will look like the following:

1308
Chapter 50: Using the Library Controls

See Also
Using Library Controls

Tree Library Control

Tree genie has the following parameters:

Parameter Description

Tree Name Name of table (max characters). Used to identify the genie when on a
graphics page

Width Pixel width of the table at runtime.

Note:Leave the size of the genie at design time as 100 pixels, as it will
be automatically calculated at runtime.

Number of items Number of items displayed on the page.

Item Height Pixel height of item in the tree display.

Show CheckBox True/False drop down box. False is selected by default. Determines
whether to show the checkboxes next to each of the tree items.

Window Inst True/False drop down box. True is selected by default. Determines
whether create a new instance of the equipment hierarchy on each
window where the equipment tree is displayed.

Refresh Rate The minimum (quickest possible) rate that the control will be redrawn.
The control is only redrawn as required upon changes to the layout,
scrolling or other user initiated events

Expand Level The minimum expand level of the tree hierarchy. Set to 0 to allow the
tree to be collapsed to its root items.

1309
Chapter 50: Using the Library Controls

Horizontal Scrollbar The name of the horizontal scrollbar genie on the page that allows the
(Optional) user to horizontally scroll the content displayed on the control genie If
you do not require horizontal scrolling, leave this field blank.

Vertical Scrollbar The name of the horizontal scrollbar genie on the page that allows the
(Optional) user to vertically scroll the content displayed on the control genie If
you do not require vertical scrolling, leave this field blank.

Label Font The font used for displaying the tree item label.

Item Font The font used for displaying the optional dynamic text next to the tree
item.

Symbol Library The name of the symbol library that contains the symbols for displayed
(Optional) next to the tree items.

Refresh Rate The minimum rate that the control will be redrawn.
Note: The control is only redrawn as required upon changes to the lay-
out, scrolling or other user initialized events.

Scan Delay The number of page scan delay before the genie is initialized at run-
time. This can be set to different number on different control genies to
stagger the initialization order.

Expand Level The minimum expand level of the tree hierarchy. Set this to 0 to allow
the tree to be collapsed to its root items.

Menu (Page) Name Name of page with menu items to display. If not specified it will default
to the menu configuration of the current window.

Intialize Callback function that is called when the control initializes. The call-
back function should return either TRUE (1) for success or FALSE (0)
for unsuccessful. By default, if the user specified function cannot ini-
tialize successfully, the control genie will retry the function a few time
before giving up. This callback only supports the #Name keyword
which represents the name assigned to the control genie.

Row Item Callback function that is called when the table initializes The callback
function should return a string value. The value returned will be dis-
played next to the tree item label. It supports the following keyword in
its argument list:
#Name - Name assigned to the genie
#Ref – the complete path of the tree item
#Label – the label of the tree item
#ItemDsp- The position of the item as displayed on screen
#IsChecked - The checked status of the tree item
#IsParent - Whether the item is expanded/collapsed
#ItemDsp - The position of the item as displayed on screen
#Node - The handle to the internal menu node object that represents
the tree item
#Level - The level of the tree item

1310
Chapter 50: Using the Library Controls

Selected Callback function that is called when a tree item is selected. No par-
ticular return value is expected from this function, and it supports the
same set of keywords as that of the Row Item function in its argument
list. Callback function that is called when the checkbox of a tree item is
clicked. No particular return value is expected from this function, and
it supports the same set of keywords as that of the Row Item function
in its argument list.

Checked Callback function that is called when a tree item is selected. No par-
ticular return value is expected from this function, and it supports the
same set of keywords as that of the Row Item function in its argument
list. Callback function that is called when the checkbox of a tree item is
clicked. No particular return value is expected from this function, and
it supports the same set of keywords as that of the Row Item function
in its argument list.

Left Mouse Callback function that is called when the user clicks the left mouse but-
ton No particular return value is expected from this function, and it
supports the following keywords in its argument list:
#Node - The handle to the internal menu node object that represents
the tree item
#Level - The level of the tree item

Right Mouse Callback function that is called when the user clicks the right mouse
button. It uses the same specification as that of the Left mouse call-
back .

Double Click Callback function that is called when the user double-click the left
mouse button. It uses the same specification as that of the Left mouse
callback.

Tree Reload Callback function that is called when the control is redrawn. No par-
ticular return value is expected from this function, and it supports the
following keywords in its argument list:
#Name = name assigned to the genie

See Also
Using the Tree Genie
Using Library Controls

Using the Tree Genie

Use the Tree genie on a page when you want to be able to view hierarchical data such as
a menu.

Note: Configure the Equipment Tree genie to view equipment in your system.

The example below illustrates how the genie can be used to view menu items within
your system for a particular page. A basic example, the implementation of the tree genie
can also be used to display dynamic generated menu items using Cicode.
Example 1: Displaying Pre-configured Menu Items

1311
Chapter 50: Using the Library Controls

Using the Example project, if you would like to display the menu items for the "_plant"
page, complete the following:
1. From the Object toolbox select -> The Paste Genie icon.
2. In the Paste Genie window select the lib_controls library
3. Select the Tree genie. The Tree genie is pasted onto the graphics page.
In the Tree Genie property dialog configure the following fields:

Parameter Description

Tree Name PlantMenu

Width 200

Number of rows 10

Row Height 15

Show CheckBox False (default)

Force Child False (default)

Window Inst True (default)

Expand Level 0

Menu (Page) Name _Plant

Selected MenuNodeRunCommand(#Node)

4. Click OK to save the changes

5. Save the page.
Compile and then run the project. At runtime the tree (menu) will look like the following:

Example 2: Displaying Dynamic Menu Items

1312
Chapter 50: Using the Library Controls

This is the more versatile usage of the menu tree where you can create an in-memory
menu hierarchy and populate it with your own data, and use the Tree control to display
it on the screen. The EquipTree genie is an example of such usage.
1. Using the Cicode sample below, open the Cicode Editor and create a callback func-
tion.
Example:'Mytree' initialization callback function:

INT FUNCTION MyTreeInitialize(STRING sTreeName)

// get the menu name for my instance of tree control
STRING sMenu = LibTree_GetProperty(sTreeName, "Menu");
// create a in-memory menu hierarchy
INT hMenu = MenuGetPageNode(sMenu, 1);
INT hNode;
// populate the menu hierarchy (only once)
IF (hMenu > -1) AND (MenuGetFirstChild(hMenu) < 0) THEN
// add level 1 item
hNode = MenuNodeAddChild(hMenu, "Item 1", "");
// add level 2 (sub) items
MenuNodeAddChild(hNode, "Sub-item 1", "");
MenuNodeAddChild(hNode, "Sub-item 2", "");
// add level 1 item
hNode = MenuNodeAddChild(hMenu, "Item 2", "");
// add level 2 (sub) items
MenuNodeAddChild(hNode, "Sub-item 1", "");
MenuNodeAddChild(hNode, "Sub-item 2", "");
// add level 1 item
MenuNodeAddChild(hMenu, "Item 3", "");
END
// return TRUE (1) to signal initialization completes
RETURN 1;
END

Save the Cicode file.

2. As in example 1 Paste the Tree Genie onto a graphics page.
In the Tree Genie property dialog configure the following fields:

Parameter Description

Tree Name TreeMenu

Width 200

Number of rows 10

Show CheckBox True

Force Child False (default)

1313
Chapter 50: Using the Library Controls

Window Inst True (default)

Expand Level 0

Menu (Page) Name MyMenu

Initialize MyTreeInitialize("#Name")

Selected MenuNodeRunCommand(#Node)

Assign the name of the in-memory menu hierarchy to the Menu name field of the genie
by assigning this name to the "Menu (Page) Name" field of the Tree control genie at con-
figuration time.
3. Click OK to save the changes
4. Save the page.
Compile and then run the project. At runtime the tree (menu) will look like the following:

See Also
Using Library Controls

Using User Callback functions with the Library Control Genies

Some fields in the genie allow the user to specify callback functions. Once specified,
these functions will be called when certain events happen to the control genies.
The syntax for specifying callback function is as follows:<Function name>(<comma sep-
arated argument list>)
Where
Function name = name of Cicode function
Argument list = arguments to the function with each separated by a comma (,)
In general the callback function should return non-empty value.
Only literals or predefined keywords, which vary among control genies, can be specified
in the argument list. When the function is fired, the literals and the interpreted value of
the keywords will be passed to the user specified function. For string argument, please
enclosed it with double quote character (“).
The following is an example of a valid callback specification:

1314
Chapter 50: Using the Library Controls

MyFunction(“#Name”,”MyPage”,100)

When the specified event occurs, the MyFunction function will be called. The value of
the #Name keyword after converted to the name assigned to the genie control, together
with the literals “MyPage” and 100, will be passed to the function that takes two
STRING and one INT arguments.
See Also
Using Library Controls

1315
Chapter 50: Using the Library Controls

1316
Using the CSV_Include Project

This section contains information on the CSV_Include project and

describes the following:
Introducing CSV_Include
Using Pages and Templates
Creating a New Project
"CSV_Include Reference" in the CitectSCADA Technical Reference

1317
1318
Chapter 51: Introducing CSV_Include
The CSV_Include Project is a preconfigured project that includes a set of templates and
pages styled for the Windows XP environment. It will help you reduce the time nec-
essary to configure a new project.
When a new CitectSCADA project is created, the CSV_Include project is automatically
incorporated as an included project. This means the project's templates and associated
content are available for implementation when creating your graphics pages in Graphics
Builder.
As well as including a standard graphics page template for creating plant mimics, the
project also includes predefined trend and alarm display pages, an administration tools
page, a file page for displaying text and Rich Text Format files, and a selection of popup
windows. They have identical navigation and alarm menus for consistent "look and
feel" across an entire project. The project even supports multimonitor displays, allowing
you to simultaneously display several graphics pages across several computer screens.

Note: Do not modify the CSV_Include project for use as a runtime project. It will not
compile 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, so you will lose
changes you make to the project when this happens.

Where to Find Information

Use the following links for details about the preconfigured content in the CSV_Include
Project:
l Predefined pages and templates. See Using Pages and Templates.
l Common toolbars. See Common Toolbars.
It also describes the processes used to create a project based on CSV_Include:
l Creating a new project. See Creating a New Project.
l Creating pages. See Creating Pages.
l Creating custom menus. See Creating Custom Menus.
l Creating an alarm group. See Creating an Alarms Group.
l Creating a trend group. Creating a Trends Group.

1319
Chapter 51: Introducing CSV_Include

Reference material is also included, describing the citect.ini parameters and Cicode func-
tions available to customize a project.

1320
Chapter 52: Using Pages and Templates
When you create a new project based on CSV_Include, the following templates and
pages are available for you to use as you create your graphics pages. This section
describes the pages and their buttons, menus, and tools.
The CSV_Include project has the following templates:

Template Name Description

Normal Standard graphics page

Alarm Active alarm page

Disabled Disabled alarm page

Summary Summary alarm page

Hardware Hardware alarm page

Trend Trend page (8 pens)

Double Trend Split-page trend page (16 pens)

File Displays a file

Admin Tools Engineering tools page

Poptrend Popup trend

Instanttrend Instant trend

Popup_Small Small popup window

Popup_Mid Medium popup window

Popup_Large Large popup window

Popup_Xlarge Extra large popup window

The project also includes the following preconfigured pages:

1321
Chapter 52: Using Pages and Templates

Page Name Description

CSV_AdminTools Engineering tools page

CSV_Alarm Active alarm page

CSV_AlarmDisabled Disabled alarm page

CSV_AlarmSummary Summary alarm page

CSV_AlarmHardware Hardware alarm page

CSV_Trend Trend page (8 pens)

CSV_TrendDouble Split-page trend page (16 pens)

CSV_File File page

See Also
Creating a New Project
Creating Pages

Normal Page Template

A template designed for creating user-necessary content and plant mimics. This page
contains the standard navigation and alarm toolbars featured on CSV_Include tem-
plates. If you are creating a project based on CSV_Include, use this template for your
standard graphics pages.
The Normal template creates a page in 1024 x 768 display format without a title bar, the
default size for pages in the CSV_Include project.
See Also
Creating Pages

Alarm Page Templates

Templates are included for the following types of alarm displays:
l Active Alarm Page (Alarm): Used to create a page displaying audible alarms that are
unacknowledged or acknowledged and still in alarm state. The preconfigured page
CSV_Alarm is based on this template.

1322
Chapter 52: Using Pages and Templates

l Hardware Alarm Page (Hardware): Used to create a page displaying details of any
system errors that are unacknowledged or acknowledged and still in alarm state, for
example, if communications are lost, if Cicode can't execute, if a graphics page is not
updating correctly, or if a server becomes inoperative, this page will alert you. The
preconfigured page CSV_AlarmHardware is based on this template.
l Disabled Alarm Page (Disabled): Used to create a page displaying alarms that are
presently disabled in the system. The preconfigured page CSV_AlarmDisabled is
based on this template. The alarms will appear on this page when they have been dis-
abled from the normal alarm system due to a maintenance shutdown, nuisance trip-
ping etc.
l Alarm Summary Page (Summary): Used to create a page displaying a historical log
of alarms that have occurred. The preconfigured page CSV_AlarmSummary is based
on this template. This page can be used for troubleshooting purposes.

Common functionality
The alarm page templates share panels to the left of the alarms list that support the fol-
lowing functionality:
Acknowledge Tasks
Offers the option to:
l acknowledge alarms on the current page
l acknowledge just the selected alarm
l silence an audible alarm.
It is featured on the Active Alarms page and the Hardware Alarms page.
Alarm Page Tasks
Allows the user to navigate through the list of alarms a page at a time. The blue box indi-
cates if more than one page is available to view.
Alarm List Filter Tasks
Allows the user to filter the current list based on plant area or by alarm category. To
apply a particular filter, you first configure an alarm group.

Trend Page Templates

The CSV_Include project includes templates for the four following types of trend display:

l Trend: An eight-pen trend display. The preconfigured page CSV_Trend is based on

this template.

1323
Chapter 52: Using Pages and Templates

l DoubleTrend:A 2 x 8-pen trend display spread across a divided screen. The pre-
configured page CSV_TrendDouble is based on this template.
l PopTrend: A four-pen pop-up display that can be launched from other graphics
pages.
l InstantTrend: A popup window for instant display of a variable tag.

Note: To implement the Instant Trend feature in one of your own projects, you
need to add the CSV_InstantTrend project as an Included project. (See Including a
project in the current project.)

The Trend, Double Trend and PopTrend displays allow you to select and display trend
tags from your CitectSCADA project on a color-coded linear chart. Being based on infor-
mation coming from the CitectSCADA Trends Server, these displays are supported by
stored historical data that can be recalled if necessary.
The Instant Trend display is unique as it allows the selection of up to four variable tags
for display. This allows you to visually monitor a tag without having to set it up within
your CitectSCADA project as a trend tag. You can even load tags directly into the dis-
play by hovering the mouse over a tag value on a graphics page and keying in a plus
sign (see the parameter [TrendX]KeySeq).
There are limitations to this feature, however, as data is only available from the time the
display is launched and is lost when the display is closed. The Instant Trend feature has
a duration setting that limits the amount of time the display can remain open, you can
adjust the default setting for this via the parameter [TrendX]Duration.
For details on implementing instant trending, see Setting Up Instant Trending.

Common functionality
The trend display templates share common controls that support the following func-
tionality:
l Selected Trend Field
l Range/Scale markers
l Span markers
l Set span button
l Trend cursor
l History mode
l Zoom
l Autoscale
l Scale defaults

1324
Chapter 52: Using Pages and Templates

l Export to file
l Paste to clipboard
l Plot trend
l Trend group

Selected Trend Field

Displays information relating to the trend tag(s) currently being mapped in the trend
chart, including a name, the current value and the scale range.

The field is color coded to match the graphical display, hence the colorful nature of the
listed fields.
To load a trend into a Selected Trend field, right-click the field. A menu appears allow-
ing you to select a trend or clear the field. Once you have loaded your selected trends,
you can make a particular pen the focus of the graph by clicking this field. An arrow to
the left of the field indicates it is currently the focus trend.
This field appears slightly different when using instant trending, as the graph will be dis-
playing current data for a variable tag, not a trend tag. In this case, the selection field
appears as below, with the tag name, current value, description and sample period dis-
played.

Range/Scale markers
These markers appear along the vertical axis and show the scale of the display for the
currently selected pen, highlighting the lowest to highest values for the scale range.

1325
Chapter 52: Using Pages and Templates

Span markers
These markers appear along the horizontal axis, and show the span of the trend display
in time. The left-hand marker shows the current start time and date, the right shows the
current end time and date. Typically the right-hand marker shows the current time; how-
ever, this can be affected by zooming or displaying in Historical mode.

Set span button

Displays an input dialog that sets the span of the current display. When you enter a unit
of time, the display will cover the defined period ending with the current time.

Trend cursor
Allows you to select a location on the graphical trend display and determine the time
and date for that particular point. The arrows to the left end of the display allow you to
move the cursor left or right. The Exit icon to the right closes the trend cursor.

History mode
Allows you to scroll forward or backward through a graph of a trend tag's history. To
switch into History Mode, select the Display History Mode checkbox. The display
changes to lower version of the control shown to the left.
The four buttons allow you to move backwards or forwards through the trend graph,
with the two outer buttons shifting a page at a time, and the two inner buttons shifting
half a page. The clock icon allows you to edit the end time for the historical display.
Deselecting the box returns to the normal trend view.

1326
Chapter 52: Using Pages and Templates

Zoom
Zooms in on or out of the current display. Zoom in (+) increases the focus of the display
and continues zooming in on subsequent clicks. Zoom out (-) returns to the default.

Autoscale
Autoscales the current view, which means the scale adjusts to the lowest and highest
values reached.

Scale defaults
Returns the scale for the display to the default for the currently selected trend.

Export to file
Exports the data for the currently displayed trend to a file. A Save As dialog will appear,
allowing you to save the data as a D Base III file (.DBF file), a comma separated value
file (.CSV file) or a text file (.TXT).

Paste to clipboard
Sends the data for the currently displayed trend to the Windows clipboard.

Plot trend
Plots the trend to a printer. Use this button to print a trend graph instead of the Print
Page button. A dialog allows you to configure the printer setup.

1327
Chapter 52: Using Pages and Templates

Trend group
Allows you to load a trend group. A dialog lists the currently configured groups and
allows you to clear currently displayed variable tags. See Creating a Trends Group.

File Page Templates

Use this template to create a page that can display text (.txt) or rich format text (.rtf) files.
To understand how a file page works, you need to distinguish between the file page and
the file that is presented on the page; for the file page merely acts as a blank palette to a
variety of files.
The file page is displayed whenever the function CSV_Nav_File is called. When executed,
CSV_Nav_File determines the file that is to be displayed on the file page, its location, the
title applied to the page, and whether or not the file is editable.
For example, you may configure a menu item that calls up the following:

?CSV_Nav_File(MyPageTitle,[Run]:\file.txt,2)

This would call up the file page, put the title "MyPageTitle" on the title bar, load the file
called File.txt from the Run directory, and allow the file to be edited (with the last argu-
ment set to 2, the file can be saved).
The parameter [Navigation]FilePage determines the page that's used as the palette for
this process. The preconfigured page CSV_File is the default. You can change the setting
for Navigation[FilePage], however, you need to verify that any page you specify for this
parameter is based on the CSV_File template, otherwise CSV_Nav_File will not be able
to execute properly.

Admin Tools Page Template

This template is used to create a page that features network and local machine statistics,
and allows the user to launch Citect configuration tools and Windows applications. The
preconfigured page CSV_AdminTools is based on this template.
The panels to the left of this page launch the following configuration tools:
l Windows applications: Allows the user to launch the listed Windows Applications
from within the runtime environment.

1328
Chapter 52: Using Pages and Templates

l Citect Configuration: Allows the user to launch the listed Citect configuration tools
from within the runtime environment. This includes viewing and editing the
Citect.INI file, running the Computer Setup Wizard, creating alarm groups, trend
groups, and launching the Menu Configuration tool.
l Citect Kernel: Launches the various components of the Citect Kernel, allowing the
system to be debugged from within the runtime environment.
l System / Hardware: I/O Device Stats launches a dialog displaying I/O Device sta-
tistics. The Next and Previous buttons allow you to step through the I/O Devices con-
nected to the system, while the Search button allows you to view statistics for a
particular device.
The Tag Debug tool allows you to browse a list of available tags and read the current
value for a selected tag. Depending on your access privileges, you may also be able to
write a new value to the tag.
The right-hand side of this page displays statistics about the CitectSCADA system:
l System Information: Provides details of the CPU usage, memory usage and available
disk space for the current runtime machine.
l Citect Information: Provides information about the CitectSCADA system including
version information and the number of trend, alarm and report clients currently con-
nected
l I/O Server: Provides information about the status of the CitectSCADA I/O Server your
system is connected to. The name of the I/O Server machine appears in the title bar of
this panel. The information displayed includes:
l Average: Overall average response time (ms).
l Maximum - the overall maximum response time (ms)
l Minimum: Overall minimum response time (ms).
l Read Request: Total read requests per second.
l Read Physical: Total physical read requests per second.
l Write Request: Total write requests per second.
l Write Physical: Total physical write requests per second.
l Reset button:lclears the current values and recalculates them.

Common Toolbars
Pages in the CSV_Include project include common toolbars for easy navigation and fea-
ture access, as well as a consistent appearance.
The following three toolbars remain on screen during operation:

1329
Chapter 52: Using Pages and Templates

l Navigation toolbar: Provides navigation buttons and direct access to key pages such
as the Trends page and Admin Tools page.
l Alarm toolbar: Provides access to Alarms pages and displays the last three active
alarms.
l Custom Menus toolbar: Provides menus capable of navigating to a specific page or
calling a Cicode function. The content of the menus is generated at runtime using a
lookup table.

See Also
Navigation Toolbar
Alarms Toolbar
Creating Custom Menus

Navigation Toolbar
The Navigation toolbar includes buttons that allow the user to move between a project's
pages. If the current user has insufficient privilege or there is no option configured for a
particular button, it is unavailable to the user.

Icon Name Description

Back Goes back to the page displayed before the current

page. The arrow to the right of the button allows you

1330
Chapter 52: Using Pages and Templates

to select from a menu of recently visited pages. You

can set the maximum number of pages included in
this menu by adjusting the parameter [Navigation]
LastPageStackSize.

Forward Goes forward to the page that was displayed prior to

the back button being pressed. The arrow to the right
of the button allows you to select from menu of pages
recently navigated back from. You can set the max-
imum number of pages included in this menu by
adjusting the parameter [Navigation]Last-
PageStackSize.

Parent Changes the display to the "parent page" of the cur-

Page rent page. You can assign a parent page to a graphics
page by setting an environment variable in Graphics
Builder. To do this, open the page you want to assign
a parent to. Go to the properties dialog for the page
(File | Properties), and click the Environment tab.
Add a new variable called "ParentPage" with a value of
the page name of the parent page.

Pre- Moves backwards or forwards through pages in a

vious/Next browse sequence if a sequence is configured. To con-
figure a browse sequence, go to the Page Properties
dialog (File | Properties) for each page in the
sequence and set the Next and Previous fields on
the General tab accordingly.

Home Displays the "home" page. By default, this page is the

startup page CSV_Start. To change the home page to
a different page, use the [Navigation]HomePage
parameter.

Trends Displays the "trend" page. By default, the pre-

Page configured page CSV_Trend appears when this but-
ton is pressed. To display a different page, adjust the
parameter [Navigation]TrendPage.

Network Displays a page called "Network" if one exists. By

Page default, this page does not exist, which means the but-
ton will not appear. To use this button to call a func-
tion, or to launch a page with a name other than
network, adjust the parameter [Navigation]Net-
workPage.

Tools Displays the Admin Tools page, named CSV_Admin-

Tools. You can adjust the parameter [Navigation]
ToolsPage to call a function with this button or change
the page displayed; however, this is not rec-
ommended. This button also features a menu to

1331
Chapter 52: Using Pages and Templates

launch the Tag Debug tool and Instant Trend display.

It also allows you to switch tool tips on and off.

Print Page Prints the current page. The parameter [Printer]

Port needs to be configured correctly for printer selec-
tion.

Login Displays the standard CitectSCADA login prompt. The

menu to the right offers extra options such as Logout,
Change Password, Edit User (restricted by login) and
Create User (restricted by login).

Help This button can be configured to display user assis-

tance information for your project. By default, it will
point to the topic Adding user assistance to a page
within the CitectSCADA help. This topic explains how
to change this default behavior within your own
project, by either disabling the button, or configuring
it to connect to your own HTML help file.

See Also
Alarms Toolbar
Creating Custom Menus

Alarms Toolbar
The alarms toolbar provides access to current alarm information and navigation buttons
for single-click access to alarm pages. It also includes standard CitectSCADA prompt
and current date and time.

The alarms toolbar contains the following features:

Icon Name Description

n/a Last The center panel of the toolbar displays the last three alarms trig-
Alarms gered within the system, providing the operator with an immediate
visual cue to alarm occurrences.

You can modify the format of this list and control which alarms
appear. For example, you can set the list to only display alarms of a

1332
Chapter 52: Using Pages and Templates

particular type, category or priority.

For details, see the parameters LastAlarmFmt, Las-

tAlarmCategories, LastAlarmPriorities, and LastAlarmType.

Active Changes the display to the active alarms page, CSV_Alarm. This
Alarms button is animated and will blink when there is an unac-
knowledged alarm in the system. This action performed by this
button is determined by the parameter [Navigation]AlarmPage.

Alarms Changes the display to the alarm summary page, CSV_Alarm-

Sum- Summary, which provides a historical log of alarm occur-
mary rences.This action performed by this button is determined by the
parameter [Navigation]SummaryPage.

Hard- Changes the display to the hardware alarms page, CSV_Alarm-

ware Hardware. This is an animated button which will blink when an
Alarms unacknowledged hardware alarm occurs. This action performed
by this button is determined by the parameter [Navigation]Hard-
warePage.

Dis- Changes the display to the disabled alarms page, CSV_Alarm-

abled Disabled. This action performed by this button is determined by
Alarms the parameter [Navigation]DisabledPage.

Alarm Silences the audible alarm buzzer that sounds when an alarm
Silenc- occurs. See Implementing Audible Alarms.
e

Creating a Privileged User

Some CSV_Include project content is restricted via a user login. Without a valid login,
some project functionality will be disabled. For example, the Tools page is mostly inac-
tive if you log in as a user with restricted privileges.
By default, the following elements within the CSV_Include project are restricted by global
privileges.

Element Global Privilege Associated Function

Admin Tools page 8 [Privilege]EngTools

Editing users 8 [Privilege]EditUser

1335
Chapter 53: Creating a New Project

Project shutdown 0 [Privilege]Shutdown

Acknowledge alarms 1 [Privilege]AckAlarms

Disable alarms 8 [Privilege]DisableAlarms

When configuring a CSV_Include project, check that your users have appropriate access
to the available functionality. Verify that your users can acknowledge alarms if nec-
essary, and that they have access to the full functionality of the Admin Tools page.
To adjust the global privileges for the elements previously listed for a more complex
security architecture, adjust the [Privilege] parameters in the Citect.ini file. Click the rel-
evant link in the previous table above for details.
See Also
Running the Computer Setup Wizard

Running the Computer Setup Wizard

As with any CitectSCADA project, you need to run the Computer Setup Wizard on any
machine where a CSV_Include project will be run. See Running the Computer Setup Wiz-
ard for more information.
How you set up a computer using the Wizard is mostly up to you; however, due to
some necessary settings, you need to run the Computer Setup Wizard as a custom setup.
The Wizard pages you need to configure are:
l Events Setup Page
l Security Setup - Control Menu Page

Events Setup page

The CSV_Include project includes three preconfigured events.
l CSV_TrendXClient: enables the Instant Trend feature.
l CSV_TrendXServer: enables the Instant Trend feature.
l CSV_AlarmClient: enables audible alarm siren.
Select and enable the necessary events listed above. To support the instant trend feature,
you need to enable both the CSV_TrendXClient and CSV_TrendXServer events on the com-
puter acting as your Trends Server. Only CSV_TrendXClient needs to be enabled on your
runtime machines. To support audible alarms, enable CSV_AlarmClient.
select every of the event unless you need to disable the associated functionality.

1336
Chapter 53: Creating a New Project

Security Setup - Control Menu page

Provides a Display Title Bar option. As the CSV_Include pages feature an XP-styled title
bar, deselecting this option allows your project to run successfully in full-screen mode
(run CSV_Include-based projects in fullscreen mode).
See Also
Creating a Privileged User
Setting Up Instant Trending
Implementing Audible Alarms

Setting Up Instant Trending

Instant trending allows you to monitor a variable tag visually from your CitectSCADA
project, without configuring the tag it as a trend tag. Without the support of the Citect-
SCADA Trends Server to facilitate this functionality, instant trending requires you to per-
form the following setup:
1. Include the CSV_InstantTrend project. To implement the Instant Trend feature in
one of your own projects, you need to add the CSV_InstantTrend project as an
Included project. (See Including a project in the current project.)
2. Enable the CSV_TrendX events. As described in Running the Computer Setup Wiz-
ard, you need to enable the events CSV_TrendXClient and CSV_TrendXServer for instant
trending to work. Verify that both events are enabled on the Trends Server computer,
and that CSV_TrendXClient is enabled on any runtime machines that will use instant
trending.
3. Call the Instant Trend display. Verify that any buttons or menu items you configure
to launch the Instant Trend display call the function CSV_TrendX_Display(). call this
function with no arguments set, as this will implement the default settings. This
loads the correct page with appropriate display settings.
4. Set the default display duration. The Instant Trend window only stays open for a set
period of time. Use the [TrendX]Duration parameter to adjust the default period of
time as appropriate.
5. Configure the Tag Selection dialog. You can decide whether or not to load a list of
current tags into the Tag Selection dialog when using instant trending. Having no
tags appear in the selection dialog might be useful if your project has many tags. See
the parameter [TrendX]TagListEnable in the Computer Setup Editor online help.
6. Check the key sequence used to load tags. You can load tags directly into the
Instant Trend display by putting the mouse cursor on a tag value on a graphics page
and pressing the plus (+) key. However, make sure that this key sequence does not

1337
Chapter 53: Creating a New Project

clash with other application functionality. To change the key sequence for this fea-
ture, see the parameter[TrendX]KeySeq.

Displaying a Project on Multiple Monitors

The CSV_Include project can display several pages simultaneously across multiple com-
puter screens. If your hardware can run multiple monitors off a single computer, the
CSV_Include project can display a different page on up to six screens at a time.
To successfully run your project across multiple monitors, adjust the following param-
eters:
l [MultiMonitors]Monitors. Adjust this parameter to indicate how many monitors you're
project will be running on.
l [MultiMonitors]StartupPagen. This parameter determines which page will appear on
each monitor at startup. You have to duplicate this parameter for each monitor. For
example, StartupPage1 determines the page that appears on the first monitor at
startup, StartupPage2 determines what appears on the second monitor, and so on.
Many types of hardware support multiple-monitor display. The CSV_Include project has
been tested on a PC with multiple outputs from a single video card, but not on other
architectures. The ability to display project pages on multiple screens might be affected
by hardware architectures that have not been tested.

Implementing Audible Alarms

The CSV_Include project offers support for audible alarms. You can configure a project
so that a selected wav file is sounded whenever an alarm of a particular priority is trig-
gered. You can even assign different sounds to different alarm priorities, allowing the
urgency of an alarm to be determined from its sound.
To implement audible alarms in your project:

1. Verify that the alarms you want to trigger an audible alert are assigned to a category
and given a particular priority.
2. Adjust the parameter [Alarm]Soundn. This parameter determines the wav file used
when an alarm sounds, based on the priority of the alarm (n). For example, [Alarm]
Sound1 identifies the .wav file that will be sounded whenever a priority 1 alarm is trig-
gered.
3. If necessary, adjust the parameter [Alarm]SoundnInterval. This parameter determines
how long the selected wav file sounds, based on the priority of the alarm (n). For

1338
Chapter 53: Creating a New Project

example, [Alarm]Sound1Interval sets the length of time a priority 1 alarm is sounded

for.
4. Enable the CSV_AlarmClient event on any machine you want an audible alert
sounded from. You can enable this event from the Events Setup page of the Com-
puter Setup Wizard. See Running the Computer Setup Wizard.
5. Verify that your users have appropriate privileges associated with their login to
acknowledge alarms, otherwise they will not be able to silence an alarm. See Creating
a Privileged User and the parameter [Privilege]AckAlarms.
See Also
Alarm Page Templates

Creating Pages
When considering the pages necessary for your project, first determine if you can use
any of the predefined pages in the CSV_Include project:

Page name Description

CSV_Trend Default 8-pen Trend page, called from the Trend button on the Navi-
gation toolbar.

CSV_Alarm Active Alarms page, called from the Alarms toolbar.

CSV_Alarm- Hardware Alarms page, called from the Alarms toolbar.

Hardware

CSV_Alarm- Disabled Alarms page, called from the Alarms toolbar.

Disabled

CSV_Alarm- Alarms Summary page, called from the Alarms toolbar.

Summary

CSV_Admin- Admin Tools page, called from the Tools button on the Navigation tool-
Tools bar.

There are also several pages that are accommodated by the Navigation toolbar that
you'll need to create if necessary. Decide if the following pages would be useful in your
project and create them using the appropriate name:

Page Description
name

1339
Chapter 53: Creating a New Project

Home Called from the Home button on the Navigation toolbar.

Network Called from the Network button on the Navigation toolbar. This button does
not display if a page called "Network" does not exist.

The links between the pages listed and the buttons that call them are defined by the
[Navigation] parameter settings within the Citect.ini file. If you want a button to call a
page with a different name, adjust these parameter settings. For details see "CSV Include
Parameters" in the CitectSCADA Technical Reference.

Creating new pages

Normal and Popup templates are designed with minimal content to enable the pre-
sentation of customer-necessary information and plant mimics.
Pages are created based on these templates within Graphics Builder by choosing the nec-
essary template from the Use Template dialog (File | New Page). You can access the
CSV_Include templates by selecting csv_xp_01 from the Style field.

Note: If you try to launch a CSV template from within Citect Explorer, you need to
drill down to [Project Name]/Graphics/Templates/csv_xp_01/XGA to locate it.

The CSV_Include project can add rollover buttons to pages without drawing and con-
figuring multiple elements. You can add text to a page that has a button appear behind
it whenever the cursor passes by adding the function DspButtonRollOver() to a button's
visibility property. No arguments are necessary.
See Also
Adding user assistance to a page

Adding user assistance to a page

The CSV_Include project includes a Help button on the Navigation toolbar. As you
create your pages, you can configure this button to provide information to the user about
the content of a page, and its supported functionality.
The information provided to your operators needs to be be created as individual HTML
pages and compiled into a HTML help file (.chm). The compiler necessary to create a
.chm file is available for download from the Microsoft Developer Network (MSDN). Go
to http://msdn.microsoft.com and search for "HTML Help Workshop". An SDK is avail-
able that includes the necessary downloads and information about creating an HTML
help project.

1340
Chapter 53: Creating a New Project

Once you have created a .CHM file, it is recommended you place it in the project direc-
tory.
To configure the help button for a project page

1. Select the project you've created in Project Explorer.

2. Go to Project Editor and select Parameters from the System menu. The Parameters
dialog will appear.
3. In the Section Name field, type in "HelpButton".
4. In the Name field, identify the page you would like to add help to using the fol-
lowing format:

SetTopic:<PageName>

where <PageName> is the name of the page included in your CitectSCADA project. Do
not include a space after the colon.
5. In the Value field, identify the associated HTML Help file and topic using the fol-
lowing format:

where:
l <HelpFileName> is the name of the compiled HTML Help file you've created
(for example MyHelpFile.chm)
l <HTMLPageName> is the name of the compiled HTML page you'd like dis-
played as a help topic (for example Help_Topic.html).
6. If necessary, add a Comment.
7. Click Add.
The help button will now launch the identified HTML file with the selected topic show-
ing.
To disable the help button for a project page

1. Select the project you've created in Project Explorer.

SetTopic:<PageName>

1341
Chapter 53: Creating a New Project

where <PageName> is the name of the page included in your CitectSCADA project. Do
not include a space after the colon.
5. In the Value field, type in DISABLED.
6. If necessary, add a Comment.
7. Click Add.
The help button on the identified page will now be unavailable during runtime.

Note: Do not duplicate this parameter for a single project page.

Creating Custom Menus

The Custom Menu Toolbar, located directly beneath the page title bar, allows you to
create drop-down menus capable of calling a Cicode function or navigating to a specific
page (i.e. to a specific plant mimic).
You can disable the menu bar on pages by adjusting the parameter [Page]MenuDisable. If
you need to disable the menu on a particular page, you can apply this parameter as an
environmental variable. To do this, open the necessary page in Graphics Builder, go to
the Properties dialog (File | Properties), and insert the parameter on the Environment
tab.

Menu Configuration tool

The content of the menus can be configured via the Menu Configuration tool, which is
launched from the Citect Configuration panel of the Admin Tools page.
The Menu Configuration tool has two panels. The panel on the left represents the menus
configured for the current project in a directory structure. The panel on the right includes
information about the item currently selected in the left panel.
The directory in the left panel is a graphical representation of a DBF lookup table that
forms the basis of the menus displayed at runtime. The hierarchical structure is deter-
mined by the following fields within this table:

Page The page field is defined as either "Generic", or the name of a page within
the project. Generic specifies that the menu is associated with every page, a
specific page name indicates the menus that will appear just on that par-
ticular page.

1342
Chapter 53: Creating a New Project

Men- Name(s) of the menus included on the specified page.

uname

Men- Item(s) that appear within each menu.

uitem

Sub- Submenus that appear in a menu (optional). Adding a sub menu auto-
menu matically removes the action defined for the menu item it is branched from,
as the parent becomes a placeholder for the list of sub menus.

The Menu Names that appear are the five defaults: Pages, Trends, Alarms, File and
Tools.
The fields you can expect to see associated with an item, as defined in the DBF table, are
as follows:

Action Either the name of the page to display or a Cicode function. If specifying a
Cicode function, it needs to be prefixed by a question mark ("?"). To invoke a
Cicode function that has arguments from the Menu System, use the following
format: function name, space, comma-separated list of string arguments. For
example, ?LoadPav dP45.pav.

Priv- The login privilege necessary to trigger the associated action.

ilege

Dis- Indicates if the item is currently disabled (embossed). For example, if the cur-
abled rent login does not meet the necessary privilege set for the item (see above),
this field will be set to True and the menu item will appear embossed to indi-
cate its currently not active.

Check- Indicates if the menu item is currently checked (with a tick). True indicates
ed

Btnwi- Specifies the width of the button (optional).

dth

Building custom menus

Creating a custom menu entails adding the necessary pages, menus, and items to the
Configure Menus directory structure, and then assigning the necessary action and priv-
ileges to each item. This is achieved via the right-click menu.
Right-click a branch in the directory to display the context menu, which shows the avail-
able actions for the current selection. The right-click menu includes the following actions:

1343
Chapter 53: Creating a New Project

Edit Item Available when an Item is selected. This option displays the
Edit Item dialog, which allows you to define the fields asso-
ciated with the current Item. In particular, it allows you to
specify the action associated with the item. (See Editing an
item)

New Page Adds a new page to the menu configuration. Use this option
to create new custom menus designed specifically for a par-
ticular page in your project. The name you give the new page
in the menu configuration needs to be identical to the name of
the page in your project that you want the menus to be
applied to.

New Button Adds a new menu button to the current page.

New Item Adds a new item to the currently selected menu.

New Sub Item Adds a sub item to the currently selected item. A subitem
overwrites the action configured for its parent item. The par-
ent item becomes a label identifying the list of Sub Items
assigned to it.

Delete Page Deletes the currently selected Page from the menu con-
figuration.

Delete Button Deletes the currently selected Menu Button from the menu
configuration.

Delete Item Deletes the currently selected Item from the menu con-
figuration.

Delete Sub Item Deletes the currently selected Sub Item from the menu con-
figuration.

Copy page Copies the currently selected page and pastes it to the end of
the menu configuration. This option is useful if you want a
page to include the generic page menu configuration, but
with additional menus that only appear when the particular
page is displayed. To do this, copy the generic page, rename
it to match the page you want to customize the menus for,
then add the necessary menus and items.

Save Saves the current menu configuration.

Editing an item
You configure a menu item's functionality by using the Edit Item Menu dialog.

1344
Chapter 53: Creating a New Project

Use this dialog to identify the action an item will trigger, be it navigation to a specific
page, or execution a function. To launch this dialog, right-click the item to configure and
choose Edit Item from the menu.
fill out the fields as follows:

Action Indicates the name of the page to display, or a Cicode function. If specifying a
Cicode function, it needs to be prefixed by a question mark ("?").

Priv- The login privilege necessary to trigger the action. Only users with appro-
ilege priate access privileges will be able to use this item.

Dis- As this setting is determined automatically depending on the current user's

abled access privileges, leave this set to False unless you want the item disabled by
default.

Check- Leave this set to False unless you want the item checked by default.
ed

But- Leave this set to zero (0) as this sets the menu button to the appropriate
ton width. To set a specific width for the button, input the width in pixels.
Width

Creating an Alarms Group

The CSV_Include project allows you to use "alarm groups" to display a specific set of
tags defined by the alarm category and area settings configured within the runtime
CitectSCADA project.
For example, you could create a group containing category one alarms. This group could
then be used as a filter to create a list of the category one alarms currently displayed on
the Active Alarms page.
Alarm groups are configured by clicking the appropriate link on the Citect Configuration
panel to the left of the Admin Tools page. The functionality can also be added to a cus-
tom menu for easier access.
To configure an alarm group:

1. Go to the Admin Tools page of a runtime project by clicking the Tools button.
2. Select Configure an Alarm Group from the Citect Configuration panel. The Configure
Alarm Groups dialog appears.

1345
Chapter 53: Creating a New Project

3. In the Alarm Group Description box, type the name you want to use to identify the
group.
4. In the Categories box, list the alarm categories configured in the CitectSCADA run-
time project that you want to use to define the group.
5. In the Area box, type the areas defined in the CitectSCADA project you want to use to
define the group.
6. Click Add.
The information to the right of the dialog indicates how many alarm groups are con-
figured and where you are currently positioned in this list. You can scroll through the
list of configured groups by using the up and down arrows.
To change a group, locate it in the list, change it as appropriate, then click Replace.
See Also
Creating a Trends Group

Creating a Trends Group

The CSV_Include project allows you to use "trend groups" to display a specific set of
trend tags. A trend group includes a set of up to eight variable tags that can be auto-
matically loaded into a trend display without having to select each tag individually.
Trend groups are configured by clicking the appropriate link on the Citect Configuration
panel to the left of the Admin Tools page. The functionality can also be added to a cus-
tom menu for easier access.
To configure a trend group:

1. Click Tools.
2. Select Configure a Trend Group from the Citect Configuration panel. The Configure
Trend Groups dialog appears.
3. In the Description text box, type the name you want to use to identify the group.
4. In the Trend Pen text boxes, select the eight variable tags you want the group to
trend. Click the button on the right of each field to view the available tags within the
CitectSCADA runtime project.
5. In the Area text box, type the areas defined in the CitectSCADA project you want to
use to define the group.
6. Click Add.
The information to the right of the dialog indicates how many trend groups are con-
figured and where you are currently positioned in this list. You can scroll through the
list of configured groups by using the up and down arrows.

1346
Chapter 53: Creating a New Project

To change a group, locate it in the list of groups or browse to it using the selection but-
ton to the right of the Description text box, make the necessary changes, then click
Replace.
See Also
Creating an Alarms Group

Using Environment Variables

Note: With the standard CSV_Include trend pages, you can print the screen using
the standard Print button, or plot the trend using the Trend Plot button. give the user
both alternatives as they both serve different purposes.

1347
Chapter 53: Creating a New Project

1348
Glossary

blocking Cicode function

A Cicode function that blocks, or waits, for an asynchronous event to complete before returning.

1
10base2
Ethernet implementation on thin coaxial cable. Typically uses a BNC connection.

10base5
Ethernet implementation on thick coaxial cable.

10baseT
Ethernet implementation on unshielded twisted pair. Typically uses as RJ45 connection.

A
Accredited - Level 1
Drivers developed under the CiTDriversQA96 Driver Quality and Accreditation System, which
ensures the driver was designed, coded, and tested to the highest possible standards.

Accredited - Level 2
Drivers developed using the CiTDriversQA92 Driver Quality and Accreditation System.

accumulator
A facility that allows you to track incremental runtime data such as motor run hours, power con-
sumption, and downtime.

active alarm
An active alarm is an alarm in one of the following states: ON and unacknowledged; ON and
acknowledged; OFF and unacknowledged.

advanced alarm
Triggered when the result of a Cicode expression changes to true. Use advanced alarms only when
alarm functionality cannot be obtained with the other alarm types. If you configure too many
advanced alarms, your system performance can be affected.

alarm categories
You can assign each alarm to a category, and then process each category as a group. For example, for
each category, you can specify the display characteristics, the action to be taken when an alarm in the

1349
Glossary

category is triggered, and how data about the alarm is logged. You can also assign a priority to the
category, which can be used to order alarm displays, filter acknowledgments, and so on.

alarm display page

The alarm display page displays alarm information in the following format: Alarm Time, Tag Name,
Alarm Name, Alarm Description.

alarm summary page

Displays alarm summary information in the following format: alarm name, time on, time off, delta
time, comment.

Alarms Server
Monitors all alarms and displays an alarm on the appropriate control client(s) when an alarm con-
dition becomes active.

analog alarms
Triggered when an analog variable reaches a specified value. supports four types of analog alarms:
high and high high alarms; low and low low alarms; deviation alarms; and rate of change alarms.

animation number files (.ANT)

ASCII text files that contain a list of animation points (ANs) and the coordinate location (in pixels) of
each point.

animation point
The points on a graphics page where an object displays. When you add an object to your page, auto-
matically allocates a number (AN) to the animation point, (i.e., the location of the object).

area
A large application can be visualized as a series of discrete sections or areas. Areas can be defined
geographically (where parts of the plant are separated by vast distances) or logically (as discrete proc-
esses or individual tasks).

arguments
Values (or variables) passed in a key sequence to a keyboard command in runtime (as operator
input). Arguments can also be the values (or variables) passed to a Cicode function when it executes.

Association
An association is the name or number you use when defining a Super Genie substitution, the value
or values of which are dynamically generated at runtime.

attachment unit interface (AUI)

Typically used to interface to a transceiver through what is often known as a drop cable.

1350
Glossary

automation component (ActiveX object)

ActiveX objects typically consist of a visual component (which you see on your screen) and an auto-
mation component. The automation component allows the interaction between the container object
and the ActiveX object.

B
baud rate
The number of times per second a signal changes in a communication channel. While the baud rate
directly affects the speed of data transmission, the term is often erroneously used to describe the data
transfer rate. The correct measure for the data rate is bits per second (bps).

BCD variable (I/O device)

BCD (Binary Coded Decimal) is a two-byte (16-bit) data type, allowing values from 0 to 9,999. The
two bytes are divided into four lots of four bits, with each lot of four bits representing a decimal
number. For example the binary number 0010 represents decimal 2. Thus the BCD 0010 0010 0010
0010 represents 2,222.

blocking Cicode function

A Cicode function that blocks, or waits, for an asynchronous event to complete before returning.

blocking Cicode function

A Cicode function that blocks, or waits, for an asynchronous event to complete before returning.

bottleneck
A bottleneck occurs when too many requests are being sent to a PLC communication link/data high-
way. It can occur with all types of protocols, and is dependent on several factors, including the
frequency of requests, the number of duplicated (and hence wasteful) requests, whether the protocol
supports multiple outstanding requests, as well as other network traffic.

browse sequence
A series of graphics pages linked by a browse sequence, which is a linear navigation sequence within
your runtime system that uses Page Previous and Page Next commands.

byte variable (I/O device)

Byte is a one-byte data type, allowing values from 0 to 255. One byte consists of 8 bits. Each ASCII
character is usually represented by one byte.

C
cache (I/O device data cache)
When caching is enabled, all data read from a I/O device is stored temporarily in the memory of the
I/O server. If another request is made (from the same or another control client) for the same data

1351
Glossary

within the cache time, the I/O server returns the value in its memory, rather than read the I/O device
a second time.

callback function
A function that is passed as an argument in another function. Callback functions must be user-
written functions.

Cicode
Programming language designed for plant monitoring and control applications. Similar to languages
such as Pascal.

Cicode blocking function

A Cicode function that blocks, or waits, for an asynchronous event to complete before returning.

CiNet
CiNet is no longer supported. CiNet was designed as a low speed wide area network (for remote mon-
itoring applications). If you have a widely-distributed application where computers are separated by
vast distances, using a LAN to connect your control clients can be expensive. To connect control
clients in this instance, use Microsoft's remote access server (RAS) or a Microsoft-approved solution,
such as Shiva LanRover.

citect.ini file
A text file that stores information about how each computer (servers and control clients) operates in
the configuration and runtime environments. The Citect.INI file stores parameters specific to each
computer and therefore cannot be configured as part of the project.

CiUSAFE
CiUSAFE is the application used to manage the hardware key that authorizes use of your software
within the agreed limitations.

client
A computer that accesses shared network resources provided by another computer called a server. 's
client-server based architecture is designed to distribute the processing tasks and optimize per-
formance.

cluster
A discrete group of alarms servers, trends servers, reports servers, and I/O servers. It would usually
also possess local control clients. For a plant comprising several individual sections or systems, mul-
tiple clusters can be used, one cluster for each section.

command
A command performs a particular task or series of tasks in your runtime system. A command is built
from Cicode and can consist of just a function or a statement.

1352
Glossary

communications link
A connection between computers and peripheral devices, enabling data transfer. A communications
link can be a network, a modem, or simply a cable. .

communications port
PC port used for sending and receiving serial data (also called serial or COM ports).

computer
A computer running . Other common industry terms for this computer could be node, machine or
workstation.

Control Client
The interface between the runtime system and an operator. If you are using on a network, all com-
puters (on the network) are control clients.

control inhibit mode

Prohibits writing to the Field VQT tag element of a tag extension.

custom alarm filter

Custom alarm filters provide a way to filter and display active alarms. Up to eight custom filter
strings can be assigned to a configured alarm. In conjunction with a user-defined query function, the
custom filters enable operators to identify and display active alarms of interest.

D
data acquisition board
Data acquisition boards communicate directly with field equipment (sensors, controllers, and so on).
You can install a data acquisition board in your server to directly access your field equipment.

data bits
Group of binary digits (bits) used to represent a single character of data in asynchronous trans-
mission.

data communications equipment (DCE)

Devices that establish, maintain, and terminate a data transmission connection. Normally referred to
as a modem.

data terminal equipment (DTE)

Devices acting as data source, data sink, or both.

data transfer
Transfer of information from one location to another. The speed of data transfer is measured in bits
per second (bps).

1353
Glossary

data type (I/O device)

Type of I/O device variable. I/O devices may support several data types that are used to exchange
data with . You must specify the correct data type whenever I/O device variables are defined or ref-
erenced in your system.

DB-15
Often called a `D' type connector due to the vague D shape of the casing. Has 15 pins arranged in
two rows of 8 and 7 pins. While not as common as DB-9 or DB-25 they may be found on some com-
puters and data communication equipment. Comes in both male (pins protruding) and female (pin
sockets) configurations.

DB-25
Often called a `D' type connector due to the vague D shape of the casing. Has 25 pins arranged in
two rows of 13 and 12 pins. This kind of connection is a part of the standard for RS-232-D and is
found on many computers, modems and other data communication equipment. Comes in both male
(pins protruding) and female (pin sockets) configurations.

DB-9
Often called a `D' type connector due to the vague D shape of the casing. Has 9 pins arranged in two
rows of 5 and 4 pins. This kind of connection is common and is often used as the serial (com) port in
computers. Often used in modems and other data communication equipment. Comes in both male
(pins protruding) and female (pin sockets) configurations.

DDE
dynamic data exchange

debug.log
The debug.log file stores information about an unexpected system shut down or other internal issues.
If an unexpected shutdown occurs, it will identify the version and path of each DLL being used at
the time.

deviation alarm
Triggered when the value of a variable deviates from a setpoint by a specified amount. The alarm
remains active until the value of the variable falls (or rises) to the value of the deadband. .

dial-back modem
Only returns calls from remote I/O devices.

dial-in modem
Only receives calls from remote I/O devices, identifies the caller, then hangs up immediately so it can
receive other calls. then returns the call using a dial-back modem.

1354
Glossary

dial-out modem
Makes calls to remote I/O devices in response to a request; e.g., scheduled, event-based, operator
request, and so on. Also returns calls from remote I/O devices.

Digiboard
A high-speed serial board manufactured by the Digiboard Corporation.

digital alarms
Triggered by a state change in a digital variable. Use these alarms when a process has only one of
two states. You can use either the on (1) state or off (0) state (of a digital variable) to trigger the alarm.

digital variable (I/O device)

Usually associated with discrete I/O in your I/O device, a digital variable can only exist in one of two
states: on (1) or off (0). Allowed values for the digital data type are therefore 0 or 1. Discrete inputs
(such as limit switches, photoelectric cells, and emergency stop buttons) and discrete outputs are
stored as digital variables.

disk I/O device

A disk file that resides on the hard disk of a computer and emulates a real I/O device. The value of
each variable in the disk I/O device is stored on the computer hard disk. The disk I/O device is not
connected to any field equipment in the plant.

display period
Defines the rate at which trend data is displayed on the trend page.

distributed processing
For large applications with large amounts of data, you can distribute the data processing to reduce
the load on individual computers.

distributed servers
If your plant consists several sections or systems, you can assign a cluster to each individual section,
and then monitor all sections using one control client.Note: Don't use distributed servers to split up a
single section or process into discrete areas. A single cluster system with distributed processing
would be better used here since it would not be hampered by the maintenance overhead of a dis-
tributed server system (such as extra project compilations, and so on).

domain name server (DNS)

Database server that translates URL names into IP addresses.

dot notation
Used for Internet addresses. Dot notation consists of four fields (called octets), each containing a dec-
imal number between 0 and 255 and separated by a full stop (.).

1355
Glossary

driver
A driver is used to communicate with control and monitoring devices, allowing the run-time system
to interact directly with different types of equipment. Communication with an I/O device requires a
device driver which implements the communication protocol(s).

driver logs
Driver logs relate to the operation of a particular driver and are named accordingly. For example, the
OPC driver is logged in 'OPC.dat'.

duplex
The ability to send and receive data over the same communication line.

dynamic data exchange (DDE)

A Microsoft Windows standard protocol set of messages and guidelines that enables communication
between Windows applications on the same Windows computer.

dynamic data exchange (DDE) Server

A Windows standard communication protocol supported by . The I/O server communicates with the
DDE server using the Windows standard DDE protocol. DDE servers are appropriate when data com-
munication is not critical as DDE servers are not designed for high-speed data transfer.

E
empty value
Indicates that the variant has not yet been initialized (assigned a value). Variants that are empty
return a VarType of 0. Variables containing zero-length strings (" ") aren't empty, nor are numeric var-
iables having a value of 0.

Equipment States
Determine the action that the item or group of equipment will take at the scheduled time.

Ethernet
Widely used type of local area network based on the CSMA/CD bus access method (IEEE 802.3).

Event data displayed by time

As an alternative to viewing event trend data by event number, it is possible to see event trends
across a timeline. When event trends are shown by time, the trend graph includes a start and end
time and enables operators to see both the time of a triggered event, and the elapsed period between
events. This data can also be displayed on the same graph as a periodic trend.

event trend/SPC
To construct an event trend/SPC, takes a sample when a particular event is triggered (in the plant).
This sample is displayed in the window. The event must then reset and trigger again, before the next
sample is taken. Events are identified by the event number. .

1356
Glossary

expression
A statement (or group of statements) that returns a value. An expression can be a single variable, a
mathematical formula, or a function.

F
Field element
The latest tag field data received from a device.

file server
A computer with a large data storage capacity dedicated to file storage and accessed by other client
computers via a network. On larger networks, the file server runs a special network operating system.
On smaller installations, the file server may run a PC operating system supplemented by peer-to-peer
networking software.

full duplex
Simultaneous two-way (in both directions) independent transmission (4 Wires).

G
generic protocol
A pseudo-protocol supported by disk I/O devices that provides a convenient way to represent disk
data. The generic protocol is not a real protocol (communicates with no physical I/O device).

Genie
If you have numerous devices of the same type (e.g., 100 centrifugal pumps), the display graphics for
each will behave in much the same way. Using Genies, you only have to configure common behav-
ior once. The graphics can then be saved as a Genie and pasted once for each device.

global Cicode variable

Can be shared across all Cicode files in the system (as well as across include projects).

global client
A control client used to monitor information from several systems or sections (using clusters).

graphics bounding box

A faint (grayed) dotted rectangular box outline defining the exterior boundary region of a graphic
object. Only visible and active when the graphics object is selected and being resized. Contains sizing
handles in each corner and (if sized large enough to display) one in the centre of each side.

graphics page
A drawing (or image) that appears on a workstation to provide operators with control of a plant, and
display a visual representation of conditions within the plant.

1357
Glossary

group (of objects)

allows you to group multiple objects together. Each group has a unique set of properties, which deter-
mine the runtime behavior of the group as a whole.

H
half duplex
Transmission in either direction, but not simultaneously.

hardware alarm
A hardware alarm indicates that an error has been detected in your system. Typically displayed on a
dedicated hardware alarms page, this type of alarm may indicate that a loss of communication has
occurred, that Cicode can not execute, that a graphics page is not updating correctly, or that a server
has become inoperative. A description and error code are provided to help decipher the cause of the
problem.

histogram
A bar graph that shows frequency of occurrence versus value. Quite often the data is fitted to a dis-
tribution such as a normal distribution. .

historize
To archive historical data for a variable for the purpose of future analysis. This is achieved through
integration with Schneider Electric's Historian application.

I
I/O Device
An item of equipment that communicates with plant-floor control or monitoring equipment (sensors,
controllers, and so on). The most common I/O devices are PLCs (programmable logic controllers);
however, supports a wide range of I/O devices, including loop controllers, bar code readers, scientific
analyzers, remote terminal units (RTUs), and distributed control systems (DCS). can communicate
with any I/O device that has a standard communications channel or data highway.

I/O device address

The (logical) location of the I/O device in the system. Each I/O device must have a unique address in
the system, unless the I/O device is defined in other servers (to provide redundancy). If redundancy
is used, the I/O device must then have the same I/O device name, number, and address for each
server.

I/O device variable

A unit of information used in . Variables are stored in memory registers in an I/O device. exchanges
information with an I/O device by reading and writing variables. refers to I/O device variables by

1358
Glossary

their register addresses. I/O devices usually support several types of variables; however, the most
common are digital variables and integer variables.

I/O server
A dedicated communications server that exchanges data between I/O devices and control clients. No
data processing is performed by the I/O server (except for its local display). Data is collected and
passed to the control clients for display, or to another server for further processing. All data sent to
an I/O device from any computer is also channelled through the I/O server. If data traffic is heavy,
you can use several I/O servers to balance the load.

imestamp (T)
The timestamp of when the element was last updated on a tag extension.

include file (.CII)

There is a maximum number of characters that you can type in a Command or Expression field
(usually 128). If you need to include many commands (or expressions) in a property field, you can
define a separate include file that contains commands or expressions. An include file is a separate
and individual ASCII text file containing only one sequence of commands or expressions that would
otherwise be too long or complicated to type into the command or expression field within . The
include file name is entered instead, and the whole file is activated when called.

integer variable (Cicode)

A 4-byte (32-bit) data type allowing values from 2,147,483,648 to 2,147,483,647.

integer variable (I/O device)

A 2-byte data type, allowing values from -32,768 to 32,767, that is used to store numbers (such as tem-
perature or pressure). Some I/O devices also support other numeric variables, such as real (floating
point) numbers, bytes, and binary-coded decimals.

Internet Display Client

Allows you to run projects over the Internet from a remote location. It is basically a "runtime-only"
version of : you can run your project from that computer, just as you would from any normal client.

interrupt
An external event indicating that the CPU should suspend its current task to service a designated
activity.

IP address
A unique logical address used by the Internet Protocol (IP). Contains a network and host ID. The for-
mat is called dotted decimal notation, and is written in the form: w.x.y.z.

1359
Glossary

K
Kernel
The Kernel allows you to perform low-level diagnostic and debugging operations for runtime anal-
ysis of your system. A set of diagnostic windows display low-level data structures, runtime data-
bases, statistics, debug traces, network traffic, I/O device traffic and so on.

keyboard command
Consist of a key sequence that an operator enters on the keyboard, and an instruction (or series of
instructions) that executes when the key sequence is entered. Keyboard commands can be assigned to
an object or page, or they can be project-wide.

knowledge base
Provides high-level technical information beyond the scope of standard technical documentation that
is updated regularly and available at http://www.citect.com.

kurtosis
An index indicating the degree of peakedness of a frequency distribution (usually in relation to a nor-
mal distribution). Kurtosis < 3 indicates a thin distribution with a relatively high peak. Kurtosis > 3
indicates a distribution that is wide and flat topped.

L
language database
When a project is compiled, creates a language database (dBASE III format) consisting of two fields:
native and local. Any text marked with a language change indicator is automatically entered in the
native field. You can then open the database and enter the translated text in the local field.

link
A copy of a library item, possessing the properties of the library original. Because it is linked, the
copy is updated whenever the original is changed.

local area network (LAN)

A system that connects computers to allow them to share information and hardware resources. With
real-time LAN communication, you can transfer data, messages, commands, status information, and
files easily between computers.

local Cicode variable

Only recognized by the function within which it is declared, and can only be used by that function.
Local variables must be declared before they can be used. Any variable defined within a function (i.e.,
after the function name) is a local variable, therefore no prefix is needed. Local variables are
destroyed when the function exits and take precedence over global and module variables.

1360
Glossary

local language
The language of the end user. Runtime display items such as alarm descriptions, button text, key-
board/alarm logs, graphic text, Cicode strings and so on can be displayed in the local language, even
though they may have been configured in the language of the developer (native language).

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

log files
Log files are a record of time-stamped system data that can be analyzed to determine the cause of a
problem. The available log files include syslog.dat, tracelog.dat, debug.log, kernel.dat, and dedicated
driver logs.

long BCD variable (I/O device)

A 4-byte (32-bit) data type, allowing values from 0 to 99,999,999. The four bytes are divided into eight
lots of four bits, with each lot of four bits representing a decimal number. For example the binary
number 0011 represents decimal 3. Thus the BCD 0011 0011 0011 0011 0011 0011 0011 0011 rep-
resents 33,333,333.

long variable (I/O device)

A 4-byte (32-bit) data type allowing values from 2,147,483,648 to 2,147,483,647.

low and low low alarms

Defined by specifying the values of the variable that trigger each of these alarms. As a low alarm
must precede a low low alarm, the low alarm no longer exists when the low low alarm is triggered.
Note that the variable must rise above the deadband before the alarm becomes inactive. .

M
maximum request length
The maximum number of data bits that can be read from the I/O device in a single request. For exam-
ple, if the maximum request length is 2048 bits, the maximum number of integers that can be read is:
2048/16 = 128.

Metadata
Metadata is a list of names with corresponding values that is attached to an objects animation point.

millisecond trending
Allows you to use a trends sample period of less than one second.

mimic
A visual representation of a production system using an organised set of graphical pages. .

1361
Glossary

minimum update rate

A pre-defined period of time after which tag update value notifications are sent to subscription
clients

module Cicode variable

Specific to the file in which the variable is declared. This means that it can be used by any function
in that file, but not by functions in other files. By default, Cicode variables are defined as module,
therefore prefixing is not required (though a prefix of MODULE could be added if desired). Module
variables should be declared at the start of the file.

multi-digital alarms
Use combinations of values from three digital variables to define eight states. For each state, you spec-
ify a description (e.g., healthy or stopped), and whether or not the state triggers an alarm.

N
native language
Generally the language of the project developer. Display items such as alarm descriptions, button
text, keyboard/alarm logs, graphic text, Cicode strings and so on can be configured in the native lan-
guage, and displayed, at runtime, in the language of the end-user (local language).

network
A group of computers and peripheral devices, connected through a communications link. Data and
services (e.g., printers, file servers, and modems) can be shared by computers on the network. A local
network of PCs is called a LAN.

network computer
A computer running that is connected to a LAN through a network adaptor card and network soft-
ware. .

Network Dynamic Data Exchange (NetDDE)

Enables communication between Windows applications on separate computers connected across a
common network.

nodes
A structural anchor point for a graphic object, usually visible as a small square box superimposed
over a graphic. Nodes will be located separately at the start, at the end, and at every change in direc-
tion within a graphic object. .

normal distribution
Also known as a `bell' curve, the normal distribution is the best known and widely applicable dis-
tribution. The distribution is symmetrical and popularly represents the laws of chance. 68.27% of the
area lies between -1 sigma and +1 sigma, 95.45% between -2 sigma and+2 sigma, and 99.73%

1362
Glossary

between -3 sigma and +3 sigma. The values of skewness and kurtosis are used to provide quan-
titative measures for normality. Assuming that at least 20 samples are used to construct a dis-
tribution, a good rule of thumb is to accept the data as a normal distribution when, -1.0 = skewness =
1.0 2 = kurtosis = 4.

null value
Indicates that a variant contains no valid data. Variants that are null return a VarType of 1. Null is
not the same as empty, which indicates that a variant has not yet been initialized. It is also not the
same as a zero-length string (" "), which is sometimes referred to as a null string. Null is not equiv-
alent to zero or blank. A value of null is not considered to be greater than, less than, or equivalent to
any other value, including another value of null. A boolean comparison using a null value will
return false.

O
object
Basic building blocks of a graphics page. Most objects possess properties that allow them to change
dynamically under user-definable runtime conditions allowing them to provide animated display of
conditions within the plant.

object ID (OID)
An object ID associated with every tag in a project that uniquely identifies the tag for use by tag-
based drivers, automatically generated at compile. It is used instead of the actual address of the reg-
ister (which is what most other drivers use to read from and write to I/O devices).

object variable (Cicode)

An ActiveX control that can only be declared with local, module, or global scope.

ODBC
Open Data Base Connectivity

OLE
Object Linking and Embedding (OLE) is a Microsoft technology that can be used to create customized
user interface elements.

OPC
OLE for Process Control (OPC) is a set of communications standards maintained by the OPC Foun-
dation for the industrial automation industry.

OPC DA
OPC Data Access (OPC DA) is a set of specifications designed to support the communication of real
time data across client/server architectures.

1363
Glossary

OPC item
An OPC item represents the connection to a data source within a server (for example, a variable tag
in a SCADA system).

open database connectivity (ODBC)

Allows applications to access data in database management systems using structured query lan-
guage (SQL) to access data.

override mode
A state where an invalid tag quality value is overridden by a manually added value.

P
pack
Packing a database re-indexes database records and deletes records marked for deletion. If you edit
your databases externally to , you should pack the database afterwards.

page environment variable

A read-only variable associated with a particular page When you make the association, you name
the variable, and assign it a value. When the page is opened during runtime, creates the variable. Its
value can then be read. When the page is closed, the environment variable memory is freed (dis-
carded).

parity
A communications error-checking procedure. The number of 1's must be the same (even or odd) for
each group of bits transmitted without error.

periodic trend
A trend that is sampled continuously at a specified period. You can also define a trigger (an event) to
stop and start the trend (when a specified condition occurs in the plant).

persistence cache
Cache data saved to a computer hard disk that allows an I/O server to be shut down and restarted
without having to re-dial each I/O device to get its current values. This cache consists of all the I/O
device's tag values.

PLC interface board

You can sometimes install a PLC interface board in your server. A proprietary interface board is
usually supplied by your PLC manufacturer, and you can connect it to a PLC or a PLC network. You
can only use proprietary interface boards with the same brand of PLC.

point limit
An individual digital (or analog) variable read from an I/O device. only counts physical points (and
counts them only once, no matter how many times they are used). The point limit is the maximum

1364
Glossary

number of I/O device addresses that can be read and is specified by your license. When you run the
point count of your project is checked against the point limit specified by your Hardware Key.

port(s)
Provide the communication gateway to your I/O device(s).

primary Alarms Server

The server that normally processes alarms.

primary Reports Server

The server that normally processes reports.

primary Trends Server

The server that normally processes trends.

Privileges
Level of access applied to system elements within your project. A user assigned a role that possesses
the matching privilege can control it.

project
The elements of a monitoring and control system, such as graphics pages, objects, and so on. These
elements are stored in files of various types; for example, graphics files for graphics pages, databases
for configuration records, and so on. You use the compiler to compile the project into a runtime sys-
tem.

properties, object
Describes the appearance of an object (size, location, color, and so on.) and its function (the command
or expression executed by the object, the privilege required to gain access to the object, and so on).

protocol
Messaging format consisting of a set of messages and guidelines used for communication between
the server and an I/O device. The communication protocol determines how and the I/O device com-
municate; the type of data to exchange; rules governing communication initiation and termination;
and error detection.

proxi/proxy server
Caches internet transactions to improve performance by reducing the average transaction times by
storing query and retrieved information for re-use when the same request is made again. When an
Internet display client (IDC) connects to a proxy server, that server provides the TCP/IP addresses nec-
essary to access report server session information.

PSTN
A public switched telephone network is the network of all the world's public switched telephone net-
works. It is now primarily digital and includes mobile as well as fixed telephones.

1365
Glossary

Q
qualified tag reference
Referencing tag data by using the tag name, element name and the item name.

Quality (Q)
The quality of the value of a tag extension.

QualityTimestamp (QT)
The timestamp of when the quality last changed on a tag extension

R
rate of change alarms
Triggered when the value of the variable changes faster than a specified rate. The alarm remains
active until the rate of change falls below the specified rate. Deadband does not apply to a rate of
change alarm.

real variable (Cicode)

Real (floating point) is a 4-byte (32-bit) data type allowing values from 3.4E38 to 3.4E38. Use a real
variable to store numbers that contain a decimal place.

real variable (I/O device)

Real (floating point) is a 4-byte (32-bit) data type, allowing values from 3.4E38 to 3.4E38. Use a real
variable to store numbers that contain a decimal place.

record name
Usually the primary property of a database record, referenced in system through its name. Database
record names must be unique for each type of database record. Sometimes you can use identical
names for different record types. However, to avoid confusion, you should use a unique name for
each database record in your application.When you specify a name for a database record, the name
must begin with an alphabetic character (A-Z, a-z) and cn only include alphanumeric characters (A-
Z, a-z, 0-9) and the underscore character (_). For example, "Pressure," "Motor_10," and "SV122_Open"
are all valid database record names. Each database record name can contain up to 16 char-
acters.Database record names are not case-sensitive, so "MOTOR_1," "Motor_1" and "motor_1" are all
identical database record names. For this reason use a meaningful name for any database record as
well as the necessary naming conventions.

redundancy
A method of using the hardware in a system such that if one component in the system becomes
inoperative, control of the system is maintained, and no data is lost.

1366
Glossary

remote communications
Interaction between two computers through a modem and telephone line.

remote terminal
A terminal remote from the computer that controls it. The computer and remote terminal com-
municate via a modem and telephone line.

report
A statement or account of plant-floor conditions. reports can be requested when required, on a peri-
odic basis, or when an event occurs.

report format file

Controls the layout and content of reports. The format file is edited using a text editor and can be in
either ASCII or RTF format.

Reports Server
Controls report processing. You can request reports at any time or when specific events occur.

reserved words
Words that cannot be used as a name for any database record or Cicode function.

RJ11
A type of IDC plug commonly used in data communications. Recognizable as the style of data plug
used in phone line and handset connectors. RJ11 is a 6/4 plug with 6 contacts but only 4 loaded.

RJ12
A type of IDC plug commonly used in data communications. Recognizable as the style of data plug
used in phone line and handset connectors. RJ12 is a 6/6 plug with 6 contacts.

RJ45
A type of IDC plug commonly used in data communications. Recognizable as the style of data plug
used in phone line and handset connectors. RJ45 is often used with 10baseT and is an 6/8 plug with
8 contacts.

Roles
A defined set of permissions (privileges and areas) that are assigned to users.

RS-232
An industry standard for serial communication. The standard specifies the lines and signal char-
acteristics that are used to control the serial transfer of data between devices.

RS-422
An industry standard for serial communication. The standard specifies the lines and signal char-
acteristics that are used to control the serial transfer of data between devices. RS-422 uses balanced

1367
Glossary

voltage interface circuits.

RS-485
An industry standard for serial communication. The standard specifies the lines and signal char-
acteristics that are used to control the serial transfer of data between devices. RS-485 uses balanced
voltage interface circuits in multi-point systems.

runtime system
The system that controls and monitors your application, process, or plant. The runtime system is
sometimes called the Man-Machine Interface (MMI), and is compiled from a project.

S
scalable architecture
A system architecture that can be resized without having to modify existing system hardware or soft-
ware. lets you re-allocate tasks as more computers are added, as well as distribute the processing
load.

schedule period
Determines how often the I/O server contacts a scheduled I/O device to read data from it. .

serial communication
Uses the communication port on your computer or a high speed serial board (or boards) installed
inside your computer.

server
A computer connected to an I/O device (or number of I/O devices). When is running, the server
exchanges data with the I/O device(s) and distributes information to the other control clients as
required. A local area network (LAN) computer that perform processing tasks or makes resources
available to other client computers. In , client-server architecture distributes processing tasks to opti-
mize performance.

simplex transmission
Data transmission in one direction only.

skewness
An index indicating the degree of asymmetry of a frequency distribution (usually in relation to a nor-
mal distribution). When a distribution is skewed to the left (for example), then the tail is extended on
that side, and there is more data on the left side of the graph than would be expected from a normal
distribution. Positive skew indicates the distribution's mean (and tail) is skewed to the right. Neg-
ative skew indicates the distribution's mean (and tail) is skewed to the left.

1368
Glossary

slider control
Allow an operator to change the value of an analog variable by dragging an object (or group) on the
graphics page. Sliders also move automatically to reflect the value of the variable tag.

soft PLC
A pure software (virtual) PLC created by software and existing only within the computer memory.
Usually provides a software interface for communication (READ and WRITE) operations to take
place with the soft PLC. Also known as a `virtual field unit' or `virtual I/O device'.

software protection
uses a hardware key that plugs into the printer port of your computer to protect against license
infringement. The hardware key contains the details of your user license. When you run , the point
count in your project is checked against the point limit specified in the hardware key.

staleness period
Represents the total number of seconds that will elapse after the last update before extended quality
of the tag element is set to “Stale”.

standby Alarms Server

The Server that processes alarms if the primary alarms server is unavailable.

standby Reports Server

The server that processes reports if the primary reports server is unavailable.

standby Trends Server

The server that processes trends if the primary trends server is unavailable.

stop bits
The number of bits that signals the end of a character in asynchronous transmission. The number is
usually 1 or 2. Stop bits are required in asynchronous transmissions because the irregular time gaps
between transmitted characters makes it impossible for the server or I/O device to determine when
the next character should arrive.

substatus value
The underlying details of a QUALITY tag.

Substitution
A Super Genie substitution is comprised of the data type (optional) and association that you use to
define an object or group of object’s properties when creating a Super Genie.

Super Genies
Dynamic pages (usually pop-ups), to which you pass information when the page displays at run-
time. You can use Super Genies for pop-up type controllers (to control a process, or a single piece of
plant floor equipment).

1369
Glossary

symbol
An object (or group of objects) stored in a library for later retrieval and use. By storing common
objects in a library, you reduce the amount of disk space required to store your project, and reduce the
amount of memory required by the run-time system.

syslog.dat
Syslog.dat is the primary log file. It contains useful system information, from low-level driver traffic
and Kernel messages, to user defined messages. Trace options (except some CTAPI traces) are sent to
this file.

T
tag extension
Additional information for a tag that represents data as a collection of elements, and a collection of
items in a tag.

task
Includes operations such as I/O processing, alarm processing, display management, and Cicode
execution. Any individual `instance' of Cicode is also a `task'.

template
A base drawing or time-saving pattern used to shape a graphics page. Each template contains base
information for the page, such as borders and common control buttons. provides templates for all
common page types.

text box
When text is added to a graphics page, it is placed in a text box. A text box has a number of handles,
which can be used to manipulate the text object.

thread
Used to manage simultaneous execution of tasks in multitasking operating systems, enabling the
operating system to determine priorities and schedule CPU access.

timeout
The period of time during which a task must be completed. If the timeout period is reached before a
task completes, the task is terminated.

time-stamped alarms
An alarm triggered by a state change in a digital variable. Time-stamped alarms have an associated
register in the I/O device to record the exact time when the alarm changes to active. Use time-
stamped alarms when you need to know the exact order in which alarms occur.

1370
Glossary

time-stamped analog alarms

Time stamped analog alarms work in the same way as analog alarms except that they are time
stamped (with the Alarm On and Alarm Off times) using millisecond precision from the time kept by
the field device (i.e. the RTU or PLC). The configuration details for time stamped analog alarms are
exactly the same as for analog alarms.

time-stamped digital alarms

Time stamped digital alarms work in the same way as digital alarms except that they are time
stamped (with the Alarm On and Alarm Off times) using millisecond precision from the time kept by
the field device (i.e. the RTU or PLC). The configuration details for time stamped digital alarms are
exactly the same as for digital alarms.

tool tip
A help message that displays in a pop-up window when an operator holds the mouse stationary
over an object.

touch (object at runtime)

An object is considered touched if an operator clicks it.

Touch command
Can be assigned to objects on graphics pages. Touch commands allow you to send commands to the
runtime system by clicking an object.

tracelog.dat
The tracelog.dat file contains managed code logging, mainly in relation to data subscriptions and
updates. Note that field traces and requests to native drivers go to the syslog.dat or a specific driver
log file.

trend
A graphical representation of the changing values of a plant-floor variable (or expression), or a
number of variables. .

trend line
The actual line on a trend that represents the changing values of a plant-floor variable (or expres-
sion). .

trend plot
Consists of a trend (or a number of trends), a title, a comment, scales, times and so on.

Trends Server
Controls the accumulation and logging of trend information. This information provides a current and
historical view of the plant, and can be processed for display on a graphics page or printed in a
report.

1371
Glossary

U
UAC
User Account Control. Security technology introduced in Windows Vista to enable users to run with
standard user rights more easily. .

unqualified tag reference

Reference to tag data by using only the tag name.

unsigned integer variable (I/O device)

A 2-byte (16 bit) data type, representing an integer range from 0 to 65,535. This is supported for all
I/O devices that can use INT types. This means you can define any integer variable as an unsigned
integer to increase the positive range.

Users
A person or group of persons that require access to the runtime system

V
Valid element
The last field data which had “Good” quality in a tag extension.

Value (V)
The value of the extension of a tag.

ValueTimestamp (VT)
The timestamp of when the value last changed on a tag extension

variable type (Cicode)

The type of the variable (INT (32 bits), REAL (32 bits), STRING (256 bytes), OBJECT (32 bits)).

view-only client
A computer configured with manager-only access to the runtime system. No control of the system is
possible, but full access to data monitoring is permitted.

virtual
Behavioral identification rather than a physical one. For example, Windows 95 is a virtual desktop.

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

1372
Index
alarms
advanced alarm properties 734
A advanced, adding 712
access alarm category properties 752
disabling 686 analog alarm properties 726
object 683 analog, adding 711
properties 684 audible 1338
property 569 tab style templates 1230, 1266
access table, reading data from 976 categories of 752
accumulators 803 debugging hardware 1091
configuring 803 delay 713
properties 803 digital alarm properties 715
action queries, calling 978 digital, adding 710
Active Alarms button 1245, 1332 display order 772
ActiveX Data Objects 93 displaying variable data in 761
ActiveX objects 630 formatting display 759
identifying 634 multi-digital alarm properties 722
managing associated data sources 630 multi-digital, adding 710
adding properties supported as tags 777
new schedule, operator 1150 server redundancy 315
user records 262 setting up 784
address forwarding 1070 time-stamped alarm properties 718
Admin Tools page template 1328 time-stamped analog alarm properties 737
advanced alarms time-stamped analog, adding 712
adding 712 time-stamped digital alarm properties 731
Advanced Security Settings dialog 235 time-stamped digital, adding 712
alarm time-stamped, adding 710
display fields 762 using properties as tags 776
filters 743 writing to properties of 782
page template 1219, 1250, 1256, 1322 alarms group 1345
paging properties 63 Alarms Summary button 1245, 1332
soe fields 766 Alarms toolbar 1245, 1332
summary fields 771 Align dialog box 584
tag name 414 aligning objects 584
Alarm data localization 1022 grids 544
alarm server, troubleshooting 788 guidelines 545
Alarm Silence button 1245, 1332 alternative .ini file 1071
alarm text analog alarms
marking for language change 1013 adding 711
alarming 93 animation point (AN) 546, 586
ANSI character sets 1023

1373
Index

appearance bitmaps 558, 565

graphics page 535 blank tab style page template 1216, 1246-1247
of objects 566 boards
appending data with ODBC 977 properties 348
archiving proprietary 337
data 890 serial 333
eventjournal 790 breaking link to data source 465
projects 206 Bring Forwards command 583
Scheduler 793 Bring to Front command 583
Using cicode 791 browse sequence, pages 521
area prefix in tag names 415 button objects 614
areas 569 Button Properties dialog box 615
groups 252-253 Byte data type 420
labels for 251
privileges 247, 258, 260 C
Super Genies and 1006 cache
viewing 254 data 382
arguments tuning 1072
in labels 869 cache kernel command 1107
values for 869 calculating
arrangements, pipe 605 array size 434
array objects fill colour 661 disk storage for trends 823
arrays 432 callback functions 1085
offsets, Super Genies and 1005 calling action queries 978
size 434 capability charts 833
Super Genies and 1004 capability, process 831
ASCII character sets 1023 categories, alarm 752
ASCII devices 873 center limit 832
format 882 character sets 1023
assigning variable tags 413 charts
associations capability 833
defining for Super Genies 994 control 833
attributes for tag names 416-417 cicode kernel command 1108
audible alarms, implementing 1338 Cicode objects 626
for tab style templates 1230, 1266 circles, drawing 596
Autoscale button 1327 Citect support 381
citect.ini, location 61
B CiUSAFE dialog box 149
Back button 1330 client syntax and DDE 952
backup 1173 cls kernel command 1110
backups, project 206 cluster
backup utility 209 defining 293
BCD data type 420 rules 291

1374
Index

cluster context 290 Computer Setup Wizard 272

resolving 290 cluster connections 281
color fonts, defining 775 computer role 275
color, fill 657 CPU configuration 278
array objects 661 events 279
gradient objects 666 EWS server setup 284, 286
multi-state objects 659 general options setup 286
on/off objects 657 internet server 277
threshold objects 664 keyboard security 283
color, gradient 593, 597, 602 menu security 282
colors on graphics pages 548 miscellaneous security 283
colors on graphics pags 548 Modify URL Reservation 285
COM port 331 network model 275
command fields 891 project 273
commands reports 277
kernel 1105 Startup Functions setup 280
keyboard 675 trends 278
SQL 945 Computer Setup Wizard, about 271
touch 672 Computer Setup Wizard, running for CSV_
common functionality, tab style alarms Include 1336
template 1251, 1258 Computer Setup Wizard, running for tab style
common functionality, tab style page templates 1229, 1265
template 1323 COMx driver
common functionality, tab style template 1242 debugging 372
common toolbars 1329 COMx driver special options 333
communications Configuration
customizing using parameters 362 views 1148
I/O devices 321 configuration files, location 61
manual configuration 347 configuration, startup/runtime 1069, 1087
report errors 863 Configure Alarm Groups dialog box 1345
scheduling 409 Configure Trend Groups dialog box 1346
serial 335-336 configuring
test project 338 accumulators 803
troubleshooting 407 alarms 784
using a COM port 331 DDE conversations 953
using a proprietary board 337 devices 880
using a serial board 331 events 797
using an Ethernet card 335 history files 825
compilation I/O device communications 325
debugging 1049 network DDE shares 963
incremental 1049 ODBC drivers 969
project 1047 reports 855
SQL devices 881

1375
Index

trend tags 808

variable tags 421 D
Web Client deployment 1184 data
Configuring Special Day Categories appending 977
engineer 1174 archiving 890
connecting caching 382
database 956 displaying in alarms 761
network DDE shared application 965 editing, with ODBC 977
SQL database 943 exchanging 951, 956
constants and Super Genies 1004 exporting trend 821
control charts 833 formatting device 882
Control Inhibit Mode 456, 458 logging in different languages 1021
Control Menu page, CSV_Include 1337 printing trend 820
Control Menu page, tab style templates 1265 reading data from access table 976
control, statistical 831 trending 807
conversations, DDE 952 using devices to read 875
conversion, database types 949 data folder, location 61
converting data sources, external 491
date and time 980 data types
values to strings 870 DDE 955
Copy Project dialog properties 200 variable tag 422
copying database device 885
objects 582 database transactions 946
projects 200 database type conversions 949
corners, rectangle 593 databases
cp index 834 external 937
cpk index 834 local language 1020
Crash Handler 1097 date conversions 980
creating dates in SQL 946
alarms group 1345 dBASE database devices 873
browse sequence 521 dBASE databases 937
custom menus 1232, 1268, 1342-1343 dBASE devices
Genies 986 format 884
graphics pages 513 dbf editing 981
pages 1231, 1267, 1340 DDE conversations 952
projects 1227, 1263, 1335 configuring 953
templates 519, 521 DDE services 961
Web Client deployment 1185 DDE shares 964
custom alarm filters 743 DDE trusted shares 964
Custom File properties 1066 debug kernel command 1110
custom fonts 775 debugging
compilation 1049
COMx driver 372
I/O Devices 371

1376
Index

log files 1092 devices 873

proprietary board drivers 379 ASCII devices format 882
protocol drivers 377 configuring 880
protocols 371 dBASE devices format 884
runtime system 1090 formatting data in 882
server redirection 1070 groups of 875
TCP/IP drivers 375 I/O devices 321
the Crash Handler 1097 printer devices format 882
decimal notation 431 reading data 875
default cluster context 290 SQL devices format 884
default languages for Web Client 1193 using a database device 885
default sort order, tab style alarms template 759 devices,SQL
defaults, graphics page 542 configuring 881
defining DevOpen Cicode function 885
access to objects 683 DevSetField() function 886
alarm categories 752 DevWrite() function 886
associations for Super Genies 994 digital alarms
colors on graphics pages 548 adding 710
labels 871 Digital data type 420
page properties 533 direction, gradient 593, 597, 602
paths 826 Disabled Alarms button 1245, 1332
substitutions for Genies 986 disabling object access 686
substitutions for Super Genies 993 disk I/O device
trend pages 818 upgrading to persisted memory mode 368
defining variable tag names 427 Disk I/O Device Errors 366
delaying alarms 713 disk I/O devices 363
deleting memory mode 367
objects 580 redundancy 365
rows from access table 978 setup 364
demo mode 150 disk storage, calculating 823
deployment for Web Client 1187 display, formatting alarm 759
configuring 1184 displaying
creating 1185 lists in alarms 761
deleting 1192 tables in alarms 761
displaying 1190 displaying tags 702
editing 1191 domain 266
updating 1192 drawing
DevAppend() function 886 buttons 614
DevDelete() function 888 circles 596
DevFind() function 887 ellipses 596
DevGetField() function 887 lines 589, 591
device drivers 358 pipes 605
device history files 888 polygons 601
polylines 601

1377
Index

rectangles 592 elements, array 433

squares 592 ellipse objects 596
drawing environment 544 engineering units 431
options 546 entry action
driver information 390 state
driver packs 360 equipment 1170
Driver Reference Help 361 environment
Driver Runtime Interface (DRI) 328 drawing 544
Driver Update Utility 361 graphics pages 540
drivers 358 environment variables 540
determining which to use 359 super genie 70
Driver Reference Help 361 equipment 94, 98, 895-896, 898, 923, 925, 1165
Driver Update Utility 361 editor 114
installing a driver pack 360 hierarchy 896
ODBC 967-969 importing 95, 926
drivertrace kernel command 1112 item 113
DspGetEnv() function 540 name 898
dual NIC 312 states 1165
Dynamic Data Exchange (DDE) 951 TagItem
and Office applications 960 Compiler Errors 741
connecting to tag database 956 types 922
data types 955 equipment templates 927
posting data 957 examples 927
reading values from 959 footer 935
writing values to 958 header 927, 931
dynamic point count 150 input 929
Dynamically Optimized Writes 69 output common fields 932
output database 933
E output node field 931-932
EcoStruxure Web Service Server 1041 outputs 930
configuration 1042 parameters 928
EcoStruxure Web Service Server SSL cer- troubleshooting 935
tificate 1043 error messages
EcoStruxure Web Service Server supported Find and Replace 226
methods 1044 Ethernet card 335
properties 1042 events 797
Edit Favorite Colors dialog box 549 configuring 797
Edit Item Menu dialog box 1344 page 538
editing 1168 properties 797
project properties 197 running 799
using ODBC 977 times and periods 799
editing menu items 1344 triggers for 800
effects, applying three-dimensional 637 events setup page, CSV_Include project 1336

1378
Index

EWS alarm summary 771

runtime operation 1044 command 891
example equipment templates 927 file names in DDE 960
Excel 981 file page template 1225, 1262, 1328
exchanging data 951, 956 file server, redundancy 319
Execute SQL function 945 files
exit kernel command 1115 alternative .ini 1071
exponential notation 431 device history 888
Export to file button 1327 include 212
Export Variable Tags dialog box 490 reconfiguring history 825
exporting trend history 821
results 223 updating server-client 1088
tags 489 fill color
trend data 821 array objects 661
Express Communications Wizard 340 gradient objects 666
caller ID 343 multi-state objects 659
device selection 340 on/off objects 657
I/O Device address 342 threshold objects 664
I/O Device communications selection 341 fill color, objects 657
I/O Device connection schedule 342 fill level 669
I/O Device type 341 fill property (object) 568
introduction 340 filters, custom alarm 743
link to external database 344 Find and Replace dialog box 220
serial device 346 finding objects 586
server selection 340 finding text 220
summary 346 fixed text
TCP/IP address 341 alarm displays 761
external data sources 491 FlexNet license manager 146
external databases, using 937 FlexNet license server 146
floating 146
F fonts
FAQs custom 775
Web Client 1198 properties 773
FastLinx for Mitsubishi form feed in reports 862
defining variable tag names 471 format file (import, export, linking) 493
reserved variable tag names 471 format files 494, 504
tag browser properties 469 formatting
FAT32 file system 235 alarm display 759
field conversion 498 device data 882
Field VQT 453, 455 numeric variables 429
fields Forward button 1331
alarm display 762 Free Hand Line tool 589
alarm soe 766 freehand line properties 590

1379
Index

frequently asked questions group 265

Web Client 1198 grouping
ftp server, redundancy 320 objects 581
functionality limitations 1181 registers 384
groups 266
G groups (areas) 252-253
genies 985, 1277 groups (devices) 875
Genies groups, object 564
and substitutions 991 GUI
creating 986 Library controls 94
opening 990, 1002 Guidelines Setup dialog box 546
substitutions for 986 guidelines, object alignment 545
using 988
Goto Object dialog box 586 H
gradient color 593, 597, 602 Hardware Alarms button 1245, 1332
gradient direction 593, 597, 602 hardware alarms, debugging 1091
gradient objects fill color 666 Help button 1332
graphics objects, hiding 1009 help kernel command 1116
graphics pages hiding
appearance 535 graphics objects 1009
bitmaps 558 objects 641
color definition 548 hierarchy 896
creating 513 hierarchy, privilege 258
defaults 542 Historian integration 1142
defining colors for 548 preparing variables 1143
displaying tags 702 history
environment 540 device 888
events 538 trend 821
keyboard commands for 537 history files 825
libraries 556 history mode 1326
locating 514 Home button 1331
opening 514 horizontal movement 642
properties 533 HTML file page template 1225, 1262
saving 514 hybrid projects 231
screen resolution 523
sizing 523 I
sliders 678 I/O Device constraints 401
symbols 557 I/O Device data, errors in 864
zooming 555 I/O devices 321
graphics, importing 566 communicating with 321
graphs, trend 817 communications test project 338
Grid Setup dialog box 545 configuring communications 325
grid, alignment of objects 544 device drivers 358

1380
Index

disk devices 363 incremental compilation 1049

Driver Runtime Interface 328 ini kernel command 1116
manual communications configuration 347 input (keyboard commands) 676
memory mode 367 input property (objects) 568
persisted memory mode 368 Insert Function dialog box 219
preparing a device 330 Insert Tag dialog box 218, 679, 681-682
preparing the I/O server 330 Insert Trend dialog box 626
properties 350 inserting variable tags 218, 679, 681-682
setting up communications 329 Integer data type 420
the role of the I/O device 322 interactive alarm list, tab style alarms
the role of the I/O server 322 template 1218, 1221, 1248, 1253, 1259
the role of the protocol 324 Internet Display Client 1086
the transport medium 323 Internet server 1087
time-stamped data 328 interpolation, trend 819
using a proprietary board 337
using a serial board 331 K
using an Ethernet card 335 kernel 1099
I/O Devices kernel commands 1105-1106
debugging 371 cache 1107
reading from 411 cicode 1108
remote multidrop 403 cls 1110
writing to 410 debug 1110
I/O server drivertrace 1112
adding 348 exit 1115
properties 347 help 1116
redundancy for remote devices 407 ini 1116
IFDEF macro, hiding graphics objects 1009 log 1116
import dialog box 560 page driver 1122
importing page general 1117
graphics 566 page memory 1126
variable tags 466 page queue 1126
importing equipment 926 page rdb 1127
importing tags, simultaneous name and field page table 1128
import 463 page table Accum.ReloadError 1129
Include page table Alarm.ReloadError 1129
Library 1277 page table Broadcast 1130
include files 212 page table Cicode 1130
Include project page table CSAtoPSI.Subs 1130
securing 234 page table data.recordset 1131
included projects 212 page table db connection 1131
Included Projects dialog box 214 page table OPCServerConnections 1132
including projects 212 page table PerformanceCounter 1132
incompatible types error 1056 page table Report.ReloadError 1133

1381
Index

page table SQL 1133 locating objects 586

page table Stats 1133 locking objects 581
page table Tran 1134 log files 1092
page table Trend.ReloadError 1137 calculations 1094
page table users 1138 locations 1094
page unit 1138 syslog format 1095
pause 1141 the Crash Handler 1097
shell 1141 time-stamping 1093
stats 1141 tracelog format 1095
syslog 1142 log files, location 61
Kernel Trace Messages 1162 log kernel command 1116
kernel window 1100, 1102 Login button 1332
keyboard commands 537, 675 LogRead field 350
LogWrite field 350
L Long Binary- Coded Decimal data type 420
labels 413, 867 Long data type 420
arguments in 869 long file names (with DDE) 960
defining 871 loop-back test 379
for areas 251 lower control limit 832
languages lower specification limit 834
changing at runtime 1022
LocalLanguage parameter 1021 M
logging in different 1021 management
setting the local language 1021 print 892
Web Client 1193 manipulating objects 577
languages properties 1018 memory mode 367
Last Alarms panel 1245, 1332 Menu Configuration dialog box 701
layout, format file 494 menu configuration tool 1342
level, fill 669 menus 1343
libraries 556 creating 1232, 1268, 1342
licensing 95, 145-146 Metadata 569
limitations methods, storage 823
Cicode functions 1181 Migration Tool 128
functionality 1181 Mirror dialog box 586
line objects 565 mirroring objects 586
linked symbols 556 mode, demo 150
linking modems 395-396
tags 463 monitoring
templates 519 runtime system 1090
links, breaking 465 movement 642
lists, displaying in an alarm 761 horizontal 642
local language 1011 of objects 578
local language databases 1020 properties 567

1382
Index

vertical 644
multi-digital alarms O
adding 710 object alignment 584
multi-dropping 401 grids 544
multi-language projects 1011 guidelines 545
multi-process system object properties 566
running independent servers 1069 disable access 686
multi-state objects fill color 659 object types 589
multidrop remote I/O Devices 403 ActiveX 630
multiple language support for Web Client 1193 buttons 614
non-default languages 1195 Cicode 626
multiple monitors, configuring 1026 ellipse 596
multiple monitors, using 1338 free hand line 589
numbers 614
pasted symbol 628
N polygons 601
Named Filters 747
rectangles 592
naming 898
straight line 591
naming standards 180
symbol sets 617
native 58
text 607
native language 1011
trends 623
native security 265
objects 563
navigation toolbar 1330
3D effects 638
nesting Super Genies 1006
access 683, 686
network DDE 961, 965
access properties 684
network DDE shared application 965
access property 569
network DDE shares 963
aligning 584
Network Page button 1331
appearance 566
network redundancy 312
applying effects 637
network redundancy, configuring 313
copying/pasting 582
networked system, restarting 1084
deleting 580
New Example Project 72
fill color 657
New Project dialog box 195
array objects 661
New Style dialog box 521
gradient objects 666
New Time Synchronization Service 64
multi-state 659
Next button 1331
on/off 657
Normal Mode 1155
threshold objects 664
normal page template 1322
fill level 669
normal tab style page template 1216, 1246
fill property 568
NTFS file system 235
grouping 581
numbers (objects) 614
groups 564
numeric variables 429
horizontal movement property 642
input property 568
keyboard commands 676

1383
Index

line 565 properties 1027

locating 586 runtime operation 1031
locking/unlocking 581 startup on client connection 1032
manipulating 577 supported interfaces 1034
mirroring 586 OPC Data Access Server Tag Browser 474
movement properties 567 OPC item browsing 1032
moving 578, 642 open bracket expected error 1056
pipes 605 Open/Save As dialog box 517
rectangles 593 opening
reshaping 565 Genies 990
resizing 579 SuperGenies 1002
rotating 585 options 546
rotational property 682 output node field 931-932
scaling 567, 650, 654 Override Mode 456, 458, 1155
sliders 568, 679-680
touch commands for 672 P
touch properties 673 page driver kernel command 1122
vertical movement 644 page events 538
visibility 641 page general kernel command 1117
objects types page memory kernel command 1126
pipes 605 Page Properties dialog box 533
objects, library 556 page queue kernel command 1126
occurrence section in tag names 416 page rdb kernel command 1127
ODBC drivers 968-969 Page recompiled against different
ODBC server, using Citect as 974 Variable.DBF 392
OEM character sets 1024 page style, graphics 519
OFS Security updates 115 page table Accum.ReloadError kernel
OFS tag import 475 command 1129
OFS tag import limitations 476 page table Alarm.ReloadError kernel
OID validation 392
command 1129
on/off object fill colour 657
page table Broadcast kernel command 1130
Online Changes 1161
page table Cicode kernel command 1130
OPC
page table CSAtoPSI.Subs kernel command 1130
Alarm and event data 795
page table data.recordset kernel command 1131
OPC AE server 795
page table db connection kernel command 1131
OPC DA server 96, 1026
page table kernel command 1128
client request conversions 1036
page table OPCServerConnections kernel com-
configuration 1027
mand 1132
DCOM settings 1029
page table PerformanceCounter kernel
diagnostics 1033
command 1132
kernel statistics 1034
page table Report.ReloadError kernel
logging 1033
command 1133
mandatory properties 1039
page table SQL kernel command 1133
OPC item browsing 1032

1384
Index

page table Stats kernel command 1133 posting data using DDE 957
page table Tran kernel command 1134 preconfigured pages 1321
page table Trend.ReloadError kernel preconfigured struxureware style pages 1215
command 1137 preconfigured tab style pages 1241
page table users kernel command 1138 prefixes in tag names 415
page templates 518 preparing a project for Web Client
page unit kernel command 1138 deployment 1180
pages 1231, 1267, 1340 Previous button 1331
splash 522 print management 892
startup 522 Print Page button 1332
Pages printer devices 873
Open 114 format 882
pages, preconfigured 1321 printing
pages, preconfigured struxureware style 1215 project details 201
pages, preconfigured tab style 1241 trend data 820
PageTabs Library Control Genie 1287 privilege hierarchy 258
paging, alarms 63 privilege/area combinations 247, 258
parameter queries 979 privileged user 1228, 1264, 1335
Parent Page button 1331 privileges, using areas with 260
Pareto charts 834 process analyst page template 1224, 1260
Paste to clipboard button 1327 process capability 831
pasted symbol objects 628 process variation 830
pasting objects 582 project restoration and security 265
path definitions 826 Project tag mismatch detected 392
path substitution 825 project upgrades, read-only 238
pause kernel command 1141 projectDBF 981
Pelco 73 projects
performance 382, 1072 backing up 206
Performance Enhancements 74 compiling 1047
periods, specifying for events 799 copying 200
Permission Entry dialog 235 editing properties 197
persisted I/O memory mode 368 hybrid 231
persistence 368 including 212
pipe arrangements 605 multi-language 1011
pipe objects 605 printing details 201
Plot trend button 1327 read-only 235
plots, in reports 862 restoring 211
point count, independent 147 projects, creating 1227, 1263, 1335
polygon objects 601 properties
polygon properties 602 3D effects 638
polylines, drawing 601 ellipses 597
ports properties 349 fill level 669
post compile commands 75 font 773

1385
Index

freehand line 590 redundancy

movement 642 disk I/O devices 365
object 566 Redundancy
object access 684 scheduler 1162
object visibility 641 Redundancy Engine 1163
page 533 redundancy, alarms server 315
pipe 606 redundancy, file server 319
polygon 602 redundancy, ftp server 320
rectangles 593 redundancy, network 312
rotational 682 redundancy, servers 312
scaling 650, 654 referencing as strings 429
slider 679 registers, grouping 384
straight lines 591 remapping
text 607-611, 613 variables 385
touch 673 repeat action 1172
variable tags 422 replacing results 225
vertical movement 644 replacing text 220
writing to alarm 782 reports 855
proprietary board drivers, debugging 379 communication errors 863
proprietary boards 337 configuring 855
protocol drivers form feed 862
debugging 377 I/O Device data errors 864
protocols plots 862
device communications 324 running 858
protocols, debugging 371 suppressing 865
trend data 862
Q triggers for 859
QUAL_BAD Substatus 445 reserved names 180
QUAL_EXT Substatus 447 reserved variable tag names 427
QUAL_GOOD Substatus 447 reserved words 427
QUAL_UNCR Substatus 446 reshaping objects 565
Quality tag element 444 resizing objects 579
queries, parameter 979 restarting the system 1082
restoring projects 211
results
R
exporting 223
range markers 1325
replacing 225
read-only projects 235
results list (Find and Replace) 222
effects on project 236
role 266
reading from I/O Devices 411
Rotate dialog box 585
reading tags 453
rotating objects 585
REAL data type 420
rotational property 682
rectangle objects 592-593
rows, deleting 978
RTF file page template 1225, 1262

1386
Index

running Scheduler interface 1147

a system 1068 Scheduler, backup 1160
events 799 Scheduler;configuring
reports 858 including 1166
running independent servers 1069 SchedulerImaintaining schedules 1152
runtime schedules, specifying 409
changing languages at 1022 scheduling
Runtime communications 409
views 1148 screen resolution and graphics pages 523
runtime configuration 1069, 1087 screen sizing examples 524
running individual processes 1069 search coverage, specifying 221
runtime information 1099 searches, troubleshooting 229
Runtime only environment 274, 288 searching text 220
runtime security 241 securing
runtime system include projects 234
monitoring and debugging 1090 top-level projects 232
Runtime Transition Manager 1162, 1164 security 58, 265, 1160
include projects 234
S MS Office 960
sample period 809 read-only projects 235
scale defaults 1327 runtime 241
scale markers 1325 specifying requirements for 247, 258
scaling objects 567, 650, 654 top-level projects 232
scan time, page 533 Send Backwards command 583
schedule Send to Back command 583
adding, operator 1150 serial board 331
Scheduler 1147, 1161, 1168, 1173 serial boards 333
backup 1160 serial communications 331, 335-336
daylight saving 1149 using a COM port 331
delay using a serial board 331
states 1171 using an Ethernet card 335
demand responce 1172 serial port loop-back cable 381
equipment states 1168 serial port loop-back test 379
inheritance 1154 server-client file updates 1088
operators 1147 server names, reserved 180
overlapping entries 1153 server redirection 1070
redindancy 1161 server redundancy overview 313
security 1160 services, starting network DDE 961
special days 1174 Set span button 1326
time synchronizatiion 1165 SetLanguage() function 1011, 1022
tree view 1148 shares, DDE 964
views 1148 shell kernel command 1141
Scheduler for Engineers 1159 shortform notation 432
size, calculating array 434

1387
Index

sizing substitutions
graphics pages 523 defining for Super Genies 993
objects by scaling 650 path 825
slider property 568 string 871
sliders 678, 682 summary display, alarms 772
Snap to Grid command 544 Super Genies
SOE areas 1006
events, alarm 790 arrays and 1004
software licensing 95, 145 arrays offsets 1005
software update 97 associations 1007
span markers 1326 associations for 994
spc page template 1225, 1261 constants and 1004
Special Days nesting 1006
Engineer 1156 substitutions for 993
Operator 1156 support 33
specifying supported methods 1044
schedule 409 suppressing reports 865
search coverage 221 Swap Color dialog box 552
splash page 522 symbol set objects 617
SQL database devices 873 symbols 557
format 884 syntax, ODBC 969
SQL databases 938 syslog format 1095
squares, drawing 592 syslog kernel command 1142
starter project 1227, 1263 system
starting network DDE services 961 running a 1068
startup configuration 1069, 1087 system tuning 1072
startup page 522
state properties 1168 T
states tab menus, default 1242
equipment 1165 tables, displaying, in alarms 761
statistical control 831 Tabs genie library control 1294
statistical process control (SPC) 829 tag
stats kernel command 1141 controlling 456, 458
storage method, trend data 823 element 441
storage, calculating disk 823 naming 414
straight line objects 591 overriding 456, 458
straight line properties 591 tag-based driver data validation 392
STRING 420 tag browser
string arrays 434 FastLinx for Mitsubishi 469
string substitution 871 OPC Data Access Server 474
structured query language (SQL) 939 tag browsing 438-441
commands 945 tag data types 420
times and dates 946 tag database, connecting to 956
structured tag names 415

1388
Index

tag extensions 77, 441 process analyst page 1224, 1260

tag import spc page 1225, 1261
FastLinx for Mitsubishi 469 struxureware style 1215
OFS 475 tab menus 1242
OFS, limitations 476 tab style 1241
Unity 473 tab style common alarms functionality 1251,
tag item 441 1258
tag name syntax 414 tab style common functionality 1242, 1323
tag names 416, 429 tab style default sort order 759
tag naming, restrictions 427 tab style interactive alarm list 1218, 1221,
tag references 429 1248, 1253, 1259
tag status 461 trend page 1224, 1260, 1323
tag values 453, 455 text
TagGen import template 478 finding and replacing 220
tags in alarm displays 761
colon 449 marking for language change 1012
displaying 702 text objects 607
exporting 489 text properties 607-611, 613
importing 466 three-dimensional (3D) effects 637-638
linking 463 threshold objects fill color 664
names for 415, 417 Time-stamped Alarm Properties 718
supported alarm properties 777 time-stamped alarms
syntax for names 414 adding 710
unused 215 time-stamped analog alarms
using alarm properties as 776 adding 712
writing 449 time-stamped data from field devices 328
tags VQT 449 Time-stamped Digital Alarm Properties 731
TCP/IP drivers time-stamped digital alarms
special options 336 adding 712
TCP/IP drivers, debugging 375 time conversions 980
technical support 33 time scheduler 98
templates 195 Time Synchronization 204-205
Admin Tools page 1328 times
alarm page 1219, 1250, 1256, 1322 in SQL 946
blank tab style page 1216, 1246-1247 specifying for events 799
creating 519, 521 timestamps 1093
CSV_Include 1321 toolbar
file page 1225, 1262, 1328 Alarms 1245, 1332
for graphics pages 518 navigation 1330
Genie substitutions in 991 toolbars, common 1329
linking 519 Tools button 1331
normal page 1322 top-level projects 232
normal tab style page 1216, 1246 touch commands 672
opening 519

1389
Index

touch properties 673 Unsigned Long Integer data type 420

tracelog format 1095 unsupported functionality 1181
Tracelog Trace Messages 1163 unsupported languages 1019
transactions, database 946 unused tags 215
translating local language databases 1020 updating
transport medium 323 server-client files 1088
trend cursor 1326 upper control limit 832
Trend group folder 1328 upper specification limit 834
trend history files 821 user folder, location 61
trend objects 623 user privileges 262
trend page template 1224, 1260, 1323 user records, adding 262
trend tag name 414 user, privileged 1228, 1264, 1335
trend tags users 266
configuring 808 Users dialog box 262
properties 809 using
trend, insert 626 external databases 937
trending data 807 Genies 988
trends serial board 333
creating pages for 818 symbols 557
exporting data for 821 Using Metadata 571
graphs of 817
interpolation 819 V
printing data 820 Valid VQT 453, 455
storage methods 823 validating tag-based driver data 392
trends group 1346 values
Trends Page button 1331 argument 869
Trends Server 299 reading from DDE application 959
triggers string conversion 870
and reports 859 writing to DDE application 958
event 800 variable data, displaying in alarms 761
troubleshooting alarms in projects 788 variable tag name 414
troubleshooting alarmss in projects 788 variable tag names 427
troubleshooting communications 407 variable tags
troubleshooting searches in projects 229 assigning 413
tuning configuring 421
cache 1072 data types 422
system 1072 importing 466
inserting into field 218, 679, 681-682
U properties 422
Unity tag import 473 variables
unlinked symbols 556 environment 540
unlocking objects 581 remapping 385
Unsigned data type 420 variation, process 830

1390
Index

vertical movement 644 XP style buttons 615

vertical sliders properties 680 XRS control charts 832
viewing
plant areas 254 Z
visibility 641 Zoom buttons 1327
Vista compatibility 1069 zooming 555

W
web-based help 72
Web Client 1177
configuring a deployment 1184
creating a deployment 1185
default languages 1193
deleting a deployment 1192
deploying a project 1187
displaying a deployment 1190
editing a deployment 1191
frequently asked questions 1198
functionality limitations 1181
getting started 1179
implementing non-default langauges 1195
introduction 1177
multiple language support 1193
preparing a project for deployment 1180
preparing user files for delivery 1065
setting up a system 1179
system architecture 1177
updating a deployment 1192
using a different language to the locale set-
ting 1194
Web Deployment Preparation tool 1183
Web Deployment Preparation tool 1183
Windows security 265
Windows user security 265
Windows Vista compatibility 1069
writing
to alarm properties 782
to I/O Devices 410
writing tags 455

X
XML DataSource Schema 451
XML template, TagGen 478

1391
Index

1392

Setting Up The Darktrace Appliance 1 PDF
100% (1)
Setting Up The Darktrace Appliance 1 PDF
10 pages
Citect SCADA Cicode 2016 - Study Guide
No ratings yet
Citect SCADA Cicode 2016 - Study Guide
13 pages
Vijeo Citect Technical Reference
0% (1)
Vijeo Citect Technical Reference
555 pages
CitectSCADA Cicode Reference
100% (2)
CitectSCADA Cicode Reference
1,355 pages
Tbii Training
100% (2)
Tbii Training
79 pages
EMSP009 03 C Eterracontrol Scada DB Alstom 2011.03.07
No ratings yet
EMSP009 03 C Eterracontrol Scada DB Alstom 2011.03.07
16 pages
HCIA-Access V2.5 Training Material
100% (1)
HCIA-Access V2.5 Training Material
933 pages
Vijeo Citect Diagnostics and Troubleshooting V7.2 R1 - VJC1093
No ratings yet
Vijeo Citect Diagnostics and Troubleshooting V7.2 R1 - VJC1093
236 pages
Vijeo Citect Customisation and Design V7.2 R1 - VJC109370-02-0
No ratings yet
Vijeo Citect Customisation and Design V7.2 R1 - VJC109370-02-0
212 pages
Installation Guide PDF
No ratings yet
Installation Guide PDF
91 pages
CitectSCADA Installation Guide
No ratings yet
CitectSCADA Installation Guide
64 pages
Vijeo Citect User Guide
100% (1)
Vijeo Citect User Guide
1,108 pages
CitectSCADA User Guide
No ratings yet
CitectSCADA User Guide
733 pages
Citect SCADA Installation Guide
No ratings yet
Citect SCADA Installation Guide
64 pages
PowerSCADA Expert 7.30 Installation Guide
No ratings yet
PowerSCADA Expert 7.30 Installation Guide
59 pages
Citect-Quickstart Tutorial Programming
100% (1)
Citect-Quickstart Tutorial Programming
67 pages
Vijeo Citect Architecture & Redundancy V7.2 R1 - VJC109330-02
No ratings yet
Vijeo Citect Architecture & Redundancy V7.2 R1 - VJC109330-02
244 pages
Vijeo Citect Cicode Reference
No ratings yet
Vijeo Citect Cicode Reference
1,284 pages
Vijeo Cicode Course v7
100% (2)
Vijeo Cicode Course v7
175 pages
Alarm Hiding DOC PCS7 V90SP1 en
No ratings yet
Alarm Hiding DOC PCS7 V90SP1 en
36 pages
Wincc 7 2 Working With Wincc PDF
No ratings yet
Wincc 7 2 Working With Wincc PDF
2,216 pages
Ge Cimplicity: Installation Checklist Document Release Date: March 26, 2019
No ratings yet
Ge Cimplicity: Installation Checklist Document Release Date: March 26, 2019
21 pages
Sicam SCC Manual
No ratings yet
Sicam SCC Manual
534 pages
Remote Desktop Services With Vijeo Citect 2015
No ratings yet
Remote Desktop Services With Vijeo Citect 2015
41 pages
SYS600 - Communication Programming Interface
No ratings yet
SYS600 - Communication Programming Interface
86 pages
CoDeSysVisualization ABB
No ratings yet
CoDeSysVisualization ABB
568 pages
Siemens Simatic S 7 300 - 400 - Working With STEP 7
100% (14)
Siemens Simatic S 7 300 - 400 - Working With STEP 7
110 pages
Simatic Manager Software
100% (1)
Simatic Manager Software
18 pages
Designing Ethernet/Ip Machine/Skid Level Networks: Rev 5058-Co900D
No ratings yet
Designing Ethernet/Ip Machine/Skid Level Networks: Rev 5058-Co900D
33 pages
Pcs 7
No ratings yet
Pcs 7
34 pages
SYS 600C Users Guide PDF
No ratings yet
SYS 600C Users Guide PDF
62 pages
Basic Programming Simatic S7-300
No ratings yet
Basic Programming Simatic S7-300
41 pages
SIMATIC PROFINET System Description PDF
100% (1)
SIMATIC PROFINET System Description PDF
182 pages
SCE Training Curriculum TIA
100% (1)
SCE Training Curriculum TIA
57 pages
SYS600 Security Guide
No ratings yet
SYS600 Security Guide
59 pages
WinCC V5 Manual Getting Started
No ratings yet
WinCC V5 Manual Getting Started
118 pages
04.licenciamiento Del MicroSCADA
No ratings yet
04.licenciamiento Del MicroSCADA
10 pages
Alarm Management Siemens Welschen
No ratings yet
Alarm Management Siemens Welschen
41 pages
Hmi Basic Panels Getting Started en-US en-US PDF
No ratings yet
Hmi Basic Panels Getting Started en-US en-US PDF
72 pages
ps7gs1 B
No ratings yet
ps7gs1 B
192 pages
CPU 410 en-US en-US
No ratings yet
CPU 410 en-US en-US
422 pages
Introduction Workbook Training Manual: SCADA Expert Vijeo Citect 2015
No ratings yet
Introduction Workbook Training Manual: SCADA Expert Vijeo Citect 2015
42 pages
Vijeo Citect - Project Development
No ratings yet
Vijeo Citect - Project Development
342 pages
SCADA
No ratings yet
SCADA
91 pages
SYS600 - Installation and Administration
No ratings yet
SYS600 - Installation and Administration
208 pages
WinCC Communication en-US en-US
No ratings yet
WinCC Communication en-US en-US
760 pages
Training Catalog
No ratings yet
Training Catalog
16 pages
Manual_SICAM_8_Applications-Communication_EN_V06
No ratings yet
Manual_SICAM_8_Applications-Communication_EN_V06
152 pages
Manual For Siemens S300 & S400
No ratings yet
Manual For Siemens S300 & S400
238 pages
WINCC Runtime Professional S7-Graph Overview and PLC Code Viewer
No ratings yet
WINCC Runtime Professional S7-Graph Overview and PLC Code Viewer
35 pages
Simatic Manager Software: Siemens
No ratings yet
Simatic Manager Software: Siemens
18 pages
CitectSCADA User Guide
No ratings yet
CitectSCADA User Guide
1,100 pages
CitectSCADA 7.20 User Guide-1
No ratings yet
CitectSCADA 7.20 User Guide-1
100 pages
CitectSCADA User Guide
No ratings yet
CitectSCADA User Guide
1,100 pages
CitectSCADA Cicode Reference
No ratings yet
CitectSCADA Cicode Reference
1,355 pages
Installation Guide
No ratings yet
Installation Guide
89 pages
Installation Guide
No ratings yet
Installation Guide
64 pages
Vijeo Citect 7.40 User Guide
67% (3)
Vijeo Citect 7.40 User Guide
1,419 pages
Vijeo Citect User Guide
No ratings yet
Vijeo Citect User Guide
1,509 pages
PELCO Camera Integration Guide PDF
No ratings yet
PELCO Camera Integration Guide PDF
65 pages
PELCO Camera Integration Guide
No ratings yet
PELCO Camera Integration Guide
65 pages
CitectVBA Reference Guide
No ratings yet
CitectVBA Reference Guide
197 pages
How To C Chat Server
No ratings yet
How To C Chat Server
19 pages
Telecommunication Networks 15B11EC611: Dr. Bhagirath Sahu Assistant Professor, JIIT, Noida
No ratings yet
Telecommunication Networks 15B11EC611: Dr. Bhagirath Sahu Assistant Professor, JIIT, Noida
26 pages
8259A Programmable Interrupt Controller (8259A/8259A-2) : (See Packaging Spec., Order 231369)
No ratings yet
8259A Programmable Interrupt Controller (8259A/8259A-2) : (See Packaging Spec., Order 231369)
35 pages
Log
No ratings yet
Log
10 pages
Computer intro Ques final (1)
No ratings yet
Computer intro Ques final (1)
16 pages
HandBook FortigateVM Install-54
No ratings yet
HandBook FortigateVM Install-54
67 pages
CMOS Battery Presentation
No ratings yet
CMOS Battery Presentation
18 pages
From Chapter 1 of Distributed Systems Concepts and Design, 4 Edition
100% (1)
From Chapter 1 of Distributed Systems Concepts and Design, 4 Edition
49 pages
FP6D4 P1
No ratings yet
FP6D4 P1
42 pages
Android Runtime: Made By-Aastha Gaba
No ratings yet
Android Runtime: Made By-Aastha Gaba
10 pages
Manual For Buffalo
No ratings yet
Manual For Buffalo
132 pages
Spectre Meltdown Advisory
No ratings yet
Spectre Meltdown Advisory
5 pages
RDM2020 1 PDF
No ratings yet
RDM2020 1 PDF
1,319 pages
Download
No ratings yet
Download
9 pages
Cisco Aaa Case Study Overview
No ratings yet
Cisco Aaa Case Study Overview
16 pages
Factsheet Dormakaba Desktop Reader 9108 en PDF
No ratings yet
Factsheet Dormakaba Desktop Reader 9108 en PDF
2 pages
Scapy
No ratings yet
Scapy
105 pages
Protocols Notes) Basic Networking Interview Questions & Answers 1. Define Network?
No ratings yet
Protocols Notes) Basic Networking Interview Questions & Answers 1. Define Network?
99 pages
User Manual: Modbus Slave / M-Bus Master - Converter
No ratings yet
User Manual: Modbus Slave / M-Bus Master - Converter
30 pages
EX2200-C Ethernet Switch Datasheet
No ratings yet
EX2200-C Ethernet Switch Datasheet
8 pages
" Music Player Using Python": Project Report On
No ratings yet
" Music Player Using Python": Project Report On
38 pages
Dge-528t B1 Manual V3.00 (WW)
No ratings yet
Dge-528t B1 Manual V3.00 (WW)
29 pages
USB Multi-Role Device Design by Example: John Hyde
No ratings yet
USB Multi-Role Device Design by Example: John Hyde
121 pages
MNFST
No ratings yet
MNFST
22 pages
Computer Networks Application Layer Notes
No ratings yet
Computer Networks Application Layer Notes
23 pages
Dream Studio
No ratings yet
Dream Studio
16 pages
Assignment 5 Os
No ratings yet
Assignment 5 Os
11 pages
7.1.1 Administrator's Reference AIX
No ratings yet
7.1.1 Administrator's Reference AIX
1,718 pages