Version 7.

Cicode Reference Guide

July 2007
DISCLAIMER
Citect Pty. Ltd. makes no representations or warranties with respect to this manual and, to the maximum extent permitted by law, expressly limits its
liability for breach of any warranty that may be implied to the replacement of this manual with another. Further, Citect Pty. Ltd reserves the right to
revise this publication at any time without incurring an obligation to notify any person of the revision.

COPYRIGHT
© Copyright 2007 Citect Pty. Ltd. All rights reserved.

TRADEMARKS
Citect Pty. Ltd has made every effort to supply trademark information about company names, products and services mentioned in this manual.

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

IBM, IBM PC and IBM PC AT are registered trademarks of International Business Machines Corporation.

MS-DOS, Windows, Windows NT, Microsoft, and Excel are either registered trademarks or trademarks of Microsoft Corporation in the United States
and/or other countries.

DigiBoard, PC/Xi and Com/Xi are trademarks of Digi International Inc..

Novell, Netware and Netware Lite are are either registered trademarks or trademarks of Novell, Inc. in the United States and other countries..

dBASE is a trademark of dataBased Intelligence, Inc.

All other brands and products referenced in this document are acknowledged to be the trademarks or registered trademarks of their respective holders.

GENERAL NOTICE
Some product names used in this manual are used for identification purposes only and may be trademarks of their respective companies.

July 2007 edition for CitectSCADA Version 7.0

Manual Revision Version 7.0.

Contact Citect today at www.citect.com

OCEANIA +61 2 9496 7300, NORTH AMERICA +1770 521 7511, LATIN AMERICA +1770 521 7511, AFRICA +27 11 699 6600,
EUROPE +31 71 576 1550, MIDDLE EAST +31 71 576 1550, GREATER CHINA +86 21 6886 3799, NORTH ASIA +65 6866 3712,
SOUTH EAST ASIA +65 6866 3712, INDIA +65 6866 3712.
Contents

Introducing Cicode
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Using Cicode Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Part I Using Cicode

Chapter 1 Using Cicode Commands

Setting Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Performing Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Using Multiple Command Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Using Include (Text) Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Getting Runtime Operator Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 2 Using Cicode Expressions

Using Cicode Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Displaying Data Using Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Decision-Making . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Logging Expression Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Triggering Events Using Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 3 Using Cicode Functions

Calling Functions from Commands and Expressions . . . . . . . . . . . . . . . . . . . . . . . . 15
Triggering Functions via Runtime Operator Input . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Evaluating Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Combining Functions with Other Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Passing Data to Functions (Arguments) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Using String Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
String assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Using the Caret Escape Sequence Character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Using Multiple Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Using Numeric Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Using Variable Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Using Operator Input in Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Returning Data from Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
iv Contents

Chapter 4 Working with Commonly Used Functions

Alarm Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Page Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Keyboard Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Report Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Time/date Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 5 Writing Functions

Cicode Function Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Function Uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Writing Groups of Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Cicode Function Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Creating a Function Outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Pseudocode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Using Comments in Cicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Using Comments for Debugging Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Following Cicode Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Cicode Function Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
End of line markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Function Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Declaring the Return Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Declaring Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Naming Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Function Argument Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Declaring Argument Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Naming Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Setting Default Values for Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Returning Values from Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 6 Using Variables

Declaring Variable Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Declaring the Variable Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Naming Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Setting Default Variable Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Using Variable Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Using Database Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Chapter 7 Using Arrays

Declaring Array Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Declaring the Array Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Naming Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
 Contents v

Declaring the Variable Array Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Setting Default (Initial) Array Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Passing Array Elements as Function Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Using One-dimensional Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Using Two-dimensional Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Using Three-dimensional Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Using Array Elements in Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Using the Table (Array) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 8 Using Cicode Macros

IFDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
IFDEFAdvAlm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
IFDEFAnaAlm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
IFDEFDigAlm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Macro Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 9 Converting and Formatting Cicode Variables

Converting Variable Integers to Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Converting Real Numbers to Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Converting Strings to Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Converting Strings to Real Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Formatting Text Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Escape Sequences (String Formatting Commands) . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 10 Working with Operators

Using Mathematical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Using Bit Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Using Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Using Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Order of Precedence of Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Chapter 11 Working with Conditional Executors

Setting IF ... THEN Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Using FOR ... DO Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Using WHILE ... DO Conditional Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Nested Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Using the SELECT CASE statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Chapter 12 Performing Advanced Tasks

Handling Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
How CitectSCADA Executes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
vi Contents

Multitasking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Foreground and background tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Controlling tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Pre-emptive multitasking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Chapter 13 Editing and Debugging Code

The Cicode Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Starting the Cicode Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Changing the default Cicode Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Creating Cicode files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Creating functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Saving files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Opening Cicode files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Deleting Cicode files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Finding text in Cicode files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Compiling Cicode files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Viewing Cicode compile errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Cicode Editor Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Docking the Windows and Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Displaying the Editor Options Properties dialog . . . . . . . . . . . . . . . . . . . . . . 85
Windows and Bars Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Toolbar options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Window options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Viewing Editor windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Options Properties Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Language Formatter Properties Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Debugging Cicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Using debug mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Debugging functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Debugging functions remotely . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Using breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Inserting or removing breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Enabling/disabling breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Stepping through code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Chapter 14 Using Cicode Programming Standards

Variable Declaration Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Variable Scope Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Variable Naming Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Standards for Constants, Variable Tags, and Labels . . . . . . . . . . . . . . . . . . . . . . . . 99
Formatting Simple Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Formatting Executable Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Formatting Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
 Contents vii

Cicode Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Formatting Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Function Naming Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Modular Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Defensive Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Function Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Debug Error Trapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Part II Function Categories

Chapter 15 Cicode Function Categories

Accumulator Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
ActiveX Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Alarm Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Clipboard Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Cluster Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Color Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
DDE Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Device Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Display Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
DLL Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Error Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Event Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Form Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Format Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
FTP Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
FuzzyTech Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Group Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
I/O Device Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Keyboard Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Mail Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Math/Trigonometry Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Page Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Plot Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Report Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Security Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
SPC Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
SQL Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
String Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Super Genie Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
viii Contents

Table (Array) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Tag Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Task Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Time/Date Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Trend Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Window Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Part III Functions Reference

Chapter 16 Functions Reference

Part IV Technical Reference

Chapter 17 Cicode Errors

Hardware/Cicode Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
Cicode and General Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
MAPI Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833

Chapter 18 Browse Function Field Reference

Browse Function Field Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835

Index 841
 Introducing Cicode

Cicode is a programming language designed for use in CitectSCADA to monitor

and control plant equipment. It is a structured language similar to Visual Basic
or 'C'. You need no previous programming experience to use it.
Using Cicode, you can access all real-time data (variables) in the CitectSCADA
project, and all CitectSCADA facilities: variable tags, alarms, trends, reports, and
so on. You can use Cicode to interface to various facilities on the computer, such
as the operating system and communication ports. Cicode supports advanced
features including pre-empted multitasking, multi threads, and remote
procedure calls.

Getting Started
Use the following sections as a quick start to using Cicode in your CitectSCADA
projects:
„ Cicode can be stored in procedures called functions for multiple reuse and
centralized maintenance. For details, see Using Cicode Files.
„ Cicode can be typed directly into command fields in online CitectSCADA
forms. For details, see Using Cicode Commands.
„ Cicode expressions are used to display and log data for monitoring and
analysis, and to trigger various elements in your system, such as alarms,
events, reports, and data logging. For information on using expressions, see
Using Cicode Expressions.
„ A Cicode function is a small program, a collection of statements, variables,
operators, conditional executors, and other functions. A Cicode function can
perform complex tasks and give you access to CitectSCADA graphics pages,
alarms, trend data, and so on. For information on using functions, see the
section titled Using Cicode Functions. Cicode has many pre-defined
functions that perform a variety of tasks. For details on commonly used
functions, see the section titled Working with Commonly Used Functions.
Where system functionality cannot be achieved with in-built functions, you
can write your own functions. See Writing Functions.
„ The Cicode Editor is the code editing tool provided with CitectSCADA for
the writing, editing and debugging of your Cicode code. For details, see The
Cicode Editor.
See Also Performing Advanced Tasks
Using Cicode Programming Standards
2

Using Cicode Files

You write all your Cicode functions in Cicode source files, stored on your hard
disk. Cicode files are identified by having a *.CI extension.
To minimize potential future problems with maintaining your Cicode files, you
should adopt a programming standard as early as possible (see Using Cicode
Programming Standards). Be sure to maintain structured Cicode files, by
logically grouping your Cicode functions within the files, and by choosing
helpful descriptive names. For details about modular programming methods,
see Modular Programming. For details about using and debugging Cicode
functions, see Formatting Functions and Debugging Cicode respectively.
When you compile your CitectSCADA project, the compiler reads all the
functions in your Cicode source files. Your system can then use these functions
in the same way as it uses in-built functions. You can use as many Cicode files as
required. Cicode files reside in the same directory as your CitectSCADA project.
When you back up your project, all Cicode source files in the project directory
are also backed up.
See Also The Cicode Editor
Creating Cicode files
Opening Cicode files
 Part I
Using Cicode
 Chapter 1: Using Cicode Commands

Cicode commands extend the control element of a CitectSCADA control and

monitoring system. You use commands to control your CitectSCADA system
and therefore the processes in your plant.
Each command has a mechanism to activate it. Commands can be issued
manually, through an operator typing a key sequence, or by clicking on a button
(or object) on a graphics page. You can also configure commands to execute
automatically:
„ When an operator logs into or out of the runtime system
„ When a graphics page is displayed or closed
„ When an alarm is triggered
„ In a report
„ When an event is triggered
To define a Cicode command, you enter a statement (or group of statements) in
the command field (Input category) for an object.
Each statement in a command usually performs a single task, such as setting a
variable to a value, calculating a value, displaying a message on the screen, or
running a report. For information on using variables, see the section titled Using
Variables.
If you want to evaluate a condition, like checking the state of your plant rather
than perform an action or command upon your plant, you should use an
expression instead. See the section titled Using Cicode Expressions.
See Also Using Cicode Programming Standards

Setting Variables
You can set a Variable in CitectSCADA within a Command field, an Expression
field, or in a Cicode Function, by using the mathematical 'equals' sign ( = )
assignment operator. The value on the right is assigned (set) to the variable on
the left, as shown in the following Cicode example :
<VAR_TAG> = Val;
where:
<VAR_TAG> is the name of the variable, and Val is the value being assigned to the
variable.
6

Examples
To set a digital variable (named BIT_1) to ON (1), use the command:
BIT_1 = 1;
To set a digital variable (named BIT_1) to OFF (0), use the command:
BIT_1 = 0;
To set a digital variable (named B1_PUMP_101_M) to ON (1), use the command:
B1_PUMP_101_M = 1;
To set a digital variable (named B1_PUMP_101_M) to OFF (0), use the command:
B1_PUMP_101_M = 0;
To set an analog variable (named B1_TIC_101_SP) to a value of ten (10), use the
command:
B1_TIC_101_SP = 10;
You can copy a variable to another by assigning (setting) the value of a variable
to the value of another variable, for example:
B1_PUMP_101_COUNT = B1_PUMP_101_CLIMIT;
The value of B1_PUMP_101_COUNT is set to the value of
B1_PUMP_101_CLIMIT only when that command is issued.
Note: The value of B1_PUMP_101_CLIMIT could change immediately after, but
B1_PUMP_101_COUNT remains unchanged and storing the original value,
until this command is issued again.

Performing Calculations
Mathematical calculations can be performed between variables in a Cicode
statement. For example:
B1_TIC_101_SP = B1_TIC_101_PV + B1_TIC_102_PV - 100;
When this command is executed, the variable B1_TIC_101_SP is set to a value
that is the sum of variables B1_TIC_101_PV and B1_TIC_102_PV minus 100.

Using Multiple Command Statements

A single statement in a Cicode command usually performs a single task. When
the CitectSCADA runtime system is in operation, the statement executes
whenever the command is requested. For example, if the statement is linked to a
keyboard command, the task is performed when an operator presses the
keyboard key defined as that command.
 7

To perform several tasks at the same time, you combine statements in a

command property:
B1_PUMP_101_COUNT = B1_PUMP_101_CLIMIT;
BATCH_NAME = "Bread";
B1_TIC_101_SP = 10;
The example above uses three statements, separated by semi-colons ( ; ). The first
statement sets the variable B1_PUMP_101_COUNT to the value of the variable
B1_PUMP_101_CLIMIT; the second statement sets the variable BATCH_NAME
to the string "Bread"; and the third statement sets the variable B1_TIC_101_SP to
10. Each statement is executed in order.
Note: Separate each statement in a command with a semicolon (;); if you don’t,
CitectSCADA will not recognize the end of a statement, and errors will result
when the project is compiled.
The number of statements you can enter in a command property is limited only
by the size of the field. However, for clarity, don’t use too many statements; enter
the statements into an Include File or write a Cicode Function. You then refer to
the include file or call the function in the command property field.

Using Include (Text) Files

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 the commands or expressions.
An include file is a separate and individual ASCII text file containing only one
sequence of CitectSCADA commands or expressions that would otherwise be
too long or complicated to type into the Command or Expression field within
CitectSCADA. The include file name is entered instead, and the whole file is
activated when called.
Note: Be careful not to confuse include files and included projects. Include files
contain CitectSCADA commands and/or expressions and are used as
substitutions in a CitectSCADA command or expression property field.
Included projects are separate (usually smaller) CitectSCADA projects that can
be included in another CitectSCADA project so that they appear together as one
project.
When you compile the project, the commands (or expressions) in the include file
are substituted for the property field, just as if you had typed them directly into
the field.
Use a text editor such as Notepad to create the text file.
Enter the name of the include file (either upper- or lower case) in the property, in
the following format:
8

@<filename>
where <filename> is any valid DOS file name. Note that the bracket characters
(< >) are part of the syntax.
You can use include files with most properties (except record names), but they
are most commonly used for commands and expressions, for example:
„ Key sequence: F5 ENTER
„ Command: @<setvars.cii>
In the above example, the setvars.cii include file would contain commands to
be substituted for the Command property when you compile your project, for
example:
PV12 = 10;
PV22 = 20;
PV13 = 15;
PV23 = 59;
PageDisplay("Mimic");
Notes
„ The include file name can contain a maximum of 64 characters, or 253
characters including a path, and can consist of any characters other than the
semi-colon (;) or the single quote('). You do not need to include the .cii
extension, but if the file is not in the project directory, you must enter the full
path to the file. If the file is not in the project directory, it will not be backed
up with the Backup facility.
„ Don’t try to open an include file within the Cicode Editor.

Getting Runtime Operator Input

You can define a keyboard command as a key sequence, to perform a specific
task each time the key sequence is pressed, for example:
„ Key sequence: F2 ENTER
„ Command: B1_TIC_101_SP = 10;
 9

A key sequence can include provision for the operator to enter data. In the
following example, the operator can set the value of the variable B1_TIC_101_SP:

The operator issues the command by pressing the F2 key, up to three characters,
and the Enter key. The three character sequence (identified by the three hash (#)
characters) is called an argument. The argument is passed into the command (as
Arg1) when the command is completed (when the operator presses the Enter
key).
The operator might type:

The value 123 is passed to the command, and B1_TIC_101_SP is set to 123.
You should always use a specific key (for example, Enter) to signal the end of a
key sequence. If, for example, you use the key sequence F2 ####, the operator
must enter 4 characters for the command to be executed - CitectSCADA waits
for the fourth character. But if you use F2 #### Enter, the operator can enter
between one and four characters as required. The command executes as soon as
the Enter key is pressed.
To use more than one argument in a command, separate the arguments with
commas ( , ):
„ Key sequence: F2 ###,## Enter
„ Command: B1_TIC_101_SP = Arg1; B1_TIC_101_PV = Arg2;
To set both variables, the operator can type:

The values 123 and 18 are passed to the command. B1_TIC_101_SP is set to 123
and B1_TIC_101_PV is set to 18.
10
 Chapter 2: Using Cicode Expressions

Using Cicode Expressions

Cicode expressions are the basic elements of the Cicode language. An expression
can be a constant, the value of a variable tag, or the result of a complex equation.
You can use expressions to display and log data for monitoring and analysis,
and to trigger various elements in your system, such as alarms, events, reports,
and data logging.
You can enter a Cicode expression in any CitectSCADA editor form or graphic
object that contains an expression property. Unlike a command, an expression
does not execute a specific task - it is evaluated. The evaluation process returns a
value that you can use to display information on the screen (for example, as a
bar graph) or to make decisions. The following expression returns a result of 12:
„ Numeric expression: 8 + 4
In the above example, the value of the expression is always a constant (12)
because the elements of the expression are constants (8 and 4).
See Also Displaying Data Using Expressions
Logging Expression Data
Triggering Events Using Expressions
Using Cicode Programming Standards
Using Cicode Files

Displaying Data Using Expressions

In the following example, the value of the expression is the value of the variable
B1_TIC_101_PV. As its value changes, the value of the expression also changes.
You can use this expression to display a number on a graphics page.
„ Numeric expression: B1_TIC_101_PV
As the expression changes, the number also changes.
Expressions can also include mathematical calculations. For example, you can
add two variables together and display the combined total:
„ Numeric expression: B1_TIC_101_PV + B1_TIC_102_PV
In this case, the value of the expression is the combined total. As the value of one
variable (or both variables) changes, the value of the expression changes.
See Also Using Cicode Expressions
12

Decision-Making
Some expressions return only one of two logical values, either TRUE(1) or
FALSE(0). You can use these expressions to make decisions, and to perform one
of two actions, depending on whether the return value is TRUE or FALSE. For
example, you can configure a text object with appearance as follows:
„ On text when: B1_PUMP_102_CMD
„ ON text: Pump Running
„ OFF text: “Pump Stopped”
In this example, if B1_PUMP_102_CMD is a digital tag (variable), it can only
exist in one of two states (0 or 1). When your system is running and the value of
B1_PUMP_102_CMD changes to 1, the expression returns TRUE and the
message "Pump Running" is displayed. When the value changes to 0, the
expression returns FALSE and the message "Pump Stopped" is displayed.
See Also Using Cicode Expressions

Logging Expression Data

You can log the value of an expression to a file for trending, by defining it as a
trend tag:
Trend Tag Name B1_TIC
Expression B1_TIC_101_PV + B1_TIC_102_PV
File Name [log]:B1_TIC

When the system is running, the value of the expression B1_TIC_101_PV +

B1_TIC_102_PV is logged to the file [log]:B1_TIC.
See Also Using Cicode Expressions

Triggering Events Using Expressions

Logical expressions - those that return either TRUE (1) or FALSE (0) -can be used
as triggers.
For example, you might need to log the expression in the above example only
when an associated pump is running.
Trend Tag Name B1_TIC
Expression B1_TIC_101_PV + B1_TIC_102_PV
File Name [log]:B1_TIC
Trigger B1_PUMP_101_CMD

In this example, the trigger is the expression B1_PUMP_101_CMD (a digital

variable tag). If the pump is ON, the result of the trigger is TRUE, and the value
 13

of the expression (B1_TIC_101_PV + B1_TIC_102_PV) is logged. If the pump is

OFF, the result is FALSE, and logging ceases.
See Also Using Cicode Expressions
14
 Chapter 3: Using Cicode Functions

A Cicode function can perform more complex tasks than a simple command or
expression allows. Functions give you access to CitectSCADA graphics pages,
alarms, trend data, and so on.
CitectSCADA has several hundred pre-built functions that display pages,
acknowledge alarms, make calculations, and so on. You can also write your own
functions to meet your specific needs.
See Also Working with Commonly Used Functions
Writing Functions

Calling Functions from Commands and Expressions

You can call a function by entering its name in any command or expression
property. The syntax is as follows:
Command FunctionName ( Arg1, Arg2, ... );

where:
FunctionName is the name of the function
Arg1, Arg2, ... are the arguments you pass to the function

Triggering Functions via Runtime Operator Input

In the following command, the PageNext() function displays the next graphics
page when the Page Down keyboard key is pressed by the Runtime operator.
Key Sequence Page_Down

Command PageNext();

Evaluating Functions
You can use a function in any expression. For example, the AlarmActive()
function returns TRUE (1) if any alarms are active, and FALSE (0) if no alarms
are active. In the following text object, either "Alarms Active" or "No Alarms
Active" is displayed, depending on the return value of the expression.
ON text when AlarmActive(0)

ON Text "Alarms Active"

16

OFF Text "No Alarms Active"

Note: All functions return a value. This value is often just an indication of the
success or failure of the function, and in many cases (e.g. when used in a
command) the return value can be ignored. You must use the parentheses () in
the function name, even if the function uses no arguments. Function names are
not case-sensitive: PageNext(), pagenext() and PAGENEXT() call the same
function.

Combining Functions with Other Statements

In expressions and commands you can use functions alone or in combination
with other functions, operators, and so on.
The following example uses three statements:
Report("Shift"); B1_TIC_101_PV = 10;
Command
PageDisplay("Boiler 1")

Each statement is executed in order. The "Shift" report is started first, the
variable B1_TIC_101_PV is set to 10 next, and finally, the "Boiler 1" page is
displayed.
Functions combine with operators and conditional executors to give you
specific control over your processes, for example, you can test for faulty
conditions and act on them.

Passing Data to Functions (Arguments)

The parentheses ( ) in the function name identify the statement as a function and
enclose its arguments. Arguments are the values or variables that are passed into
the function when it executes.
Note: Some functions (such as PageNext()) do not require any arguments.
However you must include the parentheses ( ) or CitectSCADA will not
recognize that it is a function, and an error could result when the project is
compiled.

Using String Arguments

Functions can require several arguments or, as in the following example, a single
argument:
Command PageDisplay("Boiler 1");

This function displays the graphics page called "Boiler 1". Note that when you
pass a string to a function, you must always enclose the string in double quotes.
 17

You can use the PageDisplay() function to display any graphics page in your
system - in each case, only the argument changes. For example, the following
command displays the graphics page "Boiler 2":
Command PageDisplay("Boiler 2");

You can use the Report() function to run a report (for example, the "Shift"
report) when the command executes:
Command Report("Shift");

The following example uses the Prompt() function to display the message "Press
F1 for Help" on the screen when the command executes:
Command Prompt("Press F1 for Help");

String assignment You can also assign string variables in commands. For example, if
BATCH_NAME is a variable tag defined as a string data type, you can use the
following command to set the tag to the value "Bread":
BATCH_NAME = "Bread";
Note: You must enclose a string in double quotation marks ( " ).

Using the Caret Escape Sequence Character

The caret character ( ^ ) signifies a special instruction in Cicode, called an escape
sequence, primarily used in the formatting of text strings. Escape sequences
include formatting instructions such as new line, form feed, carriage return,
backspace, horizontal and vertical tab-spaces, single and double quote
characters, the caret character, and hexadecimal numbers.
Strings are commonly represented in Cicode between double quote characters ( "
) known as delimiters. If you want the string to contain a double quote character
itself as part of the string, you must precede the double quote character with the
caret character ( ^" ) so that Cicode doesn't interpret the double quote in the
string as the delimiter indicating the end of the string. The caret character is
interpreted as a special instruction, and together with the characters
immediately following it, are treated as an escape sequence instruction. See the
section titled Formatting Text Strings for the list of escape sequences used in
Cicode.
In the following Cicode example, both of these message functions will display
the following message.
18

Message("Info", "P29 has a ^"thermal overload^".", 0);

sCurrentAlmText = "Thermal Overload";
Message("Info", "P29 has a ^""+sCurrentAlmText+"^".", 0);

Using Multiple Arguments

Some functions require several arguments. You must list all arguments between
the parentheses, and separate each argument with a comma ( , ) as in the
following example:
Command Login("Manager", "ABC");

The order of the arguments is important to the operation of any function. The
Login() function logs a user into your runtime system. The first argument (
"Manager" ) indicates the name of the user, and the second argument ( "ABC" ) is
the user's password. If you reverse the order of the arguments, the function
would attempt to login a user called "ABC" - if a user by this name does not
exist, an error message displays.

Using Numeric Arguments

You can pass numbers (integers and floating point numbers) directly to a
function, for example:
Command AlarmAck(2, 35);

Using Variable Arguments

When variables (such as real-time data) are used as arguments, the value of the
variable is passed, not the variable itself. The following example uses the
DspStr() function to display the value of a process variable at AN25:
Command DspStr(25, "TextFont", B1_TIC_101_PV);

In this instance, the value of B1_TIC_101_PV displays. If it is a real-time variable,

the number that displays depends on its value at the time.
Note: Do not use double quotes around variables, e.g. "B1_TIC_101_PV",
otherwise the text string B1_TIC_101_PV displays, not the value of the variable.
 19

Using Operator Input in Functions

You can pass operator input to functions at runtime. For example, you can define
a System Keyboard Command to let the operator select a page:
Key Sequence F10 ######## Enter

Command PageDisplay(Arg1);

When the command executes, the page name is passed to the function as Arg1.
The operator can then display any page, for example:

Returning Data from Functions

All functions return data to the calling statement (a command or expression).
Some functions simply return a value that indicates success or failure of the
function. For example, both the PageNext() and PageDisplay() functions return 0
(zero) if the page displays successfully, otherwise they return an error number.
For most simple applications, you can ignore this return value.
Some functions return data that you can use in an expression or command. For
example, the Date() function returns the current date as a string. To display the
current date on a graphics page, use the following expression in a text object
display value property:
Numeric expression Date();

The following example shows an entry command event for a graphics page,
using a combination of two functions. The FullName() function returns the name
of the user who is currently logged in to the run-time system, passing this name
to the calling function, Prompt(). When the page is opened, a welcome message
displays in the prompt line.
On page entry Prompt("Hello, " + FullName())

For example, if the current user is John Citizen, the message "Hello, John
Citizen" displays.
20
 Chapter 4: Working with Commonly Used
Functions

Cicode has many functions that perform a variety of tasks. Many of these are
used for building complex CitectSCADA systems. The functions you will most
often use are divided into six categories:
„ Alarm Functions
„ Page Functions
„ Keyboard Functions
„ Report Functions
„ Time/date Functions
„ Miscellaneous Functions
See Also Cicode Function Categories

Alarm Functions
You can use alarm functions to display alarms and their related alarm help
pages, and to acknowledge, disable, and enable alarms. You can assign a
privilege to each command that uses an alarm function, to ensure that only an
operator with the appropriate privilege can perform these commands. However,
you should assign privileges to commands only if you have not assigned
privileges to individual alarms.
„ AlarmAck: Acknowledges an alarm. The alarm where the cursor is
positioned (when the command is executed) is acknowledged. You can also
use this function to acknowledge multiple alarms.
„ AlarmComment: Adds a comment to the alarm summary entry at run time.
The comment is added to the alarm where the cursor is positioned when the
command is executed. A keyboard argument passes the comment into the
function. You must ensure that the length of the comment does not exceed
the length of the argument, or an error results.
„ AlarmDisable: Disables an alarm. The alarm where the cursor is positioned
(when the command is executed) is disabled. You can also use this function
to disable multiple alarms.
22

„ AlarmEnable: Enables an alarm. The alarm where the cursor is positioned

(when the command is executed) is enabled. You can also use this function
to enable multiple alarms.
„ AlarmHelp: Displays an alarm help page for the alarm. Each alarm in your
system can have an associated help page. The help page for the alarm at the
position of the cursor (when the command is executed) is displayed.
„ AlarmSplit: Duplicates an entry in the alarm summary display. You can use
this function to add additional comments to the alarm entry.

Page Functions
With the page functions, you can display your graphics pages and the standard
alarm pages.
Note: The following page functions are not supported in the server process in a
multiprocessor environment. Calling page functions from the server process
results in a hardware alarm being raised.
„ PageAlarm: Displays current alarms on the alarm page configured in the
project.
„ PageDisabled: Displays disabled alarms on the alarm page configured in
the project.
„ PageDisplay: Displays a new page on the screen. The Page name or number
is required as an argument. (Use the PageLast() function to go back to the
last page - the page that this new page replaced).
„ PageFile: Displays a file on the file page configured in the project.
„ PageGoto: Displays a new page on the screen. This function is similar to the
PageDisplay() function, except that if PageLast() is called, it does not return
to the last page.
„ PageHardware: Displays hardware alarms on the alarm page configured in
the project.
„ PageLast: Displays the graphics page that was displayed before the current
one. You can use this function to 'step back' through the last ten pages.
„ PageNext: Displays the next graphics page (defined in the Next Page
property of the Pages form).
„ PagePrev: Displays the previous graphics page (defined in the Prev Page
property of the Pages form).
„ PageSummary: Displays summary alarm information on the alarm page
configured in the project.
„ PageTrend: Displays a standard trend page.
 23

Keyboard Functions
Keyboard functions control the processing of keyboard entries and the
movement of the keyboard cursor on the graphics page.
„ KeyBs: Backspaces (removes) the last key from the key command line. You
should use this function with a 'Hotkey' command. It is normally used to
erase keyboard characters during runtime command input.
„ KeyDown: Moves the cursor down the page to the closest animation point
number (AN).
„ KeyLeft: Moves the cursor left (across the page) to the closest animation
point number (AN).
„ KeyRight: Moves the cursor right (across the page) to the closest animation
point number (AN).
„ KeyUp: Moves the cursor up the page to the closest animation point
number (AN).

Report Functions
To run a report by operator action, use the following function:
„ Report: Runs the report on the report server.

Time/date Functions
The following functions return the current date and time:
„ Date: Returns the current date as a string.
„ Time: Returns the current time as a string.

Miscellaneous Functions
„ Beep: Beeps the speaker on the CitectSCADA computer.
„ FullName: Returns the full name of the user who is currently logged in to
the system.
„ InfoForm: Displays the animation information form. This form displays the
real-time data that is controlling the current animation.
„ Login: Allows a user access to the CitectSCADA system.
„ LoginForm: Displays a dialog box to allow a user to log in to the system.
„ Logout: Logs the current user out of the CitectSCADA system.
24

„ Name: Returns the user name of the user who is currently logged in to the
system.
„ Prompt: Displays a message on the screen. The message String is supplied
as an argument to the function.
„ Shutdown: Terminates CitectSCADA. You should always use this function,
or the ShutdownForm() function, to shut down your system.
„ ShutdownForm: Displays a dialog box to allow a user to shut down your
CitectSCADA system.
 Chapter 5: Writing Functions

CitectSCADA is supplied with over 600 pre-built functions. One of these

functions (or several functions in combination) can usually perform most tasks
in your system. However, where system functionality cannot be achieved with
in-built functions, you can write your own functions.
A Cicode function is a small program: a collection of statements, variables,
operators, conditional executors, and other functions.
While you do not have to be an experienced programmer to write simple Cicode
functions, you should not attempt to write large, complex functions unless you
are familiar with computer programming, or have experience with Cicode.
Functions are equivalent to the subroutines of BASIC and assembly language,
and the subroutines and functions used in Pascal and C.
Note: The Cicode Editor is designed specifically for editing and debugging
Cicode functions.
See Also The Cicode Editor
Using Cicode Files

Cicode Function Structure

A function in Cicode can be described as a collection or list of sequential
statements that CitectSCADA can perform (execute) in the logical order that
they exist within the function.
A Cicode function starts with the FUNCTION statement and finishes with the
END statement. All other statements that lie between the FUNCTION and END
statements, will be executed by the function, when called to do so.
A typical Cicode function is structured like the following example:
FUNCTION
FunctionName ( )
! The exclamation point indicates that the rest of this line
contains a comment.
! Further Cicode statements go here, between the function name
and the END.
END
The line immediately following the FUNCTION statement, contains the name of
the function, which is used to identify the function to CitectSCADA. This name
is referred to when the function is called upon (called) to be executed (perform
the statements it contains) by some other event, action, or function in
CitectSCADA.
26

Note: Functions can contain statements that call other functions. These functions
are then executed before returning to the rest of the statements within the calling
function.
The function name always ends with parentheses ( ), which may or may not
contain one or more arguments required by the function. Arguments are
explained in the section titled Function Argument Structure.
All the lines between the function name line and the END statement line contain
the statements that will be executed when the function is called in CitectSCADA.
These statements are executed one at a time in logical order from top to bottom
within the function. For details about function structure, see Formatting
Functions. For details about Cicode function syntax, see Following Cicode
Syntax.
For details about using comments in Cicode and in Cicode functions, see Using
Comments in Cicode.

Function Uses
Cicode functions can have many purposes. Most often, functions are used to
store a common set of commands or statements that would otherwise require
repetitious typing and messy command or expression fields.
Some functions are simple, created to avoid a long command or expression. For
example, the following command increments the variable tag COUNTER:
IF COUNTER < 100 THEN COUNTER =
Command
COUNTER + 1; ELSE COUNTER = 0; END;

This command would be easier to use (and re-use) if it was written as a function
that can be called in the command:
Command IncCounter ( );

To be able to use the function like this, you must write it in a Cicode file, and
declare it with the FUNCTION keyword:
FUNCTION
IncCounter ( )
IF COUNTER < 100 THEN
COUNTER = COUNTER + 1;
ELSE
COUNTER = 0;
END
END
Note the indented code is identical in functionality to the long command above.
By placing the command code inside a function, and using the function name in
the command field as in the previous example, this function need only to be
 27

typed once. It can then be called any number of times, from anywhere in
CitectSCADA that requires this functionality. Because the code exists in the one
location, rather than repeated wherever needed (in potentially many places), it
can be easily maintained (altered if necessary).

Writing Groups of Functions

To perform complex tasks you need careful design. Large, complex functions are
not only more difficult to understand and debug than short functions, but they
can also hide tasks that are common to other activities.
Cicode functions allow a modular approach - the most complex task can be
broken into small functions, each with a single, clear purpose. These small
functions can then be called by other functions, or called directly in commands
and expressions. In fact, any function can call - and be called by - any other
function.
For example, you might need to write a set of functions for handling alarms. To
perform any action on an alarm, you first must know which alarm. You would
identify the alarm in a separate function, and call this function from the other
functions.

Cicode Function Libraries

Cicode functions are stored within cicode files. You can use a separate file for
each stand-alone function, or group several functions together into a common
file. For easy maintenance, you should store functions that perform related tasks
in the same file - for example, store all the functions that act on alarm data in an
Alarms.CI file.
Note: All Cicode files in your project directory will be included when you
compile your project.

Creating a Function Outline

First you must define the purpose of the function group, and create an outline of
the tasks to be performed. The following example shows an outline for a group
of functions that change the threshold values of analog alarms during run time.
The outline describes the workings of the function group, and is written in
pseudocode (also called Program Design Language).
/*
This file contains functions to allow the operator to make runtime
changes to Analog Alarm thresholds.
This file has 4 functions. The master function calls the other
functions.
ChangeAnalogAlarmThresholds ( )
This calls in turn:
28

1:GetVariableTag ( )
Argument:cursor position
Return:name of variable tag at cursor
2:GetAlarmThresholds ( )
Argument:tag name
Return:threshold value of alarm
3:DisplayAlarmThresholds ( )
Argument:threshold value of alarm
Displays threshold values in prompt line
Return:success or failure
*/

Pseudocode
The pseudocode above is a Cicode comment, enclosed between the comment
markers /* and */, and is ignored by the compiler. With pseudocode, you can get
the logic of the function correct in a more readable structure, before you write it
in Cicode syntax, leaving the pseudocode within the finished code as comments.
You should also use comments as file headers at the start of each Cicode file, to
describe the functions in the file - their common purpose, a broad description of
how they achieve that purpose, special conditions for using them, and so on.
You can also use the header to record maintenance details on the file, such as its
version number and date of revision. For example:
/*
** FILE: Recipe Download.Ci
**
** AUTHOR:AJ Smith
**
** DATE: March 1996